@desplega.ai/agent-swarm 2.9.0 → 2.10.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 (453) hide show
  1. package/dist/acp-adapter-bht22g3k.js +16 -0
  2. package/dist/{acp-targets-swxq55dr.js → acp-targets-arrwv4f0.js} +7 -7
  3. package/dist/{actions-pb678g3e.js → actions-y0d2n1c2.js} +102 -21
  4. package/dist/{agent-fs-provision-dmhnc38q.js → agent-fs-provision-tpj7sktd.js} +4 -4
  5. package/dist/{amp-adapter-3pa66q27.js → amp-adapter-vmmnmw8d.js} +2 -2
  6. package/dist/{anthropic-messages-x2cp5fvf.js → anthropic-messages-zdca3gv1.js} +22 -22
  7. package/dist/{app-17d12ev4.js → app-wb7w45dq.js} +6 -3
  8. package/dist/{approval-notifications-h7vd9pmg.js → approval-notifications-7mqr6vbd.js} +8 -5
  9. package/dist/{assistant-t7k39ree.js → assistant-gf60454p.js} +23 -21
  10. package/dist/{boot-args-schema-0gqmkfbe.js → boot-args-schema-qxmd59sr.js} +1 -1
  11. package/dist/{boot-reembed-f064w382.js → boot-reembed-5tmeskj2.js} +1 -1
  12. package/dist/{boot-reembed-n6anc01d.js → boot-reembed-wb44vc3s.js} +1 -1
  13. package/dist/boot-scrub-sweep-25bxhnw4.js +9 -0
  14. package/dist/{boot-seeds-f99fjs5q.js → boot-seeds-nj9za0vk.js} +4 -4
  15. package/dist/{claude-adapter-gvznwxgc.js → claude-adapter-d3krpdyb.js} +7 -7
  16. package/dist/{claude-managed-adapter-pbrbvc64.js → claude-managed-adapter-t8nfgcgz.js} +2 -2
  17. package/dist/{claude-managed-setup-kdxttvc3.js → claude-managed-setup-7y4pwd81.js} +3 -3
  18. package/dist/{claude-sdk-session-0t2teq6n.js → claude-sdk-session-d138zy0e.js} +7 -7
  19. package/dist/{cli-6dp0jkfj.js → cli-01k6wpr9.js} +4 -4
  20. package/dist/{cli-c07v0qfa.js → cli-124ntmf0.js} +83 -74
  21. package/dist/{cli-1tvdx9t5.js → cli-2rnd5j3t.js} +1 -1
  22. package/dist/{cli-4ghh072d.js → cli-2spnz7ye.js} +36 -36
  23. package/dist/{cli-dd37e0cm.js → cli-2v2zdm0a.js} +1 -1
  24. package/dist/{cli-aa8s22gn.js → cli-3aaeb78m.js} +195 -186
  25. package/dist/{cli-8x8y70av.js → cli-3caf7pmg.js} +2 -2
  26. package/dist/{cli-jd3kxppb.js → cli-3et6fmfe.js} +1 -1
  27. package/dist/{cli-kaa4bd7x.js → cli-3f8zbtqa.js} +9 -8
  28. package/dist/{cli-57pvhnyt.js → cli-43evxwj4.js} +1 -1
  29. package/dist/cli-43ms35q9.js +270 -0
  30. package/dist/cli-47hz21se.js +25584 -0
  31. package/dist/{cli-n515ex5z.js → cli-4ymxrwg5.js} +16 -16
  32. package/dist/{cli-2tnbc3gw.js → cli-539h29es.js} +2379 -66
  33. package/dist/{cli-rts1qvb4.js → cli-5qhfv9rw.js} +2 -2
  34. package/dist/{cli-faf46gdq.js → cli-6037prsx.js} +10 -10
  35. package/dist/{cli-bk9v1xrv.js → cli-6cwr32fe.js} +25 -25
  36. package/dist/{cli-812paz57.js → cli-6ehs4mta.js} +18 -2
  37. package/dist/{cli-95930z69.js → cli-6ym4jhzp.js} +2 -2
  38. package/dist/{cli-zg3z63x3.js → cli-7mv4h3sn.js} +1 -1
  39. package/dist/{cli-9a2rtd77.js → cli-7r162fxe.js} +24 -15
  40. package/dist/{cli-eg437b5p.js → cli-7sf9sb0w.js} +2 -1
  41. package/dist/{cli-vw5x18yj.js → cli-8st34zhr.js} +20 -10
  42. package/dist/{cli-fgphc007.js → cli-91pkxres.js} +1 -1
  43. package/dist/{cli-2kg31ted.js → cli-9fjr27ez.js} +11 -11
  44. package/dist/{cli-wr1h0k28.js → cli-9w8712tq.js} +617 -278
  45. package/dist/cli-aw83sr40.js +98 -0
  46. package/dist/{cli-ssvdrk4y.js → cli-b6px1k1q.js} +1 -1
  47. package/dist/{cli-w7dxb2fj.js → cli-cc93xzes.js} +6 -6
  48. package/dist/{cli-js8zrfyg.js → cli-fcfbct2j.js} +5 -5
  49. package/dist/{cli-3zxdz9r7.js → cli-fq2rr3jb.js} +6 -6
  50. package/dist/{boot-scrub-sweep-ejd5dnrz.js → cli-had1p04a.js} +8 -9
  51. package/dist/{cli-7cgf614g.js → cli-j6te8keb.js} +5 -5
  52. package/dist/{cli-25nstr34.js → cli-jrbq4djp.js} +1 -1
  53. package/dist/{cli-pz1c00aa.js → cli-k3q2va86.js} +2 -2
  54. package/dist/{cli-nhq5js1b.js → cli-k5yewqgd.js} +3 -3
  55. package/dist/cli-kbtzfrxj.js +404 -0
  56. package/dist/{cli-dx439zpg.js → cli-kpgcm7xy.js} +13 -1
  57. package/dist/{cli-mc1fx4xd.js → cli-m9cvf7vs.js} +10 -10
  58. package/dist/{cli-kmvcm34h.js → cli-md50mj0r.js} +2 -2
  59. package/dist/{cli-q8cfh1t9.js → cli-mk7c5ac4.js} +1 -1
  60. package/dist/cli-mys27d03.js +321 -0
  61. package/dist/{cli-spzkdgtg.js → cli-n3qe7tyr.js} +172 -168
  62. package/dist/{cli-7akn6ze9.js → cli-nh7x3133.js} +7 -28
  63. package/dist/{cli-fnh4b12r.js → cli-nstkanmx.js} +6 -6
  64. package/dist/{cli-g3zzby8t.js → cli-nv4xsvmk.js} +5 -5
  65. package/dist/{cli-sn4pc4qx.js → cli-p0c3vtch.js} +2 -2
  66. package/dist/{cli-5ntc4we6.js → cli-p0n7b5rz.js} +859 -2058
  67. package/dist/{cli-pn1v1pb0.js → cli-psffsanb.js} +3 -2
  68. package/dist/{cli-svc803vq.js → cli-q5srsxq2.js} +15 -15
  69. package/dist/{cli-nmcpzbty.js → cli-qrta34nb.js} +4 -4
  70. package/dist/{cli-k09cxm6m.js → cli-qx4f057j.js} +2 -2
  71. package/dist/{cli-eepnpee7.js → cli-s1khw52h.js} +12 -12
  72. package/dist/{cli-h474mvp5.js → cli-s1zqk1aj.js} +21 -11
  73. package/dist/{cli-8axx8vnw.js → cli-sb4426be.js} +10 -10
  74. package/dist/{cli-kqh27v2y.js → cli-th1dkc2v.js} +1 -1
  75. package/dist/{cli-cw7mc1je.js → cli-tr27kwyg.js} +3 -3
  76. package/dist/{cli-5kcmxwxv.js → cli-tvgqesec.js} +7 -5
  77. package/dist/{cli-a9hfzg2r.js → cli-ty3gha1p.js} +6 -6
  78. package/dist/{cli-fjggej24.js → cli-v46zsvqk.js} +1 -1
  79. package/dist/{cli-5gygrr67.js → cli-v8z0yga9.js} +4 -4
  80. package/dist/{cli-k7pt28ad.js → cli-vfqvrd82.js} +5 -5
  81. package/dist/{cli-vvgaz8t6.js → cli-vq2eg24x.js} +2 -2
  82. package/dist/{cli-pwsax0vp.js → cli-vsw91x06.js} +23 -22
  83. package/dist/{cli-7fx9jyfs.js → cli-w1q68d8x.js} +67 -11
  84. package/dist/{cli-c5cspahx.js → cli-wafmk3fn.js} +45 -20
  85. package/dist/{cli-ymct0ycy.js → cli-wwp1bd3n.js} +5495 -5095
  86. package/dist/{cli-me4maa4j.js → cli-y4ccxtz5.js} +45 -9
  87. package/dist/{cli-m1fbz2wj.js → cli-y8p78ekx.js} +178 -19
  88. package/dist/{cli-nr46j5pw.js → cli-z0m452jr.js} +1 -1
  89. package/dist/{cli-gddgcnav.js → cli-zeh2mhkg.js} +1 -1
  90. package/dist/{cli-e9973bf0.js → cli-zk7v5s89.js} +2 -2
  91. package/dist/cli.js +24 -23
  92. package/dist/{cloudflare-workers-ai-system-one-9y1zx3pt.js → cloudflare-workers-ai-system-one-4aysy6rh.js} +2 -2
  93. package/dist/{codex-adapter-44yq2fkn.js → codex-adapter-exfdbj73.js} +6 -6
  94. package/dist/{codex-hook-h1zb7cfk.js → codex-hook-59atdwd8.js} +1 -1
  95. package/dist/{codex-login-cdyrr5y1.js → codex-login-a239g1ah.js} +1 -1
  96. package/dist/{codex-session-runner-zbh26gbw.js → codex-session-runner-xhznc4g3.js} +6 -6
  97. package/dist/{commands-54f02v5b.js → commands-d8g349v4.js} +3 -3
  98. package/dist/{controller-9gpwcdek.js → controller-mwgdmb8y.js} +6 -3
  99. package/dist/{controllers-connect-61re6k1n.js → controllers-connect-5v7qx04j.js} +22 -20
  100. package/dist/core-sxy4epp2.js +38 -0
  101. package/dist/{cursor-adapter-7e4g81vd.js → cursor-adapter-p2q5h35d.js} +1 -1
  102. package/dist/{db-wnh0qjy1.js → db-qpganbeb.js} +3 -3
  103. package/dist/{db-dg2gc7fd.js → db-wcw0b2j8.js} +8 -2
  104. package/dist/{dispatcher-jrm24r43.js → dispatcher-8d8s49yz.js} +20 -18
  105. package/dist/{docker-9aq30pp2.js → docker-09tkkg0n.js} +42 -3
  106. package/dist/{dsh-adapter-1yqk267c.js → dsh-adapter-me0twn13.js} +1 -1
  107. package/dist/{easter-egg-3d-r4h9cs9m.js → easter-egg-3d-wv7w5ty6.js} +1 -1
  108. package/dist/{embedding-space-bafjr5f7.js → embedding-space-e48xchqa.js} +6 -6
  109. package/dist/{embeddings-7xmgqe0e.js → embeddings-tgq2afbq.js} +1 -1
  110. package/dist/{execute-d6jg5ns0.js → execute-8rhwrk7f.js} +1 -1
  111. package/dist/{external-channel-frq1xvq2.js → external-channel-8bt3j2pm.js} +2 -2
  112. package/dist/fx-adapter-adtdb3jb.js +19 -0
  113. package/dist/{google-generative-ai-hh7strj3.js → google-generative-ai-bh0djqjp.js} +5 -5
  114. package/dist/{google-vertex-fy5bw2pm.js → google-vertex-prjbw8dj.js} +9 -9
  115. package/dist/grok-adapter-accnn9km.js +19 -0
  116. package/dist/handlers-1x77561e.js +35 -0
  117. package/dist/{heartbeat-6bpa611t.js → heartbeat-x0056ra5.js} +23 -21
  118. package/dist/{hook-hvm5nf46.js → hook-a7vmn2st.js} +5 -5
  119. package/dist/{hook-w12k146y.js → hook-mrd2ayxv.js} +6 -6
  120. package/dist/{http-43tthdvs.js → http-ym9c5svp.js} +1335 -363
  121. package/dist/{index-fn054vsf.js → index-01ns1pkw.js} +1 -1
  122. package/dist/{index-1f0vypbg.js → index-0h6qd4p1.js} +34 -24
  123. package/dist/index-48qzcqzj.js +35 -0
  124. package/dist/{index-4b1q8kan.js → index-4k7m5dgj.js} +629 -354
  125. package/dist/index-620y7jzq.js +15 -0
  126. package/dist/{index-cret47a5.js → index-8p0j4h4j.js} +506 -43
  127. package/dist/{index-m5gx1xd6.js → index-9myfj74s.js} +40 -40
  128. package/dist/{index-bs7gw5fd.js → index-b5wgnm78.js} +44 -44
  129. package/dist/{index-ftywhyr0.js → index-ny60jcat.js} +394 -66
  130. package/dist/{index-tx9mc2ap.js → index-p46tvwtx.js} +24 -22
  131. package/dist/{index-585gyczt.js → index-pe3d8jfy.js} +3 -3
  132. package/dist/index-rkvaambe.js +36 -0
  133. package/dist/{index-mhq4sh5w.js → index-x6azjwm8.js} +1 -1
  134. package/dist/index-xj1mq27m.js +40 -0
  135. package/dist/k8s-m56sw868.js +217 -0
  136. package/dist/{keepalive-rk0j0jvh.js → keepalive-7yxg8z4c.js} +3 -3
  137. package/dist/lead-enzn86bz.js +74 -0
  138. package/dist/{maintenance-g6z6kaxw.js → maintenance-6tefxmk1.js} +1 -1
  139. package/dist/{node-jftbyawr.js → node-2wfcey7d.js} +1 -1
  140. package/dist/{oauth-refresh-sweep-2k3g2q4w.js → oauth-refresh-sweep-70cavc3a.js} +2 -2
  141. package/dist/{onboard-6fdbvh3v.js → onboard-fja65z08.js} +5 -5
  142. package/dist/{openai-decisions-q3hh60wr.js → openai-decisions-ytp6w6xh.js} +1 -1
  143. package/dist/{opencode-adapter-fdbsvts7.js → opencode-adapter-hakkm7yh.js} +6 -6
  144. package/dist/{otel-impl-rvwtc09q.js → otel-impl-7zhnt6gj.js} +1 -1
  145. package/dist/{pending-sqkrb836.js → pending-h01yzpx4.js} +21 -19
  146. package/dist/{pi-mono-adapter-asqayqcg.js → pi-mono-adapter-f52hz743.js} +40 -13
  147. package/dist/{pricing-refresh-f5tkgmw2.js → pricing-refresh-fzxvk2zf.js} +2 -2
  148. package/dist/{rbac-roles-06s555fa.js → rbac-roles-9v6vhgbs.js} +3 -3
  149. package/dist/{rbac-roles-szxsg8t1.js → rbac-roles-hfgh8sba.js} +2 -2
  150. package/dist/{render-v2-103p266q.js → render-v2-1rgspxzf.js} +6 -3
  151. package/dist/{resume-v7kjewt9.js → resume-tqy61x24.js} +10 -7
  152. package/dist/{runtime-f1gmk0b7.js → runtime-exkxyx5f.js} +1 -1
  153. package/dist/{session-access-6shev8ts.js → session-access-3act7vt4.js} +4 -4
  154. package/dist/{session-source-backfill-bd7spzjd.js → session-source-backfill-82qe7fqq.js} +3 -3
  155. package/dist/{setup-kmxmztdb.js → setup-ry1vfdef.js} +1 -1
  156. package/dist/thread-buffer-3x93yexa.js +38 -0
  157. package/dist/{typesafe-system-one-f2en2knd.js → typesafe-system-one-vcfj2ak8.js} +2 -2
  158. package/dist/user-merge-jobs-bx6bf7db.js +22 -0
  159. package/dist/{virtual-modules-57eje5wy.js → virtual-modules-s0rjzcqq.js} +3 -3
  160. package/dist/{work-objects-zr47ygmf.js → work-objects-z2e5tv03.js} +29 -23
  161. package/dist/{worker-follow-up-grrr3fda.js → worker-follow-up-y3xeg89w.js} +20 -18
  162. package/dist/worker-zfcv2wbf.js +74 -0
  163. package/openapi.json +2763 -147
  164. package/package.json +9 -8
  165. package/src/apps/catalog.generated.json +43 -3
  166. package/src/apps/page-validator.ts +27 -0
  167. package/src/be/boot-seeds.ts +7 -1
  168. package/src/be/db/model-groups.ts +238 -0
  169. package/src/be/db/model-profiles.ts +28 -7
  170. package/src/be/db/session-costs.ts +225 -0
  171. package/src/be/db/session-log-reasoning.ts +36 -0
  172. package/src/be/db/tasks/read.ts +8 -3
  173. package/src/be/db/tasks/write.ts +34 -1
  174. package/src/be/db/user-references.ts +75 -0
  175. package/src/be/db/users/references.ts +185 -0
  176. package/src/be/db-client.ts +70 -19
  177. package/src/be/db.ts +232 -361
  178. package/src/be/key-window-usage.ts +386 -0
  179. package/src/be/memory/demotion-evidence.ts +34 -0
  180. package/src/be/memory/reranker.ts +34 -12
  181. package/src/be/memory/review-recall-filter.ts +83 -0
  182. package/src/be/memory/search-candidates.ts +19 -6
  183. package/src/be/memory/types.ts +11 -0
  184. package/src/be/migrations/303_task_ui_specs.sql +28 -0
  185. package/src/be/migrations/306_provider_account_telemetry.sql +1 -0
  186. package/src/be/migrations/307_session_cost_credential_attribution.sql +23 -0
  187. package/src/be/migrations/310_session_logs_reasoning.sql +12 -0
  188. package/src/be/migrations/312_task_ui_action_runs_repeatable.sql +6 -0
  189. package/src/be/migrations/314_model_groups.sql +85 -0
  190. package/src/be/migrations/318_superseded_workflow_cut_backfill.sql +22 -0
  191. package/src/be/migrations/319_user_fk_indexes.sql +153 -0
  192. package/src/be/migrations/320_session_costs_kind.sql +4 -0
  193. package/src/be/migrations/321_user_merge_jobs.sql +52 -0
  194. package/src/be/pricing-normalize.ts +2 -0
  195. package/src/be/rbac-roles.ts +6 -4
  196. package/src/be/runtime-pools/db.ts +23 -5
  197. package/src/be/runtime-pools/supervisor.ts +15 -1
  198. package/src/be/scripts/db.ts +11 -0
  199. package/src/be/scripts/typecheck.ts +2 -0
  200. package/src/be/seed-model-groups.ts +86 -0
  201. package/src/be/seed-model-profiles.ts +20 -13
  202. package/src/be/seed-scripts/catalog/boot-triage.inline.ts +1 -0
  203. package/src/be/seed-scripts/catalog/boot-triage.ts +1 -0
  204. package/src/be/seed-scripts/catalog/dreaming-gather.ts +165 -1
  205. package/src/be/seed-scripts/catalog/wait-for-task.ts +5 -1
  206. package/src/be/seed-skills/index.ts +3 -0
  207. package/src/be/swarm-config-guard.ts +58 -1
  208. package/src/be/task-ui-spec.ts +259 -0
  209. package/src/be/user-merge-jobs.ts +564 -0
  210. package/src/be/users.ts +41 -23
  211. package/src/commands/controller.ts +3 -0
  212. package/src/commands/credential-outcome-report.ts +13 -3
  213. package/src/commands/onboard/agent-fs-version.ts +1 -1
  214. package/src/commands/onboard/compose-generator.ts +1 -1
  215. package/src/commands/onboard/env-generator.ts +1 -1
  216. package/src/commands/provider-credentials.ts +1 -1
  217. package/src/commands/rate-limit-outcome.ts +6 -0
  218. package/src/commands/runner.ts +34 -53
  219. package/src/extensions/catalog.generated.json +3 -3
  220. package/src/extensions/contract-types.generated.ts +1 -1
  221. package/src/extensions/contract.ts +15 -0
  222. package/src/extensions/dispatcher.ts +14 -4
  223. package/src/github/handlers.ts +57 -0
  224. package/src/github/types.ts +4 -0
  225. package/src/http/all-routes.ts +2 -0
  226. package/src/http/api-keys.ts +258 -30
  227. package/src/http/approval-requests.ts +5 -1
  228. package/src/http/auth.ts +3 -1
  229. package/src/http/config.ts +34 -1
  230. package/src/http/index.ts +13 -0
  231. package/src/http/memory.ts +19 -6
  232. package/src/http/model-groups.ts +277 -0
  233. package/src/http/model-profiles.ts +30 -13
  234. package/src/http/session-data.ts +74 -23
  235. package/src/http/sessions.ts +6 -2
  236. package/src/http/tasks.ts +140 -5
  237. package/src/http/tool-hooks.ts +140 -0
  238. package/src/http/users.ts +142 -19
  239. package/src/http/workflows.ts +19 -1
  240. package/src/integrations/chat-sdk/inbound.ts +8 -2
  241. package/src/integrations/chat-sdk/limits.ts +8 -3
  242. package/src/integrations/chat-sdk/relay.ts +87 -0
  243. package/src/jira/outbound.ts +5 -3
  244. package/src/linear/outbound.ts +5 -1
  245. package/src/prompts/base-prompt.ts +8 -0
  246. package/src/prompts/session-templates.ts +19 -2
  247. package/src/providers/acp-targets.ts +2 -2
  248. package/src/providers/amp-adapter.ts +1 -1
  249. package/src/providers/claude-adapter.ts +27 -4
  250. package/src/providers/claude-flag-settings.ts +39 -1
  251. package/src/providers/codex-adapter.ts +85 -3
  252. package/src/providers/codex-app-server.ts +9 -5
  253. package/src/providers/codex-oauth/auth-json.ts +1 -0
  254. package/src/providers/pi-mono-adapter.ts +35 -2
  255. package/src/providers/pricing-sources.md +41 -0
  256. package/src/providers/types.ts +11 -0
  257. package/src/rbac/legacy-policy.ts +1 -0
  258. package/src/rbac/permissions.ts +5 -0
  259. package/src/runtime-providers/docker.ts +65 -1
  260. package/src/runtime-providers/index.ts +7 -5
  261. package/src/runtime-providers/k8s.ts +250 -0
  262. package/src/scheduler/deferred-task-waits.ts +18 -5
  263. package/src/scripts-runtime/types/stdlib.d.ts +2 -0
  264. package/src/scripts-runtime/types/swarm-extension.d.ts +24 -9
  265. package/src/scripts-runtime/types/swarm-sdk.d.ts +2 -0
  266. package/src/slack/actions.ts +79 -0
  267. package/src/slack/app.ts +22 -15
  268. package/src/slack/blocks.ts +23 -2
  269. package/src/slack/inbound-files.ts +2 -0
  270. package/src/slack/render-v2.ts +154 -23
  271. package/src/slack/responses.ts +3 -2
  272. package/src/slack/work-objects.ts +4 -1
  273. package/src/tasks/errors.ts +5 -0
  274. package/src/tests/acp-adapter.test.ts +30 -6
  275. package/src/tests/api-key-tracking.test.ts +0 -72
  276. package/src/tests/api-keys-status-model-limits.test.ts +93 -1
  277. package/src/tests/api-keys-validation.test.ts +42 -0
  278. package/src/tests/approval-card-resolution.test.ts +7 -1
  279. package/src/tests/approval-requests-notifications.test.ts +11 -1
  280. package/src/tests/apps-catalog-page-frame.test.ts +49 -0
  281. package/src/tests/apps-session-thread.test.ts +79 -0
  282. package/src/tests/base-prompt.test.ts +111 -5
  283. package/src/tests/chat-sdk-relay.test.ts +170 -2
  284. package/src/tests/check-pr-body.test.ts +43 -0
  285. package/src/tests/claude-adapter-binary.test.ts +67 -6
  286. package/src/tests/claude-flag-settings.test.ts +29 -0
  287. package/src/tests/claude-sdk-lifecycle.test.ts +5 -0
  288. package/src/tests/codex-adapter.test.ts +340 -2
  289. package/src/tests/codex-app-server.test.ts +16 -0
  290. package/src/tests/codex-oauth.test.ts +3 -1
  291. package/src/tests/codex-rate-limits.test.ts +384 -0
  292. package/src/tests/credential-check.test.ts +14 -6
  293. package/src/tests/credential-outcome-report.test.ts +20 -0
  294. package/src/tests/db-client.test.ts +146 -0
  295. package/src/tests/db-task-read-contract.test.ts +3 -0
  296. package/src/tests/db-task-write-contract.test.ts +4 -0
  297. package/src/tests/deferred-task-wake.test.ts +63 -1
  298. package/src/tests/deploy-guard.test.ts +7 -7
  299. package/src/tests/deploy-select.test.ts +83 -0
  300. package/src/tests/docker-isolation-config-guard.test.ts +29 -0
  301. package/src/tests/docs-index-footprint.test.js +11 -3
  302. package/src/tests/dreaming-gather-corrections.test.ts +467 -0
  303. package/src/tests/e2e-visuals-comment.test.ts +82 -0
  304. package/src/tests/e2e-visuals-verify-pr.test.ts +138 -0
  305. package/src/tests/event-loop-lag.test.ts +9 -7
  306. package/src/tests/extensions-example-sql-admin-only.test.ts +7 -4
  307. package/src/tests/fixtures/extensions/native-tool-recorder/hooks.ts +26 -0
  308. package/src/tests/fixtures/extensions/native-tool-recorder/manifest.json +10 -0
  309. package/src/tests/fixtures/onboard/content.compose.yml.txt +1 -1
  310. package/src/tests/fixtures/onboard/content.env.txt +1 -1
  311. package/src/tests/fixtures/onboard/dev.compose.yml.txt +1 -1
  312. package/src/tests/fixtures/onboard/dev.env.txt +1 -1
  313. package/src/tests/fixtures/onboard/full-all.compose.yml.txt +1 -1
  314. package/src/tests/fixtures/onboard/full-all.env.txt +1 -1
  315. package/src/tests/fixtures/onboard/full.compose.yml.txt +1 -1
  316. package/src/tests/fixtures/onboard/full.env.txt +1 -1
  317. package/src/tests/fixtures/onboard/research.compose.yml.txt +1 -1
  318. package/src/tests/fixtures/onboard/research.env.txt +1 -1
  319. package/src/tests/fixtures/onboard/solo.compose.yml.txt +1 -1
  320. package/src/tests/fixtures/onboard/solo.env.txt +1 -1
  321. package/src/tests/fixtures/ui-spec-slack/deploys.json +121 -0
  322. package/src/tests/fixtures/ui-spec-slack/incident.json +183 -0
  323. package/src/tests/fixtures/ui-spec-slack/three-charts-stale.json +196 -0
  324. package/src/tests/fixtures/ui-spec-slack/video-rejected-by-slack.json +183 -0
  325. package/src/tests/fixtures/ui-spec-slack/video.json +446 -0
  326. package/src/tests/github-event-filter.test.ts +8 -0
  327. package/src/tests/github-handlers-inline-comments.test.ts +2 -0
  328. package/src/tests/github-handlers-reactions.test.ts +4 -0
  329. package/src/tests/github-handlers.test.ts +3 -0
  330. package/src/tests/github-sender-trust.test.ts +223 -0
  331. package/src/tests/gitleaks-download-retry.test.ts +85 -0
  332. package/src/tests/http-users.test.ts +142 -41
  333. package/src/tests/human-thread-routing.test.ts +187 -0
  334. package/src/tests/jira-outbound-sync.test.ts +33 -1
  335. package/src/tests/k8s-pool-smoke.test.ts +190 -0
  336. package/src/tests/key-window-usage.test.ts +846 -0
  337. package/src/tests/linear-outbound-sync.test.ts +30 -1
  338. package/src/tests/memory-rater-store.test.ts +35 -1
  339. package/src/tests/memory-reranker.test.ts +39 -4
  340. package/src/tests/memory-review-recall-filter.test.ts +205 -0
  341. package/src/tests/migration-318-superseded-workflow-cut-backfill.test.ts +74 -0
  342. package/src/tests/model-groups-api.test.ts +415 -0
  343. package/src/tests/model-profiles-api.test.ts +1 -0
  344. package/src/tests/operator-granted-credentials.test.ts +7 -2
  345. package/src/tests/operator-granted-role-wire.test.ts +2 -1
  346. package/src/tests/pi-mono-adapter.test.ts +79 -0
  347. package/src/tests/preload-env.test.ts +2 -0
  348. package/src/tests/preload.ts +3 -1
  349. package/src/tests/prompt-template-session.test.ts +4 -3
  350. package/src/tests/provider-quota-persistence.test.ts +362 -0
  351. package/src/tests/rate-limit-event.test.ts +22 -0
  352. package/src/tests/rbac-engine.test.ts +1 -0
  353. package/src/tests/reasoning-events.test.ts +164 -0
  354. package/src/tests/routing-affinity-inventory.test.ts +22 -0
  355. package/src/tests/runtime-k8s-pools.test.ts +142 -0
  356. package/src/tests/runtime-pools-db.test.ts +42 -2
  357. package/src/tests/runtime-pools-http.test.ts +47 -2
  358. package/src/tests/runtime-provider-registration.test.ts +5 -14
  359. package/src/tests/runtime-providers-docker.test.ts +91 -0
  360. package/src/tests/runtime-providers-k8s.test.ts +303 -0
  361. package/src/tests/script-connections.test.ts +18 -1
  362. package/src/tests/secret-canary-sweep.test.ts +41 -5
  363. package/src/tests/seed-scripts.test.ts +23 -0
  364. package/src/tests/session-cost-attribution.test.ts +748 -0
  365. package/src/tests/session-costs.test.ts +14 -15
  366. package/src/tests/session-logs.test.ts +83 -0
  367. package/src/tests/sessions-detail-batch.test.ts +7 -0
  368. package/src/tests/short-id.test.ts +23 -0
  369. package/src/tests/slack-blocks.test.ts +69 -0
  370. package/src/tests/slack-render-v2.test.ts +411 -0
  371. package/src/tests/slack-start-reload-race.test.ts +67 -0
  372. package/src/tests/spec-base-url.test.ts +13 -1
  373. package/src/tests/subscription-plans.test.ts +20 -1
  374. package/src/tests/system-one-decide-session-cost.test.ts +196 -0
  375. package/src/tests/task-ui-action-route.test.ts +249 -0
  376. package/src/tests/task-ui-actions.test.ts +195 -0
  377. package/src/tests/task-ui-script-actions.test.ts +517 -0
  378. package/src/tests/task-ui-spec-fallback.test.ts +65 -0
  379. package/src/tests/task-ui-spec.test.ts +368 -0
  380. package/src/tests/tool-hooks-http.test.ts +187 -0
  381. package/src/tests/ui-spec-script-actions-config.test.ts +196 -0
  382. package/src/tests/user-delete-perf.test.ts +321 -0
  383. package/src/tests/user-merge-jobs.test.ts +680 -0
  384. package/src/tests/vcs-provider.test.ts +25 -5
  385. package/src/tests/vendored-openapi.test.ts +13 -1
  386. package/src/tests/workflow-agent-task-retry.test.ts +96 -1
  387. package/src/tests/workflow-foreach-supersede-retry.test.ts +10 -0
  388. package/src/tests/workflow-http-v2.test.ts +27 -0
  389. package/src/tests/workflow-replay.test.ts +10 -1
  390. package/src/tests/workflow-triggers-v2.test.ts +128 -0
  391. package/src/tests/workflow-wait-event.test.ts +109 -1
  392. package/src/tools/defer-task.ts +1 -1
  393. package/src/tools/memory-search.ts +14 -3
  394. package/src/tools/store-progress.ts +69 -3
  395. package/src/tools/swarm-config/delete-config.ts +12 -1
  396. package/src/tools/swarm-config/set-config.ts +8 -0
  397. package/src/tools/system-one-decide.ts +113 -3
  398. package/src/tools/utils.ts +4 -1
  399. package/src/tools/workflows/create-workflow.ts +2 -0
  400. package/src/tools/workflows/update-workflow.ts +3 -1
  401. package/src/types.ts +93 -4
  402. package/src/ui-spec/actions.ts +112 -0
  403. package/src/ui-spec/fallback.ts +19 -0
  404. package/src/ui-spec/schema.ts +38 -0
  405. package/src/ui-spec/script-actions.ts +340 -0
  406. package/src/ui-spec/script-allowlist.ts +48 -0
  407. package/src/ui-spec/slack.ts +17 -0
  408. package/src/ui-spec/validate.ts +169 -0
  409. package/src/utils/codex-rate-limits.ts +159 -0
  410. package/src/utils/credentials.ts +2 -0
  411. package/src/utils/error-tracker.ts +19 -0
  412. package/src/utils/provider-account-telemetry.ts +331 -0
  413. package/src/utils/reasoning-events.ts +107 -0
  414. package/src/utils/short-id.ts +20 -14
  415. package/src/utils/subscription-plans.ts +11 -59
  416. package/src/utils/task-ui-spec.ts +79 -0
  417. package/src/vcs/index.ts +12 -2
  418. package/src/workflows/executors/system-one-decision.ts +2 -2
  419. package/src/workflows/resume.ts +3 -2
  420. package/src/workflows/task-step-routing.ts +38 -13
  421. package/src/workflows/triggers.ts +35 -3
  422. package/templates/extensions/manifest.schema.json +13 -0
  423. package/templates/extensions/sql-admin-only/README.md +2 -1
  424. package/templates/extensions/sql-admin-only/hooks.ts +7 -3
  425. package/templates/extensions/sql-admin-only/manifest.json +1 -1
  426. package/templates/skills/apps/SKILL.md +32 -5
  427. package/templates/skills/apps/content.md +32 -5
  428. package/templates/skills/swarm-docs/content.md +2 -0
  429. package/templates/skills/ui-spec/config.json +14 -0
  430. package/templates/skills/ui-spec/content.md +133 -0
  431. package/templates/workflows/dreaming/content.md +1 -1
  432. package/dist/acp-adapter-jqn86aam.js +0 -16
  433. package/dist/cli-7831nhaw.js +0 -93
  434. package/dist/cli-srtkr1h2.js +0 -12078
  435. package/dist/fx-adapter-0zrkfbkd.js +0 -19
  436. package/dist/grok-adapter-3db1c538.js +0 -19
  437. package/dist/handlers-k22n8mnn.js +0 -33
  438. package/dist/index-8xcyd3mc.js +0 -33
  439. package/dist/index-9sy2bh6n.js +0 -38
  440. package/dist/index-b24j7t2m.js +0 -12797
  441. package/dist/index-wjd56k1v.js +0 -34
  442. package/dist/lead-atxf3q6e.js +0 -72
  443. package/dist/thread-buffer-4yz236d0.js +0 -36
  444. package/dist/worker-p4hbtcy3.js +0 -72
  445. package/dist/{azure-openai-responses-590s1eea.js → azure-openai-responses-b3y7fz36.js} +8 -8
  446. package/dist/{cli-j49yqpvh.js → cli-7evph51z.js} +3 -3
  447. package/dist/{cli-g0vv9dg4.js → cli-8y43jx2r.js} +8 -8
  448. package/dist/{cli-m0cy2vyf.js → cli-k6nejceb.js} +4 -4
  449. package/dist/{mistral-conversations-0c30em7t.js → mistral-conversations-tm2vd4gc.js} +8 -8
  450. package/dist/{openai-codex-responses-bkcd8pjj.js → openai-codex-responses-sxjv60xx.js} +4 -4
  451. package/dist/{openai-completions-f3n69rep.js → openai-completions-0c7qnhsx.js} +20 -20
  452. package/dist/{openai-responses-gbh0wfqe.js → openai-responses-a7h29chp.js} +15 -15
  453. package/dist/{pi-messages-zebyt7gb.js → pi-messages-2j0fpqwq.js} +5 -5
@@ -17,18 +17,20 @@ import {
17
17
  deleteSkill2,
18
18
  getSkillByName2,
19
19
  init_db4
20
- } from "./cli-ymct0ycy.js";
21
- import"./cli-k7pt28ad.js";
20
+ } from "./cli-wwp1bd3n.js";
21
+ import"./cli-vfqvrd82.js";
22
22
  import {
23
23
  agentFsProvisionSeeder2
24
- } from "./cli-vvgaz8t6.js";
24
+ } from "./cli-vq2eg24x.js";
25
25
  import {
26
26
  runSeeders
27
- } from "./cli-nr46j5pw.js";
28
- import"./cli-q8cfh1t9.js";
27
+ } from "./cli-z0m452jr.js";
28
+ import"./cli-mk7c5ac4.js";
29
+ import"./cli-9w8712tq.js";
30
+ import"./cli-47hz21se.js";
29
31
  import"./cli-q2d3e1k1.js";
30
- import"./cli-2tnbc3gw.js";
31
- import"./cli-w7dxb2fj.js";
32
+ import"./cli-539h29es.js";
33
+ import"./cli-cc93xzes.js";
32
34
  import {
33
35
  buildSkillContent
34
36
  } from "./cli-691vz9mk.js";
@@ -52,11 +54,12 @@ import {
52
54
  init_typecheck,
53
55
  parseSkillContent,
54
56
  init_skill_parser
55
- } from "./cli-7fx9jyfs.js";
56
- import"./cli-1tvdx9t5.js";
57
- import"./cli-svc803vq.js";
58
- import"./cli-dd37e0cm.js";
59
- import"./cli-pwsax0vp.js";
57
+ } from "./cli-w1q68d8x.js";
58
+ import"./cli-2rnd5j3t.js";
59
+ import"./cli-q5srsxq2.js";
60
+ import"./cli-n3qe7tyr.js";
61
+ import"./cli-2v2zdm0a.js";
62
+ import"./cli-vsw91x06.js";
60
63
  import {
61
64
  isEnvFlagEnabled,
62
65
  init_env_flag
@@ -300,6 +303,7 @@ export default async function bootTriage(args: any, ctx: any) {
300
303
  FROM agent_tasks p
301
304
  LEFT JOIN agents a ON a.id = p.agentId
302
305
  WHERE p.status = 'superseded'
306
+ AND p.failureReason IS NOT 'superseded_workflow_task'
303
307
  AND datetime(p.lastUpdatedAt) >= datetime(?, ?)
304
308
  AND NOT EXISTS (
305
309
  SELECT 1
@@ -3089,8 +3093,11 @@ const CAPS = {
3089
3093
  identityOpsTotal: 6,
3090
3094
  identityOpsPerAgent: 1,
3091
3095
  memoryStore: 5,
3092
- memoryEdit: 5,
3096
+ // 5 for the lanes that existed before + memoryCorrections, since a confirmed correction is an edit.
3097
+ memoryEdit: 15,
3093
3098
  memoryDelete: 10,
3099
+ // Memories per night in swarm.memory.corrections (explicit-self rating notes). About 3 new notes a day.
3100
+ memoryCorrections: 10,
3094
3101
  skillCreate: 2,
3095
3102
  skillUpdate: 6,
3096
3103
  scriptSpecs: 2,
@@ -3552,6 +3559,156 @@ export default async function (args: unknown, ctx: ScriptContext) {
3552
3559
  // memories had long titles. A newline in a name is the real defect.
3553
3560
  [win],
3554
3561
  );
3562
+ // Correction queue: explicit-self ratings whose note says a manual memory is wrong or stale. One item per memory,
3563
+ // oldest unhandled note first. Handled = the memory has a version newer than the rating (edited), or a non-dry
3564
+ // synthesis already ruled on the rating: a rejected[] item from "swarm.memory.corrections" naming "rating:<id>"
3565
+ // with a non-cap reason, or a propose action whose evidence cites "rating:<id>". Cap overflow and edits apply
3566
+ // refused leave no marker, so they come back the next night.
3567
+ // A rating on a later chunk counts for its document: it maps to chunk 0 by the same match dreaming-apply uses
3568
+ // (name, agent, chunk count, write minute). A single-chunk body is sent whole, since synthesis may replace it;
3569
+ // one longer than CORR_SINGLE_MAX is held out of the queue (counted in \`oversize\`) instead of being truncated.
3570
+ // A body the egress scrubber rewrote is held out too (counted in \`scrubbed\`): synthesis could copy its
3571
+ // "[REDACTED:<key>]" marker into a replace, and apply's scrubberGuard credits markers in the op content, so the
3572
+ // original text would be lost. SQL length() is a number, so the scrubber leaves it alone; a changed code-point
3573
+ // count catches a rewrite even when no marker text survives.
3574
+ const CORR_SINGLE_MAX = 8000;
3575
+ const scrubbedRead = (text: string, rawLen: unknown) =>
3576
+ text.includes("[REDACTED") || [...text].length !== Number(rawLen ?? 0);
3577
+ const corrWf = await q(
3578
+ "correctionsWorkflow",
3579
+ \`SELECT COALESCE((SELECT workflowId FROM workflow_runs WHERE id = ?),
3580
+ (SELECT id FROM workflows WHERE name = 'dreaming' ORDER BY createdAt ASC LIMIT 1)) wf\`,
3581
+ [a.runId ?? ""],
3582
+ );
3583
+ // The scrubber rewrites a body after the query returns, so a held-out memory is only known here. Page by
3584
+ // excluding every memory already read: a run of scrubbed or held memories at the head of the queue can no
3585
+ // longer fill the window and starve the clean corrections behind it night after night.
3586
+ const corrPage = (seen: string[]) => q(
3587
+ "memCorrections",
3588
+ \`WITH syn AS MATERIALIZED (
3589
+ SELECT json_extract(s.output, '$.taskOutput') o FROM workflow_run_steps s JOIN workflow_runs r ON r.id = s.runId
3590
+ WHERE r.workflowId = ? AND s.nodeId = 'synthesize' AND s.runId <> ? AND json_valid(s.output)
3591
+ AND COALESCE(CASE WHEN json_valid(r.triggerData) THEN json_type(r.triggerData, '$.dryRun') = 'true'
3592
+ OR json_extract(r.triggerData, '$.dryRun') = 'true' END, 0) = 0),
3593
+ handled AS MATERIALIZED (
3594
+ SELECT json_extract(j.value, '$.item') ref FROM syn, json_each(syn.o, '$.rejected') j
3595
+ WHERE j.type = 'object' AND json_extract(j.value, '$.from') = 'swarm.memory.corrections'
3596
+ AND COALESCE(json_extract(j.value, '$.reason'), '') NOT GLOB 'cap*'
3597
+ UNION
3598
+ SELECT e.value FROM syn, json_each(syn.o, '$.actions') x, json_each(x.value, '$.evidence') e
3599
+ WHERE x.type = 'object' AND json_extract(x.value, '$.tier') = 'propose' AND e.type = 'text' AND e.value GLOB 'rating:*'),
3600
+ rated AS MATERIALIZED (
3601
+ SELECT r.id ratingId, r.memoryId ratedId, r.taskId, r.signal, r.reasoning, r.createdAt ratedAt,
3602
+ CASE WHEN COALESCE(c.chunkIndex, 0) = 0 THEN c.id ELSE (
3603
+ SELECT h.id FROM agent_memory h WHERE h.name = c.name AND h.agentId IS c.agentId AND h.source = 'manual'
3604
+ AND COALESCE(h.chunkIndex, 0) = 0 AND COALESCE(h.totalChunks, 1) = COALESCE(c.totalChunks, 1)
3605
+ AND substr(h.createdAt, 1, 16) = substr(c.createdAt, 1, 16) ORDER BY h.createdAt, h.id LIMIT 1) END docId
3606
+ FROM memory_rating r JOIN agent_memory c ON c.id = r.memoryId
3607
+ WHERE r.source = 'explicit-self' AND r.signal < 0 AND length(trim(COALESCE(r.reasoning, ''))) > 0
3608
+ AND c.source = 'manual'),
3609
+ q AS MATERIALIZED (
3610
+ SELECT r.ratingId, r.docId memoryId, r.ratedId, r.taskId, r.signal, r.reasoning, r.ratedAt,
3611
+ m.name, m.agentId, m.scope, m.version, m.alpha, m.beta, m.createdAt memCreatedAt, m.content, length(m.content) rawLen,
3612
+ COALESCE(m.totalChunks, 1) totalChunks,
3613
+ (COALESCE(m.totalChunks, 1) = 1 AND length(m.content) > ?) big,
3614
+ ROW_NUMBER() OVER (PARTITION BY r.docId ORDER BY r.ratedAt DESC) rn,
3615
+ MIN(r.ratedAt) OVER (PARTITION BY r.docId) firstAt
3616
+ FROM rated r JOIN agent_memory m ON m.id = r.docId
3617
+ WHERE julianday(r.ratedAt) > julianday(COALESCE(
3618
+ (SELECT MAX(v.createdAt) FROM agent_memory_version v WHERE v.memory_id = m.id), m.createdAt))
3619
+ AND ('rating:' || r.ratingId) NOT IN (SELECT ref FROM handled WHERE ref IS NOT NULL))
3620
+ -- The counts row survives an empty pick (memoryId NULL), so oversize-only backlogs still report.
3621
+ SELECT f.*, s.backlog, s.oversize
3622
+ FROM (SELECT COUNT(DISTINCT memoryId) backlog, COUNT(DISTINCT CASE WHEN big THEN memoryId END) oversize FROM q) s
3623
+ LEFT JOIN (SELECT * FROM q WHERE rn <= 3 AND memoryId IN (
3624
+ SELECT memoryId FROM q WHERE rn = 1 AND NOT big
3625
+ AND memoryId NOT IN (SELECT value FROM json_each(?)) ORDER BY firstAt ASC, memoryId LIMIT ?)) f ON 1
3626
+ ORDER BY f.firstAt ASC, f.memoryId, f.rn\`,
3627
+ [String(corrWf?.[0]?.wf ?? ""), a.runId ?? "", CORR_SINGLE_MAX, JSON.stringify(seen), CAPS.memoryCorrections * 2],
3628
+ );
3629
+ // Each page adds only unseen memories, so the loop ends when the queue is exhausted. The page guard is a
3630
+ // runaway stop: 50 pages x 20 memories is ten times the backlog seen in prod.
3631
+ const CORR_MAX_PAGES = 50;
3632
+ // ok false = a page query failed, so the items read so far are not the whole queue.
3633
+ let corrOk = !!corrWf;
3634
+ let corrCounts: any = null;
3635
+ const corrSeen: string[] = [];
3636
+ // Multi-chunk bodies may be cut for the prompt: apply refuses edits to them, so they only become proposals.
3637
+ const CORR_BODY_MAX = 3000;
3638
+ const corrItems: any[] = [];
3639
+ const corrHeld = new Set<string>();
3640
+ const corrScrubbed = new Set<string>();
3641
+ for (let page = 0; corrOk && page < CORR_MAX_PAGES && corrItems.length < CAPS.memoryCorrections; page++) {
3642
+ const rows = await corrPage(corrSeen);
3643
+ if (rows === null) {
3644
+ corrOk = false;
3645
+ break;
3646
+ }
3647
+ corrCounts ??= rows[0] ?? null;
3648
+ const fresh = [...new Set(rows.map((r: any) => r.memoryId).filter((id: unknown) => id != null))] as string[];
3649
+ if (!fresh.length) break;
3650
+ corrSeen.push(...fresh);
3651
+ for (const r of rows) {
3652
+ if (r.memoryId == null || corrHeld.has(r.memoryId) || corrScrubbed.has(r.memoryId)) continue;
3653
+ let item = corrItems.find((x) => x.memoryId === r.memoryId);
3654
+ if (!item) {
3655
+ if (corrItems.length >= CAPS.memoryCorrections) continue;
3656
+ let body = String(r.content ?? "");
3657
+ const totalChunks = Number(r.totalChunks);
3658
+ // SQLite length() counts code points and JS counts UTF-16 units: re-check, never send a cut single-chunk body.
3659
+ if (totalChunks <= 1 && body.length > CORR_SINGLE_MAX) {
3660
+ corrHeld.add(r.memoryId);
3661
+ continue;
3662
+ }
3663
+ let joined = totalChunks <= 1;
3664
+ if (totalChunks > 1) {
3665
+ // Same document match as dreaming-apply (name, agent, chunk count), pinned to chunk 0's write minute.
3666
+ const parts = await q(
3667
+ "memCorrectionChunks",
3668
+ \`SELECT content, length(content) rawLen FROM agent_memory WHERE name = ? AND agentId IS ? AND source = 'manual'
3669
+ AND COALESCE(totalChunks, 1) = ? AND substr(createdAt, 1, 16) = substr(?, 1, 16) ORDER BY chunkIndex ASC\`,
3670
+ [r.name, r.agentId ?? null, totalChunks, r.memCreatedAt],
3671
+ );
3672
+ if (parts?.length) body = joinChunks(parts.map((x: any) => String(x.content ?? "")));
3673
+ joined = parts?.length === totalChunks;
3674
+ if (parts?.some((x: any) => scrubbedRead(String(x.content ?? ""), x.rawLen))) {
3675
+ corrScrubbed.add(r.memoryId);
3676
+ continue;
3677
+ }
3678
+ }
3679
+ if (scrubbedRead(String(r.content ?? ""), r.rawLen)) {
3680
+ corrScrubbed.add(r.memoryId);
3681
+ continue;
3682
+ }
3683
+ const cut = totalChunks > 1 && body.length > CORR_BODY_MAX;
3684
+ item = {
3685
+ memoryId: r.memoryId,
3686
+ name: r.name,
3687
+ agentId: r.agentId ?? null,
3688
+ scope: r.scope,
3689
+ version: Number(r.version ?? 1),
3690
+ alpha: Number(r.alpha),
3691
+ beta: Number(r.beta),
3692
+ totalChunks,
3693
+ multiChunk: totalChunks > 1,
3694
+ content: cut ? body.slice(0, CORR_BODY_MAX) : body,
3695
+ // true = the body shown is not the whole memory (cut for the prompt, or a chunk read came back short).
3696
+ contentTruncated: cut || !joined,
3697
+ notes: [],
3698
+ };
3699
+ corrItems.push(item);
3700
+ }
3701
+ item.notes.push({
3702
+ ratingId: r.ratingId,
3703
+ // The chunk row the agent rated; differs from memoryId when the rating was on a later chunk.
3704
+ ratedMemoryId: r.ratedId,
3705
+ taskId: r.taskId ?? null,
3706
+ signal: Number(r.signal),
3707
+ ratedAt: r.ratedAt,
3708
+ note: String(r.reasoning ?? "").slice(0, 1000),
3709
+ });
3710
+ }
3711
+ }
3555
3712
  const created = await q(
3556
3713
  "memCreatedInWindow",
3557
3714
  \`SELECT source, COUNT(*) n FROM agent_memory WHERE julianday(createdAt) > julianday('now', ?) GROUP BY source\`,
@@ -3566,6 +3723,17 @@ export default async function (args: unknown, ctx: ScriptContext) {
3566
3723
  })),
3567
3724
  unhelpful: unhelpful ?? [],
3568
3725
  badKeys: badKeys ?? [],
3726
+ // ok false = a queue page failed, so the list may be short or empty; it is not "nothing to correct".
3727
+ corrections: {
3728
+ ok: corrOk,
3729
+ cap: CAPS.memoryCorrections,
3730
+ backlog: Number(corrCounts?.backlog ?? 0),
3731
+ // Single-chunk memories over CORR_SINGLE_MAX chars: held out, never sent cut (synthesis could replace them).
3732
+ oversize: Number(corrCounts?.oversize ?? 0) + corrHeld.size,
3733
+ // Memories whose body came back scrubbed: held out, never sent (a replace would persist the marker).
3734
+ scrubbed: corrScrubbed.size,
3735
+ items: corrItems,
3736
+ },
3569
3737
  createdInWindow: {
3570
3738
  manual: cnt("manual"),
3571
3739
  taskCompletion: cnt("task_completion"),
@@ -14593,7 +14761,11 @@ export default async function waitForTask(args: any, ctx: any) {
14593
14761
  const t: any = await ctx.swarm.task_get({ taskId });
14594
14762
  const d = t?.data ?? t ?? {};
14595
14763
  last = { status: d.status ?? null, output: d.output ?? null };
14596
- if (["completed", "failed", "cancelled", "skipped"].includes(String(last.status))) {
14764
+ // A workflow step whose supersede cut got a retry moves from failed to
14765
+ // superseded with no resume to follow; it is as settled as the failure was.
14766
+ const cutWithRetry =
14767
+ last.status === "superseded" && d.failureReason === "superseded_workflow_task";
14768
+ if (cutWithRetry || ["completed", "failed", "cancelled", "skipped"].includes(String(last.status))) {
14597
14769
  return { done: true, ...last };
14598
14770
  }
14599
14771
  await new Promise((r) => setTimeout(r, 2000));
@@ -14944,7 +15116,7 @@ var config_default2 = `{
14944
15116
  `;
14945
15117
 
14946
15118
  // templates/skills/apps/content.md
14947
- var content_default2 = "# Swarm Apps\n\nSwarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot.\n\n> **Capability gate**: app tools are available when the server's `CAPABILITIES` includes `pages` (for example `CAPABILITIES=core,task-pool,pages`). There is no separate `apps` capability. If these tools are absent from your MCP list, this is why.\n\n## Tools and iteration loop\n\n| Tool | Use it for |\n|---|---|\n| `app-list` | Discover apps by id, name, description, and timestamps. Definitions are omitted. |\n| `app-get` | Read one complete stored definition before changing it. |\n| `app-upsert` | Create an app, or replace an existing app's entire definition when you intentionally have the full desired state. |\n| `app-patch` | Make a focused change while preserving everything not mentioned in the patch. Prefer this for iteration. |\n| `app-query` | Run one declared named query and return its rows. Use this when an agent or saved script needs to consume app data rather than render the app UI. |\n| `app-rows-list` | List rows with typed equality filters, sorting, and a limit. Returns `{ rows, total }`. |\n| `app-row-get` | Read a row by `rowId`. Returns `{ row }`. |\n| `app-row-create` | Create a row from `values`. Returns `{ row }`. |\n| `app-rows-create` | Create 1 to 500 rows from a `rows: values[]` array, within 10 MiB. Returns `{ rows }`. |\n| `app-row-patch` | Patch a row by `rowId` with `values`. Returns `{ row }`. |\n| `app-row-delete` | Delete a row by `rowId`. Returns `{ ok: true }`. |\n| `app-rows-delete` | Delete matching rows with a non-empty `equals` filter. Returns `{ deleted }`. |\n| `app-action-run` | Run a declared script, task, or sync action with `{ appId, action, input? }`. Agents can invoke it through MCP only. |\n| `app-history` | List definition snapshots and their compact model/column digests before choosing a restore point. |\n| `app-diff` | Show a unified definition diff; defaults to newest snapshot → CURRENT. |\n| `app-rollback` | Restore a snapshot through the normal schema-migration engine. |\n\nFor every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch` -> if rejected, fix every returned `issues[]` entry (`path` + `message`) and retry. Validation happens before storage, so a rejected update leaves the saved app unchanged. Do not guess at the current definition or use `app-upsert` with a partial definition.\n\n`app-patch` can also change `name`; omit `description` to preserve it or pass `description: null` to clear it.\n\n### Reading an app's callable surface\n\nOne `app-get` returns everything needed to drive an app you did not write: `definition.queries` are runnable with `app-query` (supply every `$param` the query references), and `definition.actions` are invocable with `app-action-run` or `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read the query parameters and action arguments from the definition before invocation. Do not guess parameter names.\n\n### Verified action caller\n\nScript actions receive `caller` as a reserved, server-stamped argument. The server overwrites `caller` from definition defaults and request input.\n\n```typescript\ntype AppActionCaller = {\n kind: \"user\" | \"agent\" | \"operator\" | \"guest\";\n id: string | null;\n name?: string;\n pageId?: string;\n};\n```\n\nThe caller identifies the authenticated user or agent. Operator and guest callers have `id: null`. A signed page session adds `pageId`.\nWith the swarm key, a registered `X-Agent-ID` produces an agent caller and `agent:<id>` row provenance. Missing or unknown agent IDs remain operator callers.\nTask actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.\n\n### Verified action caller\n\nScript actions receive `caller` as a reserved, server-stamped argument. The server overwrites `caller` from definition defaults and request input.\n\n```typescript\ntype AppActionCaller = {\n kind: \"user\" | \"agent\" | \"operator\" | \"guest\";\n id: string | null;\n name?: string;\n pageId?: string;\n};\n```\n\nThe caller identifies the authenticated user or agent. Operator and guest callers have `id: null`. A signed page session adds `pageId`.\nWith the swarm key, a registered `X-Agent-ID` produces an agent caller and `agent:<id>` row provenance. Missing or unknown agent IDs remain operator callers.\nTask actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.\n\n## Safe schema evolution and rollback\n\nPrefer **hiding** a column over deleting it. A hidden column's values stay on every existing row, so an unhide or rollback can make it visible again. Hiding is metadata-only: hidden columns cannot be used in queries, page bindings, `app.mutate` values, or new row writes, and `required` is ignored while hidden. Row GETs still expose the historical value for backward compatibility.\n\nDo not reuse a hidden column name. The name remains held until you either unhide it or explicitly purge its stored values. To permanently remove a column, delete its declaration with `null` and include `{ \"columnName\": { \"purge\": true } }` in the same `migration` object. That is deliberately one-shot and irreversible for row data.\n\nSchema-changing writes can carry this sibling `migration` object:\n\n```json\n{\n \"migration\": {\n \"priority\": { \"from\": \"flag\", \"map\": { \"urgent\": \"high\", \"watch\": \"low\" }, \"else\": \"none\" },\n \"status\": { \"from\": \"flag\", \"map\": { \"watch\": \"watching\", \"done\": \"done\" }, \"else\": \"open\" },\n \"oldColumn\": { \"purge\": true },\n \"count\": { \"coerce\": true, \"else\": 0 },\n \"owner\": { \"set\": \"unassigned\" }\n }\n}\n```\n\nUse `set` to backfill a changed column, `from` with optional `map`/`else` to derive it from one existing (including hidden) column, `coerce` for a kind change, and `purge` only for explicit destruction. Non-purge directives target a column changed in that same write. The server fails loudly before writing when a lossy change needs a directive: inspect every returned `issues[]` item, including its per-value row counts, then choose an explicit policy and retry. Never guess a migration just to get a 200.\n\n**Source lifecycle** rides the same engine with the same all-or-nothing guarantees. Free: adding a source, adding a NEW column with a `source` binding, binding an existing column that holds zero values, changing a binding's `field`/`transform`, and changing a source's `args`/`config`/`connection`/`scriptId` (window changes churn staleness on the next pass — expect `stale` flips when narrowing). Rejected with a path-bearing issue: changing `joinKey` (immutable — remove the source and add it again), changing `connector` while the source owns rows (row count in the message), and binding an existing column that already holds values (purge it — or add a fresh column — and bind that instead; a sync pass would otherwise overwrite the data). Removing a source **detaches** its rows: values survive as ordinary columns, the `source`/`syncedAt`/`stale` envelope is stripped, and the report counts them in `detachedRows`. A patch removing a source must drop its column bindings in the same call — a dangling `source.of` is rejected before anything is written.\n\nSync never adopts rows it does not own: a pulled record whose join key matches an unowned row creates a second, source-owned row. Adding a source over a join-key column that already holds values therefore duplicates those records on the first pass — and remove-source → re-add duplicates for the same reason, because detached rows keep their values. To convert a hand-maintained model into a synced one, purge the old rows first or use a fresh join-key column.\n\nFor example, split a legacy `flag` into `priority` and `status` without losing data in one patch: add the two columns, map both from `flag`, update every affected query/page binding, then hide `flag`.\n\n```json\n{\n \"appId\": \"<app-id>\",\n \"definition\": {\n \"models\": {\n \"ticket\": {\n \"columns\": {\n \"priority\": { \"kind\": \"enum\", \"enum\": [\"none\", \"low\", \"high\"] },\n \"status\": { \"kind\": \"enum\", \"enum\": [\"open\", \"watching\", \"done\"] },\n \"flag\": { \"kind\": \"string\", \"hidden\": true }\n }\n }\n }\n },\n \"migration\": {\n \"priority\": { \"from\": \"flag\", \"map\": { \"urgent\": \"high\", \"watch\": \"low\" }, \"else\": \"none\" },\n \"status\": { \"from\": \"flag\", \"map\": { \"watch\": \"watching\", \"done\": \"done\" }, \"else\": \"open\" }\n }\n}\n```\n\nEvery schema migration returns `{ scanned, backfilled, coerced, mapped, elsed, purgedValues, idxRebuilt, detachedRows, orphanFields }`. Read `orphanFields`: it reports extra row fields that predate or no longer appear in the definition; they are preserved until an explicit purge. `schemaVersion` is server-managed: never set it in an input patch or try to use it as application data.\n\nEvery successful definition write snapshots the previous definition. Use `app-history` to select a version, `app-diff({ appId, from: <version> })` to inspect it against CURRENT, then `app-rollback({ appId, version: <version>, migration? })` to restore it. Rollback is a forward migration over live rows, not row-level time travel: it creates a new pre-rollback snapshot and may reject a lossy restore with the same migration directives and counts. A rejected rollback changes nothing.\n\n### Per-user configuration\n\n`userConfig` declares up to 20 typed settings in the versioned definition; its values are deliberately stored outside the definition, separately for each user (and the operator dashboard). Each field is `{ \"kind\": \"string\" | \"number\" | \"boolean\" | \"date\" | \"enum\", \"default\"?: ..., \"enum\"?: [...], \"label\"?: \"...\" }`. Defaults follow column rules, including enum membership; `required` is not allowed. A missing or obsolete stored value reads as its default, or `null` when no default is declared.\n\nUse `{ \"$state\": \"/user/<field>\" }` on a page for the read-only current-user binding; the field must be declared and the path cannot continue below it. Pure and bound reusable elements cannot bind `/user` directly — pass the value through an element prop from the consuming page. An agent acting on an owned user-requested task reads and edits that requester's preferences. `userConfig` schema changes are always migration-compatible and appear in migration reports; no migration directives are needed. Rollback restores the historical schema but never alters saved per-user values, so values can resurface when a field returns.\n\n### Theming\n\nAn optional top-level `\"theme\"` sets the preset the dashboard applies to the app's rendered canvas: a lowercase slug validated by shape only. The preset catalog ships with the dashboard and lives in `src/themes/presets.ts` and `src/themes/classics.ts`. Update this list and the `app-upsert` tool description when it changes. Current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, `paper` (the warm editorial paper look), and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette: hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `\"hive\"` is an explicit reset to the stock look even inside a themed dashboard.\n\nViewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.\n\nAn optional top-level `\"icon\"` sets the app's icon on the dashboard Apps page. It takes one of three shapes:\n\n- `{ \"type\": \"lucide\", \"icon\": \"<kebab-case lucide name>\", \"color\": \"#RRGGBB\" }` (`color` optional). The dashboard looks the name up in its curated icon catalog and shows a generic grid icon for an unknown name.\n- `{ \"type\": \"url\", \"url\": \"https://...\" }`: an https image link, at most 2048 characters, no credentials.\n- `{ \"type\": \"agent-fs\", \"path\": \"/apps/<appId>/icon.png\" }`: an image on the swarm's agent-fs drive. Add both `orgId` and `driveId` for another drive; never just one.\n\nThe server validates shape only. The dashboard shows the grid glyph while an image loads, when it fails to load, and when the viewer has no agent-fs connected, so omitting `icon` is always safe. `app-patch` replaces `icon` whole, so switching shapes leaves no keys from the old one.\n\n\nDistinguish the two rollback 400s. A lossy-migration 400 is fixable: copy the required `migration` entries from the message and retry. A target-snapshot validation 400 explicitly says that directives cannot repair that historical definition; use `app-history` and choose a different version.\n\nWhen a schema patch reports stale page/query bindings, repair them in that same patch. Page elements are atomic: replace the complete `pages.<page>.elements.<id>` declaration, removing any reference to a hidden or deleted column, instead of sending only the changed nested prop. This is also the repair move for older apps whose stored page already references an undeclared column; full-definition validation otherwise blocks every patch.\n\n## Definition reference\n\n```json\n{\n \"models\": {\n \"modelName\": {\n \"columns\": {\n \"externalId\": { \"kind\": \"string\" },\n \"title\": { \"kind\": \"string\" }\n }\n }\n },\n \"queries\": { \"queryName\": { \"model\": \"modelName\" } },\n \"actions\": { \"actionName\": { \"kind\": \"task\", \"prompt\": \"Review the current rows and report\" } },\n \"pages\": {\n \"main\": {\n \"root\": \"root\",\n \"elements\": { \"root\": { \"type\": \"Container\", \"props\": {} } }\n }\n },\n \"defaultPage\": \"main\",\n \"theme\": \"ember\"\n}\n```\n\nOptional top-level `layout: \"sidebar\"` turns on the app shell (see Pages, routes, and page trees). Without it every page renders on the plain canvas, exactly as before.\n\nModel, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-10 models and at most 20 reusable elements; each declared model has 1-40 columns. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.\n\n### Reusable elements\n\nTop-level `elements` are versioned inside the app definition and can be reused from the app's own pages or, when explicitly exported, from another app. They are private by default. Each entry declares a `mode`, optional typed `props`, one `root`, and a flat `elements` node map using the same validated tree vocabulary as a page:\n\n```json\n{\n \"elements\": {\n \"statCard\": {\n \"mode\": \"pure\",\n \"export\": true,\n \"props\": {\n \"label\": { \"kind\": \"string\", \"required\": true },\n \"value\": { \"kind\": \"number\", \"default\": 0 }\n },\n \"root\": \"card\",\n \"elements\": {\n \"card\": { \"type\": \"Card\", \"props\": {}, \"children\": [\"label\", \"slot\"] },\n \"label\": { \"type\": \"Metric\", \"props\": { \"label\": { \"$state\": \"/props/label\" }, \"value\": { \"$state\": \"/props/value\" } } },\n \"slot\": { \"type\": \"ElementSlot\", \"props\": {} }\n }\n }\n }\n}\n```\n\n- `pure` elements may read only their declared `/props/<name>` state; `$item` and `$index` are also legal inside repeated nodes. They cannot invoke any action step. A pure tree may contain at most one leaf `ElementSlot` where consumer children are inserted.\n- `bound` elements may additionally read the defining app's declared queries and actions and use its models. Those references are validated against the defining app, including hidden-column rules. Exported bound elements cannot use `app.navigate`; private bound elements may navigate within their defining app.\n- Prop kinds are `string`, `number`, `boolean`, `date`, or `enum`. An enum prop requires a non-empty `enum: [\"value\", ...]` values array. A literal default and each literal consumer value must match the kind and, for enums, be one of those values. A required prop without a default must be supplied.\n\nReference an element with an `ElementRef` node. Omit `app` for same-app reuse; cross-app references name the defining app id and require `export: true`. `instanceKey` is optional. Consumer `children` are accepted only when the target has an `ElementSlot`:\n\n```json\n{\n \"type\": \"ElementRef\",\n \"props\": {\n \"app\": \"<defining-app-id>\",\n \"element\": \"statCard\",\n \"props\": { \"label\": \"Open issues\", \"value\": 12 },\n \"instanceKey\": \"openIssues\"\n },\n \"children\": [\"details\"]\n}\n```\n\nElement references float to the defining app's current definition. `app` and `element` must be literal strings; dynamic references are not supported. The server rejects reference cycles and expansion deeper than five, missing/private targets, invalid props, and a breaking write to an exported element that other apps reference. Removing or unexporting an exported element, changing its mode, removing a declared prop, changing a prop kind, or adding a required prop without a default is breaking; publish the new contract under a new element name. If consumers are abandoned intentionally, retry the PUT, PATCH, or rollback with `\"forceElementBreak\": [\"elementName\"]`. The named consumers will then render an error once element rendering is available; deleting an entire app is deliberately not compatibility-gated.\n\n### Models\n\nEach column is `{ \"kind\": ..., \"required\"?: boolean, \"default\"?: ..., \"index\"?: boolean, \"enum\"?: string[], \"hidden\"?: boolean }`.\n\n| `kind` | Values and indexing |\n|---|---|\n| `string` | String value; set `index: true` only when equality lookups need it. |\n| `number` | Finite number; never indexed. |\n| `boolean` | Boolean; set `index: true` only when equality lookups need it. |\n| `date` | ISO-8601 string; never indexed. |\n| `enum` | String from the non-empty unique `enum` list; always indexed, without `index: true`. |\n| `json` | Any JSON value (object, array, nested) up to 256 KB serialized by default (`APPS_JSON_COLUMN_MAX_BYTES`); never indexed, and a named query cannot `filter` or `sort` on it. Not allowed for `userConfig` fields or element props. |\n\n`default` must match the column kind (and be one of the enum values). `required: true` rejects missing/null values unless a default supplies the value. `id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` — and the sync envelope `source`, `syncedAt`, `stale` — are system columns and reserved names. An app created before the sync envelope that declared ordinary columns with these names surfaces `definitionError` after upgrade until they are renamed: patch in a fresh column with a `{from}` migration directive, then purge the old one. Rows always expose `id`/`createdAt`/`updatedAt`; `createdBy`/`updatedBy` record the acting principal (`user:<id>`, `agent:<id>`, `operator`, or `sync:<source>` for engine writes) and are system-managed on every row write.\n\n### Sources and sync\n\nA model may declare up to 4 named `sources` — one-way inbound projections of an external system into its rows. The `script` connector is THE way to bring external data in (GitHub, Linear, any API): a saved script owns the fetch, its auth placeholders, and its paging. `swarm-tasks` is the one native connector, projecting this swarm's own task pool (`config`: `status`/`tags` comma-lists, `agentId`, `assetKey` namespace prefix, `limit` up to 200 — default 100, `includeHeartbeat`). Synced rows are readable by EVERY principal with `app.use` on the app; an unscoped `swarm-tasks` source publishes task prompts (truncated, secret-scrubbed) to all of them, so scope it with `config.assetKey`/`config.agentId` unless that exposure is intended. A user-invoked sync only ever pulls the invoking user's own requested tasks. Script sources run with their run-as identity's credentials — an agent-owned script runs as its owner and only the owner may wire it; an owner-less catalog (global) script runs as the LEAD, so only the lead or the operator can wire or alter such a source (stored references stay valid with their args and connection pinned).\n\n```json\n{\n \"models\": {\n \"issue\": {\n \"columns\": {\n \"issueKey\": { \"kind\": \"string\" },\n \"title\": { \"kind\": \"string\", \"source\": { \"of\": \"gh\", \"field\": \"title\" } },\n \"openedAt\": { \"kind\": \"date\", \"source\": { \"of\": \"gh\", \"field\": \"created_at\", \"transform\": \"date-parse\" } },\n \"note\": { \"kind\": \"string\" }\n },\n \"sources\": {\n \"gh\": { \"connector\": \"script\", \"scriptId\": \"<script-uuid>\", \"joinKey\": \"issueKey\", \"args\": { \"repo\": \"owner/name\" }, \"connection\": \"github\" }\n }\n }\n }\n}\n```\n\n- **Join key**: each source names a `joinKey` — an owned, non-hidden `string` column carrying the external identity. It must not be `required`, must not declare a `default`, and cannot itself be source-bound. A row belongs to at most ONE source (`row.source`).\n- **Column bindings**: `{ \"of\": \"<sourceName>\", \"field\": \"user.login\", \"transform\"? }` projects a (dotted-path) field of the pulled record into the column on every pass. Transforms and their required column kinds: `slug`/`lower`/`upper` → `string`, `cents` → `number` (×100, rounded), `date-parse` → `date` (ISO). A failed transform nulls that one column and warns; it never fails the pass.\n- **Read-only contract**: source-bound columns and the join key reject every direct write (row create/patch/bulk) with a path-bearing issue — mutate them via the source or a sync refresh. Owned columns on the same model stay writable. Every `required` owned column on a sourced model must declare a `default`, because sync-created rows cannot supply it.\n- **Provenance**: synced rows carry `source` (owner), `syncedAt` (last confirmed presence — sortable), and `stale` (true when a complete pull no longer returned the record; clears on reappearance). `syncedAt` advances on every confirmed row WITHOUT touching `updatedAt`; `updatedAt` moves only when projected data actually changed.\n- **`connection`** (optional, script sources): names a connections-system slug the source depends on. It buys write-time validation plus a preflight before every pull; it does not by itself gate egress. Credentials resolve for the sync run-as identity — the script's owner when it has one, else the lead agent — so global connections always work and agent-scoped ones need matching script ownership. The slug is injected into the script's args as `connection`, letting one generic script serve N connections.\n\n**The canonical sync-script contract** (every sync script, always):\n\n```ts\nexport default async function run(args, ctx) {\n // args = { ...source.args, app: { id }, model: \"<model>\", source: \"<sourceName>\", connection?: \"<slug>\" }\n const records = [{ key: \"42\", fields: { title: \"…\", created_at: \"…\" } }];\n return { records, complete: true }; // or return the bare array — a bare array IS a complete snapshot\n}\n```\n\nReturn `Array<{ key, fields }>` or `{ records, complete? }`. `key` is the external identity the engine joins on `joinKey` (numbers are coerced to strings); `fields` is the bag bindings project from. Return `complete: false` whenever the pull window may have missed records — a paged fetch, a hit `limit`, or client-side filtering of a full page. An incomplete pull skips the stale sweep, so rows outside a narrow window are not falsely marked stale; compute `complete` BEFORE any client-side filtering. Hard cap 500 records per pull (over-cap pulls truncate and count as incomplete). An invalid return shape, thrown error, or non-zero exit fails the pass with zero row churn.\n\nThe seeded catalog script `github-issues-pull` is the worked example (placeholder auth via `[REDACTED:GITHUB_TOKEN]`, PR filtering, `complete` computed before filtering). For scheduled refreshes, point a `targetType: \"script\"` schedule at the seeded `app-sync-run` with `scriptArgs: { \"appId\": \"<id>\", \"model\"?, \"source\"? }`.\n\n**Three refresh doors, one engine**: `POST /api/apps/<id>/sync` (body `{ \"model\"?, \"source\"? }`), a `sync` action kind, and the `app-sync` MCP tool (`ctx.swarm.app_sync` from scripts). `{model?, source?}` fans out to every matching (model × source) pair; each pass reports `{ pulled, created, updated, refreshed, unchanged, markedStale, warnings }`. A pair already syncing in this API process short-circuits with `alreadyRunning: true` instead of pulling twice. Each pair's last-pass status (`lastFinishedAt`, counts, `error?`) comes back as `syncStatus` — keyed `\"<model>:<source>\"` — on `GET /api/apps/<id>` and in `app-get` data, so UI and agents can render \"last synced / last error\" without extra calls.\n\n### Freshness and the refresh button\n\nFreshness renders with the existing column kinds — no special components. Give the table `{ \"key\": \"syncedAt\", \"kind\": \"date\" }` and `{ \"key\": \"stale\", \"kind\": \"badge\", \"tones\": { \"true\": \"warning\" } }` columns, declare a `sync` action, and wire a Button to it:\n\n```json\n{\n \"actions\": { \"refresh\": { \"kind\": \"sync\" } },\n \"pages\": {\n \"main\": {\n \"root\": \"root\",\n \"elements\": {\n \"root\": { \"type\": \"Container\", \"props\": {}, \"children\": [\"refreshBtn\", \"issuesTable\"] },\n \"refreshBtn\": {\n \"type\": \"Button\",\n \"props\": { \"label\": \"Refresh\" },\n \"on\": { \"press\": [{ \"action\": \"app.action\", \"params\": { \"name\": \"refresh\" } }] }\n },\n \"issuesTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIssues/data\" },\n \"columns\": [\n { \"key\": \"title\", \"label\": \"Issue\" },\n { \"key\": \"syncedAt\", \"label\": \"Synced\", \"kind\": \"date\" },\n { \"key\": \"stale\", \"label\": \"Stale\", \"kind\": \"badge\", \"tones\": { \"true\": \"warning\" } }\n ]\n }\n }\n }\n }\n }\n}\n```\n\nA `sync` action answers the script-action state shape (`/actions/refresh` → `running` → `ok`/`error`, result under `result.passes`), so the page's queries refetch when it completes. Use `app-query` to READ rows (named queries may filter on `stale`/`source` and sort by `syncedAt`); use `app-sync` to REFRESH sources; never poll a sync door in a loop — schedule it or give people the button.\n\n### Queries\n\nA named query is:\n\n```json\n{\n \"model\": \"idea\",\n \"filter\": { \"status\": \"open\" },\n \"sort\": { \"column\": \"createdAt\", \"dir\": \"desc\" },\n \"limit\": 100\n}\n```\n\n`filter` is a strict AND of equality checks. A filter may target a declared model column or a system column (`id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and on synced models `source`, `syncedAt`, `stale`) — filtering on `id` is the universal way to select one row for a detail view, and `{ \"stale\": true }` selects rows a complete pull stopped confirming. A literal value must match the column's kind; date filters compare the stored raw ISO string, not parsed instants. Omit `limit` for the default 200 rows, or set an integer from 1 through 1000. `sort.column` is a non-`json` model column, `createdAt`, `updatedAt`, or `syncedAt`; `dir` is `asc` or `desc`. Query runtime state is `{ data, loading, error }` under `/queries/<queryName>`.\n\nA filter value may instead be exactly `{ \"$param\": \"<name>\" }`. At execution, the caller supplies that name and the server coerces its value to the filtered column's kind before equality matching:\n\n```json\n{\n \"queries\": {\n \"issueDetail\": { \"model\": \"issue\", \"filter\": { \"issueId\": { \"$param\": \"issueId\" } }, \"limit\": 1 }\n }\n}\n```\n\nThe placeholder object must contain only `$param`. Missing caller values fail loudly rather than returning unfiltered rows: HTTP reports 400 and `app-query` returns a tool error listing every missing name. Supplying a param name the query does not reference is also an error. The app UI supplies current declared route params automatically. Direct calls use `app-query({ appId, query: \"issueDetail\", params: { issueId: 42 } })` or `ctx.swarm.app_query({ appId, query: \"issueDetail\", params: { issueId: 42 } })`.\n\n### Custom actions\n\nActions are optional (maximum 20) and are invoked from the page with the `app.action` runtime action.\n\n```json\n{\n \"actions\": {\n \"recalculate\": {\n \"kind\": \"script\",\n \"scriptId\": \"00000000-0000-4000-8000-000000000000\",\n \"args\": { \"mode\": \"fast\" }\n },\n \"triage\": {\n \"kind\": \"task\",\n \"prompt\": \"Triage this idea and report a recommendation\"\n }\n }\n}\n```\n\n| Kind | Contract |\n|---|---|\n| `script` | `scriptId` must identify an existing script; optional `args` are defaults. Invocation input overrides same-named defaults, and the runtime also supplies `app: { id }`. |\n| `task` | `prompt` must be non-empty; omit `agentId` to use default (lead) assignment. Only set `agentId` to a real agent UUID. Invocation `input` is included as context for the task prompt. Spawned tasks carry asset key `shared/app:<appId>/action:<name>/`, so a `swarm-tasks` source with `config.assetKey: \"shared/app:<appId>/\"` pulls back the tasks this app spawned. |\n| `sync` | Optional `model` and `source` narrow which (model × source) pairs refresh; omitting both syncs every pair the app declares. At least one pair must exist. Answers the script-kind state shape with per-pass results under `result.passes`. |\n\n- Invocation state lands at `/actions/<name>` as `{ status, result?, error?, taskId?, taskStatus? }`, where `status` is `\"running\"`, `\"ok\"`, or `\"error\"`.\n\nUse a task action named Tackle when a person should hand one issue row to the swarm. Pass the complete current row under `input.issue`; `{ \"$row\": \"\" }` resolves to the whole row and that context lands in the task prompt.\n\n```json\n{\n \"actions\": {\n \"tackle\": { \"kind\": \"task\", \"prompt\": \"Tackle this issue. Inspect the supplied issue context, do the work, and report the outcome.\" }\n },\n \"pages\": {\n \"main\": {\n \"root\": \"issuesTable\",\n \"elements\": {\n \"issuesTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIssues/data\" },\n \"columns\": [{ \"key\": \"title\", \"label\": \"Issue\" }],\n \"rowActions\": [{\n \"label\": \"Tackle\",\n \"actions\": [{\n \"action\": \"app.action\",\n \"params\": { \"name\": \"tackle\", \"input\": { \"issue\": { \"$row\": \"\" } } }\n }]\n }]\n }\n }\n }\n }\n },\n \"defaultPage\": \"main\"\n}\n```\n\nFor direct MCP calls, `app-query` accepts `{ appId, query, params? }` and returns rows from that declared named query; every supplied param must be referenced by a `$param` filter in that query. Use it when an agent needs to read app state without scraping the UI.\n\nSaved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.\n\n### Pages, routes, and page trees\n\n`pages` is a map of independently validated page trees and `defaultPage` must name one entry. Each page may also declare a display `title` and typed route `params`. On every non-default page the runtime automatically renders breadcrumbs (`<default page title> › <current page title>`, first crumb navigates back) — including in chromeless embeds — so a detail page does NOT need its own back button; give pages good `title`s instead. This complete pattern connects a table row to a typed detail route and its parameterized query:\n\n```json\n{\n \"models\": {\n \"issue\": {\n \"columns\": {\n \"issueId\": { \"kind\": \"number\" },\n \"title\": { \"kind\": \"string\" },\n \"status\": { \"kind\": \"string\" }\n }\n }\n },\n \"queries\": {\n \"allIssues\": { \"model\": \"issue\" },\n \"issueDetail\": {\n \"model\": \"issue\",\n \"filter\": { \"issueId\": { \"$param\": \"issueId\" } },\n \"limit\": 1\n }\n },\n \"pages\": {\n \"issues\": {\n \"title\": \"Issues\",\n \"root\": \"issuesTable\",\n \"elements\": {\n \"issuesTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIssues/data\" },\n \"columns\": [\n { \"key\": \"title\", \"label\": \"Issue\" },\n { \"key\": \"status\", \"label\": \"Status\", \"kind\": \"badge\" }\n ],\n \"rowActions\": [{\n \"label\": \"Open\",\n \"actions\": [{\n \"action\": \"app.navigate\",\n \"params\": {\n \"page\": \"detail\",\n \"params\": { \"issueId\": { \"$row\": \"issueId\" } }\n }\n }]\n }]\n }\n }\n }\n },\n \"detail\": {\n \"title\": \"Issue detail\",\n \"params\": { \"issueId\": { \"kind\": \"number\", \"required\": true } },\n \"root\": \"detail\",\n \"elements\": {\n \"detail\": {\n \"type\": \"DetailList\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/issueDetail/data/0\" },\n \"fields\": [{ \"key\": \"title\", \"label\": \"Issue\" }]\n }\n }\n }\n }\n },\n \"defaultPage\": \"issues\"\n}\n```\n\nDrawer variant: declare a route param on the containing page, set the Drawer `props.param` to that literal param name, and use the same `app.navigate` shape targeting that page with the row id assigned to the Drawer's param. The Drawer then opens from route state without a separate action contract.\n\nApp shell (`layout: \"sidebar\"` at the top level of the definition): every page renders inside a left sidebar that lists the app's pages and a sticky page header. Per page:\n\n- `title`: the sidebar label and the header heading (defaults to the page name).\n- `icon`: one catalog icon name (the list under Component catalog) before the sidebar label; unknown names are rejected.\n- `description`: one line under the header title (at most 280 characters).\n- `headerActions`: the key of one element of this page, rendered in the header's actions slot (right side), e.g. a Refresh `Button` with `on.press: [{ \"action\": \"app.refresh\" }]` or a row `Stack` of buttons. It is a second root: it must exist in the page's `elements` and must NOT also be reachable from `root`. It shares the page's state and actions.\n- `nav: false`: leave the page out of the sidebar. Pages with a `required` param never list (they cannot open without it); open them with `app.navigate`.\n\nThe sidebar lists pages in definition order and marks the current one. Below 768px it folds into a menu button at the left of the header. Crumbs back to the default page show in the header only on pages the sidebar does not list. The shell renders in every view mode: inside the bordered canvas (default view, under the dashboard header that names the app), under the slim bar in `?mode=full`, and as the whole viewport in `?mode=chromeless`, where the sidebar also shows the app name (it is the only navigation inside an iframe). `headerActions` and `nav` without `layout: \"sidebar\"` are rejected; `icon` and `description` are accepted and unused.\n\n```json\n{\n \"layout\": \"sidebar\",\n \"defaultPage\": \"overview\",\n \"pages\": {\n \"overview\": {\n \"title\": \"Overview\",\n \"icon\": \"activity\",\n \"description\": \"Deploys and spend, last 14 days.\",\n \"headerActions\": \"refresh\",\n \"root\": \"root\",\n \"elements\": {\n \"root\": { \"type\": \"Stack\", \"props\": {}, \"children\": [\"spend\"] },\n \"spend\": {\n \"type\": \"Chart\",\n \"props\": {\n \"kind\": \"area\",\n \"data\": { \"$state\": \"/queries/days/data\" },\n \"loading\": { \"$state\": \"/queries/days/loading\" },\n \"x\": \"date\",\n \"xType\": \"time\",\n \"format\": \"currency\",\n \"series\": [{ \"key\": \"spend\", \"label\": \"Spend\" }]\n }\n },\n \"refresh\": {\n \"type\": \"Button\",\n \"props\": { \"label\": \"Refresh\", \"icon\": \"refresh-cw\", \"variant\": \"outline\", \"size\": \"sm\" },\n \"on\": { \"press\": [{ \"action\": \"app.refresh\" }] }\n }\n }\n },\n \"settings\": { \"title\": \"Settings\", \"icon\": \"pencil\", \"root\": \"root\", \"elements\": { \"root\": { \"type\": \"Text\", \"props\": { \"content\": \"…\" } } } }\n }\n}\n```\n\nParam `kind` is `string` by default, or `number` / `boolean`; `required` defaults to false. The names `mode`, `apiUrl`, `apiKey`, `email`, and `name` are reserved. `/apps/<id>` renders `defaultPage`; `/apps/<id>/p/<page>?issueId=42` is the shareable deep link for another page. Browser navigation is client-side, so app state and polled data stay warm across page changes.\n\nWithin each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Accordion, Container, Card, Section, Drawer, and Dialog). `watch` maps state paths to an action step or chain.\n\n## Component catalog (all 45)\n\nProps reject unknown keys. A `{\"$state\":\"...\"}` binding may replace a literal prop value at any depth.\n\nIcons: every `icon` prop (and the `Icon` block) takes one name from a curated lucide set: `plus`, `refresh-cw`, `search`, `filter`, `download`, `upload`, `external-link`, `copy`, `check`, `x`, `trash-2`, `pencil`, `eye`, `calendar`, `clock`, `user`, `users`, `bot`, `git-pull-request`, `git-branch`, `github`, `slack`, `mail`, `link`, `file-text`, `folder`, `database`, `zap`, `sparkles`, `flag`, `star`, `tag`, `alert-triangle`, `info`, `circle-check`, `trending-up`, `trending-down`, `dollar-sign`, `activity`, `rocket`. Any other name is rejected.\n\nTones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `error`, `info`, `pending`, `warning`, or `paused`.\n\n| Component | Required props | Optional props / values |\n|---|---|---|\n| `Stack` | none | Primary layout; `direction: \"column\", \"row\"`, `gap`, `padding: \"none\", \"xs\", \"sm\", \"md\", \"lg\", \"xl\"`; `align: \"start\", \"center\", \"end\", \"stretch\"`, `justify: \"start\", \"center\", \"end\", \"between\"`, `wrap`; `motion: \"rise\"` (default), `\"fade\"`, or `\"none\"` (see Motion below); `fill` (grow to fill a `fill`-aware parent; see Layout below); has the `default` child slot. |\n| `Grid` | none | Responsive `columns`: integer 1 through 6, or `{ base, sm, md, lg }` counts 1 through 6; `gap` uses the Stack spacing values; has the `default` child slot. |\n| `Split` | none | `ratio: \"1-1\", \"1-2\", \"2-1\", \"1-3\", \"3-1\"`, `gap`, `collapseBelow: \"sm\", \"md\", \"lg\"`, `reverse`, `fill` (same contract as Stack); has the positional `default` child slot. |\n| `Divider` | none | `label`, `orientation: \"horizontal\"` (default) or `\"vertical\"` (a rule between the items of a row `Stack`, as tall as the row); no children. |\n| `Tabs` | `id`, `tabs` | `tabs` entries are `{ key, label?, icon?, count? }` (`count` is a number shown as a small pill); `defaultTab`; `variant: \"line\"` (default) or `\"segmented\"` (a compact segmented control, same state and warm panels); has the positional `default` child slot. |\n| `Accordion` | `id`, `items` | Grouped collapsible sections. `items` entries are `{ key, title, description?, icon? }`; children are positional like Tabs (`children[i]` is the body of `items[i]`, same count, validated). `type: \"single\"` (default: opening one closes the others, and the open one can close) or `\"multiple\"`. Open keys are client state at `{ \"$state\": \"/ui/<id>/open\" }`, always an array; `defaultOpen` lists the keys open on first render. Bodies mount only while open. `Section collapsible` stays the one-item form. |\n| `Container` | none | Legacy layout primitive; prefer Stack. `direction: \"row\", \"column\"`, `gap: \"none\", \"sm\", \"md\", \"lg\"`; has the `default` child slot. |\n| `Card` | none | `title`, `description`; has the `default` child slot. |\n| `Heading` | `text` | `level: \"h1\", \"h2\", or \"h3\"`. |\n| `Text` | `content` | `tone: \"default\" or \"muted\"`. |\n| `Markdown` | `content` | Rendered Markdown for help, instructions, and rich prose; no children. A link to a GitHub PR, issue, commit or repo, a dashboard task, agent, session or app, or an agent-fs file renders as a chip (icon plus short label), like agent output in a session; `[text](url)` keeps its text. |\n| `SearchInput` | `id` | `placeholder`, `label`, `shortcut` (one key, usually `\"/\"`: shows a keycap and focuses the field); writes debounced text to `/ui/<id>/value`; no children. |\n| `Select` | `id`, `options` | `options` are strings or `{ value, label?, icon?, hint? }`; `placeholder`, `label`, `clearable`, `searchable` (type to filter; on by default past 8 options), `searchPlaceholder`, `multiple`, `defaultValue` (seeds `/ui/<id>/value` once, before any interaction; a one-entry array with `multiple`); writes a string or null to `/ui/<id>/value`, or with `multiple` a string array (empty = nothing picked); no children. |\n| `NumberInput` | `id` | `label`, `placeholder`, `min`, `max`; a text field with a decimal keyboard that writes the parsed number to `/ui/<id>/value` on every change (no debounce), or null when the field is empty; non-numeric text (a bare `-` mid-edit, letters) leaves the stored value untouched; `min`/`max` clamp the stored value and the visible text snaps to it when the field loses focus; no children. |\n| `Chips` | `id`, `options` | Toggle chips for quick filters. `options` are strings or `{ value, label?, icon? }`; `multiple`; `label` (group name for screen readers). Writes a string or null to `/ui/<id>/value`, or a string array with `multiple`; pressing the selected chip clears it. |\n| `Button` | `label` | `variant: \"default\", \"secondary\", \"outline\", \"ghost\", \"destructive\", or \"destructive-outline\"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: \"<actionName>\"` swaps the label for a spinner while that custom action's `/actions/<name>/status` is `\"running\"` (presses are ignored), then shows a check and `successLabel` for about 1.5s when it turns `\"ok\"`; `icon`, `iconPosition: \"start\" or \"end\"`; `size: \"sm\", \"default\", or \"lg\"`; `shortcut` (one key, shown as a keycap, presses the button); `hint` (tooltip); dispatch with element-level `on.press`. |\n| `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: \"up\", \"down\", or \"flat\", label }`; `info` (explanation tooltip next to the label). `sparkline`: a small trend line under the value in the `tone` color, from an array of numbers (`null` is a gap) or from rows (bind `/queries/<name>/data`) read through `sparklineKey`; fewer than two points draws nothing. `format: \"number\"`, `\"currency\"` (with `currency`, an ISO code, default `USD`) or `\"percent\"` (a ratio: 0.42 is 42%) formats a numeric `value`, like Chart; a string value shows as is. |\n| `Chart` | `kind`, `x`, `series` | `kind: \"line\", \"area\", \"bar\", \"pie\" or \"donut\"`; bind `data` / `loading` / `error` to a named query like Table. `x` is the row field on the x axis; `xType: \"category\"` (default, row order) or `\"time\"` (ISO date or epoch ms, sorted, date ticks; rows whose `x` does not parse are dropped). `series`: 1-8 `{ key, label?, color? }`, `color` one of `chart-1`..`chart-5`, `primary`, `success`, `warning`, `error`, `info`, `muted` (default palette, in order: `primary`, `chart-2`..`chart-5`). `stacked` stacks area and bar series (lines never stack). `format: \"number\"` (default), `\"currency\"` (with `currency`, an ISO code, default `USD`) or `\"percent\"` (values are ratios: 0.42 is 42%). Tooltip on hover; the legend shows with two or more series (`legend` forces it on or off). `height` 120-640 px (default 240); `emptyMessage` (default \"No data yet\"). `x` and every `series[].key` must be columns of the bound query's model. `pie` and `donut` take exactly one series: `x` is the slice label, each row with a positive value is a slice labelled with its share, the tooltip adds the share to the formatted value, and the legend defaults on (`xType` and `stacked` do not apply). Wrap it in a `Card` for a title. |\n| `Alert` | `message` | `title`, `tone: \"info\", \"success\", \"warning\", or \"error\"`, `icon` (overrides the tone icon), `actionLabel` (a button inside the callout that emits `press`; wire it with `on.press`). |\n| `Badge` | `text` | `text` is string or number; `tone`; `icon` replaces the dot; `variant: \"tag\"` (default uppercase chip), `\"status\"` (sentence-case pill), `\"count\"` (numeric pill), or `\"beta\"` (the BETA tag); `status` (a lifecycle value renders the dashboard status chip); `hint` (tooltip; the beta tag's explanation). |\n| `Icon` | `name` | `size: \"sm\", \"md\", or \"lg\"`, `tone: \"default\", \"muted\", \"success\", \"warning\", \"error\", or \"info\"`, `label` (accessible name; decorative without it). |\n| `Progress` | `value` | `max` (default 100), `tone`, `label`, `variant: \"bar\"` (default) or `\"ring\"` (the dashboard progress ring; ignores `tone`), `showValue` (default true: percent for a bar, `value / max` for a ring). |\n| `EmptyState` | `title` | `icon` (default inbox), `body`, `actionLabel` (a button that emits `press`; wire it with `on.press`). |\n| `CopyButton` | `value` | `value` is string or number; `label` is the visible text, icon-only without it. Renders nothing for an empty value. |\n| `Kbd` | `keys` | Keycaps, one per string (`[\"⌘\", \"K\"]`). Display only. |\n| `Skeleton` | `shape` | `shape: \"line\", \"block\", \"rows\", \"metric\", or \"card\"`; `count` (1-20: lines, rows, tiles, or cards); `height` (px, `block` only, default 128). Show it with `visible` bound to a query's `loading`. |\n| `Spinner` | none | `variant: \"ring\", \"ellipsis\", or \"bars\"` (default: the dashboard spinner), `size: \"sm\" or \"md\"`, `label` (visible text and accessible name). |\n| `AvatarStack` | `users` | `users` are display names (initials avatars); `max` (default 4) before a `+N` count. Hover lists every name. |\n| `Section` | `title` | `description`, `collapsible`, `defaultOpen` (default true); has the `default` child slot. |\n| `Table` | `columns` | `data`, `loading`, `refreshing`, `error`, `emptyMessage`, `emptyState`, `rowActions`, `id`, `selectable`, `bulkActions`, `filterable`, `clearState`, `onRetry`, `onRowClick`, `selectedId`, `rowId`, `mobile`, `mobileFields`, `search`, `filters`; see below. |\n| `Form` | `id`, `fields`, `onSubmit` | `title`, `submitLabel`; see below. |\n| `Drawer` | `param` | `title`, `description`, `side: \"right\" or \"left\"`, `size: \"sm\", \"md\" (default), \"lg\", or \"xl\"` (about 480/660/900/1010px at 1440px; grows with the viewport up to 640/960/1280/1600px; full width on phones), `actions` (sticky footer buttons; see below), `presentation: \"sheet\"` (default) or `\"split\"` (an inline right pane beside the page; see below); has the `default` child slot. |\n| `Dialog` | `param` | A centered modal with the Drawer route contract: open exactly while the page param named by `param` is set; Escape, the X or a click outside clears it. `title`, `description`, `size: \"sm\", \"md\" (default), or \"lg\"`, `actions` (footer buttons, Drawer rules). Use it for a short form opened from `headerActions`; after the write, an `app.navigate` without the param closes it. Has the `default` child slot. |\n| `DetailList` | `fields` | `data`, `emptyMessage`, `columns: 1 or 2`, `loading` (bind `/queries/<name>/loading` for skeleton fields while loading); renders one record without edit controls; see below for field kinds. |\n| `CardGrid` | `titleKey` | `data`, `loading`, `error`, `emptyMessage`, `imageKey`, `fields`, `columns`, `onClick`; one card per row for record browsers; see below. |\n| `Kanban` | `columnField`, `columns`, `titleField` | `data`, `loading`, `cardFields`, `idField` (default `id`), `onMove`, `onCardClick`; see below. |\n| `Calendar` | `startField`, `titleField` | `data`, `loading`, `endField`, `idField`, `onSelect`; read-only month grid; see below. |\n| `ContributionGraph` | none | `data`, `loading`, `dateField` (default `date`), `countField`, `days` (7-730, default 365); read-only activity heatmap. |\n| `Tree` | `id`, `nodes` | `label`, `maxHeight` (default `480px`), `fill`; collapsible outline of a doc-shaped value that writes the clicked node key to `/ui/<id>/value`; see below. |\n| `Files` | `path` | `mode: \"list\"` (default) or `\"browser\"`, `selectedPath`, `emptyMessage`, `maxHeight` (default `480px`), `fill`, `onSelect`, `upload`; an agent-fs folder listing read as the viewer; see below. |\n| `File` | `path` | `height`, `fill`; one agent-fs file (Markdown, image, PDF, text) read as the viewer; see below. |\n| `DateRange` | `id` | `presets` (any of `7d`, `30d`, `90d`, `mtd`, `custom`; default all five), `defaultPreset` (default the first), `label`; writes `/ui/<id>/from` and `/ui/<id>/to`; see below. |\n| `Timeline` | `timeField`, `titleField` | `data`, `loading`, `descriptionField`, `statusField`, `tones`, `icon`, `emptyMessage`, `onSelect`; vertical event list, newest first, grouped by day; see below. |\n| `SchemaForm` | `id`, `schema` | `value`, `baseDoc`, `nodeKey`, `onChange`, `fill`; form generated from a JSON schema's `properties`, mirrored to `/ui/<id>/value`; see below. |\n| `Approval` | `requestId` | `showResolved` (default true), `compact`, `onResolved`; one approval request answered in place by the viewer; see below. |\n| `SessionThread` | `id`, `sessionKey` | `scope`, `placeholder`, `onDispatch`, `fill`; the dashboard's session conversation (the \"Session about this page\" panel) for one session per viewer and key, with a composer that steers or chains tasks; the draft is mirrored to `/ui/<id>/value`; see below. |\n\nTable details:\n\n- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: \"left\" or \"right\", align?: \"start\" or \"end\", truncate?: \"end\" or \"middle\", icon?, tooltip?: \"<row field>\", hint?: string, popover?: { title?, fields, trigger? }, href?: \"<row field>\", linkLabel?: \"<template>\", max?: number, format?: \"<template>\", currency?: \"<ISO 4217>\", onChange?: chain, filter?: \"values\" or \"text\" or false, muted?: string[] }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `checkbox`, `link`, `json`, `currency`, or `percent`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. `currency` shows a number as money in the column's `currency` (an uppercase ISO 4217 code, default `USD`): `1234.5` is `$1,234.50`. `percent` reads a ratio: `0.42` is `42%`. Both right-align and show a non-numeric value as is. Pin id/actions columns so they survive horizontal scroll on narrow viewports.\n - `status`: lifecycle values (`pending`, `in_progress`, `running`, `completed`, `failed`, `cancelled`, `paused`, `reviewing`, ...) render the dashboard status chip with its icon; other values use `tones` like `badge`.\n - `user` / `agent`: avatar plus name. `relative` (and `date`): smart time, exact time on hover. `duration`: milliseconds as `1m 23s`. `progress`: a bar against `max` (default 100). `copy`: the value plus a copy button. `link`: a smart link (see Smart links, tooltips and popovers below); any other http(s) URL opens in a new tab and other values render as text.\n - `switch` / `checkbox`: a toggle or a checkbox bound to a boolean column. `onChange` runs with `$row` = the row with this column already set to the new value, e.g. `[{ \"action\": \"app.mutate\", \"params\": { \"model\": \"m\", \"op\": \"update\", \"rowId\": { \"$row\": \"id\" }, \"values\": { \"enabled\": { \"$row\": \"enabled\" } } } }]`. Without `onChange` the control is read-only. Each toggle is a model write, so to pick rows for a bulk action use `selectable` (below), not a boolean column.\n - Numbers, durations and progress right-align by default. `truncate: \"middle\"` keeps both ends of ids and paths. `icon` shows in the header; `tooltip` names a row field shown in a styled tooltip on the cell (when the cell is plain text that gets cut off, the tooltip shows its full text without any config).\n - `format`: a `{{field}}` template that combines several row fields into one cell, e.g. `\"{{name}} ({{status}})\"`. Placeholder names match `[\\w.]+` (letters, digits, `_` and `.`; no hyphens or spaces). Each placeholder reads that row field as-is (a dotted name such as `{{owner.name}}` is a literal column name, not a nested path); a missing or null field becomes an empty string and an object or array becomes a JSON preview cut to 120 characters. The whole cell is capped at 500 characters. A templated column ignores `kind`, shows the same text in the phone list, and sorts by the composed text. `search` and `filters` still read the column's `key`.\n - `muted: [\"none\", \"no\"]`: those cell values (matched case-insensitively) render as a quiet `—` instead of a pill or text, for columns that are mostly `none` / `no`. The value stays in the data, in the filter list, as a hover title and for screen readers; the phone list leaves it out. Not applied to `switch` / `checkbox` cells.\n- `selectable` + `id`: a leading pinned checkbox column. The header checkbox selects every row left after `search` / `filters` (checked, unchecked or indeterminate; clicking it again clears those rows), and shift-click selects a range in the order shown. The selection is client state at `{ \"$state\": \"/ui/<id>/selected\" }`, an array of row ids (the `rowId` field, default `id`, as strings). It is never a model write and is not shared with other viewers. `id` is a literal like `SearchInput.id`, and the validator requires it with `selectable` or `bulkActions`. Selected rows that disappear from the data drop out of the selection.\n- `bulkActions[]`: `{ label, variant?, icon?, confirm?, actions }`, the `rowActions` shape without `placement`; a non-empty list implies `selectable`. A bar under the table shows `N selected`, the buttons and Clear while the selection is non-empty. Chains have no `$row`; pass the ids with `{ \"$state\": \"/ui/<id>/selected\" }`, e.g. `{ \"action\": \"app.action\", \"params\": { \"name\": \"enqueue\", \"input\": { \"prs\": { \"$state\": \"/ui/prTable/selected\" } } } }`. Confirm rules match `rowActions`; the dialog always adds the selection size (`Applies to 3 selected rows.`). The selection is locked while the chain runs. It clears (only the rows the chain acted on) once every step succeeded, waiting for a task-backed `app.action` to finish; a failed `app.mutate` or a failed task stops the chain and keeps the selection for a retry.\n- `filterable: true` + `id`: built-in column filters. Each filterable column gets a filter button in its header: `badge`, `status`, `enum`, `boolean`, `user` and `agent` columns open a checkbox list of the distinct values with row counts (the counts follow the other active filters, so a second tick shows what it adds); a column with no kind (or `text` / `string`) opens a contains-text field; numbers, dates, links and `format` columns get none. `columns[].filter` overrides per column: `\"values\"` or `\"text\"` (works without `filterable`, and is how a `format` column opts in), or `false` to opt out. Active filters show as removable pills above the table with Clear all. The state is client state at `{ \"$state\": \"/ui/<id>/filters\" }`, an object with one entry per column (`/ui/<id>/filters/<column>`): a string array for a list, a string for text; other elements can read it. It composes with `search` and `filters`: a row must pass all three. Below 768px the header menus become one Filters button above the card list. `id` is required (the validator checks it).\n- `clearState`: state paths the Table's Clear filters button and the pills' Clear all also reset, e.g. `[\"/ui/prSearch/value\"]` for the `SearchInput` feeding `search`. Only `/ui/<id>/...` paths of controls on the page. Without it, those controls keep their value and the no-match state only offers Clear filters for the built-in filters.\n- Loading and errors: the first load (no rows yet) shows a skeleton shaped like the table, with its header labels. `loading` (`/queries/<name>/loading`) is the first load only. Bind `refreshing` to `{ \"$state\": \"/queries/<name>/fetching\" }` (true during any fetch, including the 5s poll and `app.refresh`) and a refetch with rows showing runs a slim bar along the top edge, on phones too, and never dims, covers or blanks a row. A failed query shows the error callout with a Retry button; `onRetry` is the chain it runs (default `[{ \"action\": \"app.refresh\" }]`, which re-runs every query on the page). With rows already loaded the callout sits above the stale rows; with none, it is the whole state (no empty message). A search or filter that hides every row shows \"No rows match\" with a Clear filters button; with header filters the table stays in place (header and open filter input included) and the button sits under it.\n- Smart links, tooltips and popovers (Table, DetailList, CardGrid, Markdown):\n - A `link` cell (Table `kind: \"link\"`, DetailList and CardGrid `kind: \"link\"`) shows a chip with an icon and a short label when its value is a GitHub PR, issue, commit or repo URL (`agent-swarm#2605`, `agent-swarm@a1b2c3d`, `owner/repo`), the GitHub shorthand `owner/repo#N` or `owner/repo@sha`, a dashboard task, agent, session, app, page or workflow URL (shown by its name once the dashboard knows it, else `Task 1f6feea0`), or an agent-fs file. GitHub links open in a new tab; dashboard links stay in the app. Any other http(s) URL is a plain external link, and any other value is text. Only `github.com` links are GitHub links.\n - `href: \"<row field>\"` (Table column, DetailList or CardGrid field) takes the URL from another row field, so a cell can show one field and link with another: `{ \"key\": \"number\", \"label\": \"PR\", \"format\": \"{{repo}}#{{number}}\", \"href\": \"url\" }` shows `agent-swarm#2605` as a PR chip. With `href` the cell's own text (or `format`) is the label. `linkLabel: \"<template>\"` (same `{{field}}` rules as `format`) sets the label instead, e.g. `\"Lead review\"` on a `kind: \"link\"` column.\n - `hint: \"<text>\"` on a column adds a header tooltip. A header cut off by the column width also shows its full label in the tooltip, with no config.\n - `popover: { title?: \"<template>\", fields: [...], trigger?: \"hover\" | \"click\" }` on a Table column opens a popover from the cell that lists up to 12 fields of the row, in the DetailList field shape (`{ key, label?, kind?, tones?, href?, linkLabel? }`, any DetailList kind). It opens on hover or keyboard focus by default and lets the pointer move into it; `trigger: \"click\"` toggles it from the cell; on a cell with its own controls (link, copy, switch) it opens from a separate Details button beside the content. In the phone list, link columns render as chips under the row and each popover column gets a Details button that opens on tap. Use it for detail that does not fit a column, such as a merge reason or CI status. `key` and `href` must name model columns.\n- `onRowClick`: action chain with `$row` / `$rowIndex`, run when a row is clicked (or Enter on a focused cell). Pair it with `app.navigate` that sets a Drawer param, and bind `selectedId` to `{ \"$state\": \"/route/params/<param>\" }` so the open row stays highlighted. `rowId` names the id field (default `id`).\n- Phones (below 768px): the table renders as a card list. `mobileFields: { title, subtitle?, meta?: string or string[], status? }` picks the columns; by default the first text column is the title and the first `status`/`badge` column the chip. `mobile: \"scroll\"` keeps the grid; it is the default when the table has `rowActions` but no `onRowClick`. With `selectable`, each phone card gets a checkbox beside it and a Select all row sits above the list. An editable `checkbox` / `switch` column (one with `onChange`) becomes a real control beside the card, not a line of text.\n- `emptyState: { icon?, title, body? }` replaces the plain empty message. A search or filter that hides every row shows its own \"No rows match\" state.\n- `pagination`: boolean; defaults to auto-enabling past 200 rows (set `false` to force one scroll region). `density: \"compact\"` tightens row height for dense readouts.\n- `rowActions[]`: `{ label, variant?, icon?, placement?: \"inline\" or \"menu\", confirm?, actions }`. `placement: \"menu\"` moves the action into the row's More menu. Variants add `destructive-outline` to the Button variants. `destructive` and `destructive-outline` confirm by default; customize with `{ \"title\": ..., \"description\": ..., \"confirmLabel\": ... }`, or use a bare `confirm` string as the dialog description (use `confirm: false` only for a reversible action).\n- `search`: optional string; case-insensitive substring matching across the listed string and number columns. Bind a SearchInput value for client-side search.\n- `filters`: optional record of per-column string, number, boolean, null, or array values. An array means \"the cell is one of these\" (what a `multiple` Chips or Select writes). Null, empty strings, empty arrays, or absent values disable one filter. Bind Select or Chips values for client-side filters.\n\nKanban details:\n\n- One card per `data` row, grouped by the row's `columnField` value. `columns[]` are plain strings or `{ id, label? }`, in display order; rows matching no column are hidden.\n- `cardFields[]` uses the DetailList field shape (`{ key, label?, kind?, tones? }`, same kinds) for extra lines under the title.\n- `onMove` is an action chain run when a card is dropped in another column. `$row` is the moved row with `columnField` already set to the new column: `[{ \"action\": \"app.mutate\", \"params\": { \"model\": \"deal\", \"op\": \"update\", \"rowId\": { \"$row\": \"id\" }, \"values\": { \"stage\": { \"$row\": \"stage\" } } } }]`. Without `onMove`, cards cannot be dragged.\n- `onCardClick` is an action chain with `$row`; pair it with `app.navigate` and a `Drawer` to open a card.\n\nCalendar details:\n\n- `startField` / `endField` hold ISO dates, ISO datetimes, or epoch ms. An event shows on every day from start to end; without `endField` it shows on its start day.\n- Each Calendar keeps its own visible month (prev/next controls in its header). `onSelect` is an action chain with `$row`, run when an event is clicked.\n\nContributionGraph details:\n\n- Buckets `data` rows by the calendar day of `dateField` over the trailing `days`. Each row counts 1, or adds its numeric `countField` when set.\n\nTree details:\n\n- `nodes` is a doc-shaped value: `{ root: string | string[], elements: { <key>: { type, children?: string[] } } }`, the json-render flat element map. Usually bind it to a json column: `{ \"$state\": \"/queries/<name>/data/0/<column>\" }`. A malformed or absent value renders an empty state; a `children` key missing from `elements` shows as `key — ?`. Outlines are cut at 2,000 rows with a notice; branches deeper than 32 levels keep a disabled chevron.\n- Each row shows `key — type`. Clicking a row writes its key to `/ui/<id>/value`, and the row bound to that path renders selected; read the selection with `{ \"$state\": \"/ui/<id>/value\" }`. The Tree never writes `null`: when the selected key leaves the doc (a refetch, an edit) the stored key stays and no row renders selected. Selection and collapse are keyed by node key, so a key reachable through two parents selects and collapses in both places.\n- Rows scroll inside `maxHeight` (default `480px`). Set `fill: true` inside a `fill` Stack or Split pane to grow to that height instead and scroll within it (ignores `maxHeight`).\n\nFiles and File details:\n\n- Both read agent-fs as the viewer, with the viewer's own agent-fs key (the one Comb saves in their browser), from the swarm's default drive (`agent_fs.comb` in `/status`). There is no `drive` prop yet. The swarm key never reaches agent-fs, and the viewer sees only what their drive membership allows; an app cannot widen it.\n- A viewer who has not connected agent-fs sees a \"Connect agent-fs\" card that opens Comb's connect flow. In a `?mode=chromeless` iframe the card links to the app in the dashboard instead, because the iframe has no saved key.\n- `path` is absolute. A literal path must not contain `..`; bind it with `$state` to follow a route param. A folder that does not exist yet lists as empty (`emptyMessage`).\n- `Files` sorts folders first. `mode: \"browser\"` opens subfolders in place, with crumbs that never go above `path`, and reopens on the folder holding `selectedPath`. A file click (in list mode, any row) runs `onSelect` with `$row` = `{ path, name, type, size, modifiedAt }`; `type` is `file` or `directory`, and a folder's `path` ends with `/`. Usually: `[{ \"action\": \"app.navigate\", \"params\": { \"page\": \"docs\", \"params\": { \"file\": { \"$row\": \"path\" } } } }]`, plus `\"selectedPath\": { \"$state\": \"/route/params/file\" }`.\n- `File` renders Markdown with raw HTML shown as text, images as `<img>` (SVG too, so its scripts never run), PDFs in the browser's viewer, video and audio in a player, CSV as a table, and text files (HTML as source) as lines. Other types show Download and \"Open in agent-fs\". An empty `path` shows \"No file selected\".\n- List and view: a `Split` with `Files` in the left pane and `File` with `\"path\": { \"$state\": \"/route/params/file\" }` in the right; declare `file` in the page's `params`.\n- `upload: true` adds an Upload button and a drop zone over the list. Files upload with the viewer's key into the folder on screen (the opened subfolder in browser mode), create-only: a taken name asks Keep both or Skip. The list refreshes when a file lands. agent-fs's own upload limit applies.\n- Scripts: an `app.action` script runs as its owner agent, so `ctx.fs` `/afs` reads that agent's default drive, not the viewer's. It sees the same files only when the agent's default drive is the swarm's comb drive.\n\nDateRange and Timeline details:\n\n- `DateRange` writes inclusive `YYYY-MM-DD` dates (the viewer's local calendar) to `/ui/<id>/from` and `/ui/<id>/to`, and the active preset to `/ui/<id>/preset`. On first load it writes `defaultPreset` unless the state already holds a range. Bind query params with `{ \"$state\": \"/ui/<id>/from\" }` so the query refetches when the range changes. `7d` is today and the six days before it; `mtd` starts on the 1st. `custom` opens two date inputs in a popover; Apply needs both dates, from not after to. `id` must match `[A-Za-z0-9_-]+`, and `defaultPreset` must be one of `presets`.\n- `Timeline` reads `timeField` as an ISO date or epoch ms (rows that do not parse are left out), sorts newest first and groups under day headings: Today, Yesterday, then the date. Each event shows `titleField`, the time, `descriptionField` (two lines at most) and a `statusField` pill (`tones` maps value to tone; lifecycle values get the status chip). `icon` replaces the marker dot. `onSelect` runs with `$row` (the row) and `$rowIndex` (its index in `data`); without it events are not clickable.\n\nSchemaForm details:\n\n- `schema` is a JSON schema object held in state (usually `{ \"$state\": ... }`). Each entry of `properties` becomes one control: `type: \"boolean\"` a switch, `enum` of strings a select, `type: \"number\"` or `\"integer\"` a number input, anything else a text input. `description` is the tooltip. Fields seed from `value[key]`, else the property `default`. At most 100 fields and 200 enum options render. `id` must match `[A-Za-z0-9_-]+`. Rebinding `schema` resets the form.\n- Typing updates `/ui/<id>/value` with the draft object; switches and selects commit at once and text and number inputs commit on blur. Each commit runs `onChange` with `$form` = the draft.\n- Nested document editing: bind `baseDoc` to a doc-shaped value (`{ root, elements }`) and `nodeKey` to an element key, such as a Tree's `{ \"$state\": \"/ui/<tree>/value\" }`. The form then edits `baseDoc.elements[nodeKey].props`, and `/ui/<id>/value` holds the whole doc with the edit merged in, so one `app.mutate` with `values: { <jsonColumn>: { \"$state\": \"/ui/<id>/value\" } }` persists it. Props the schema does not list are kept. Edits the query has not returned yet stay applied, so two quick edits on different nodes both survive. A `nodeKey` that is not a key of `elements` falls back to plain mode, and a `baseDoc` over 5,000 elements is not editable. Typing writes `/ui/<id>/value` on every keystroke, before the commit on blur, so another component's `app.mutate` that reads that path can persist half-typed text; persist from the SchemaForm's own `onChange`.\n\nApproval details (human-in-the-loop):\n\n- `requestId` names one approval request, usually the id an `app.action` script returned: `{ \"$state\": \"/actions/<name>/result/requestId\" }`. An empty value renders nothing, so the element can sit on the page before the request exists.\n- While the request is pending, the card shows its questions with the dashboard's answer flow and polls every 5s; polling stops once it resolves. The viewer answers with their own credential, so the server records them and enforces the approvers list and RBAC.\n- A viewer whose role cannot answer, or whose answer the server refuses (not an approver), sees a read-only card with an \"Open in dashboard\" link. If the request was answered or expired meanwhile, the card refetches and shows that state instead of an error. With an `all` or `{ min: N }` policy, an answer that does not resolve it shows \"Your answer is recorded\".\n- `showResolved: false` shows only the outcome line after resolution, not the answers. `compact: true` drops the card chrome.\n- `onResolved` is an action chain run once, when the page sees the request leave `pending`. Its params may read `{ \"$chain\": \"status\" }` (`approved`, `rejected`, `timeout`, `cancelled`), `{ \"$chain\": \"responses\" }` (answers keyed by question id; `{ \"$chain\": \"responses/<questionId>\" }` reads one), and `{ \"$chain\": \"resolvedBy\" }`. A request that was already resolved when the page loaded does not run it, so a reload never repeats the follow-up. Use `onResolved`, not `on.resolved`: the validator rejects the latter.\n\nIn-session wait: the follow-up runs in the viewer's browser, so if they close the tab before the answer, nothing continues. The script behind the action creates the request detached and returns its id:\n\n```ts\nexport default async function run(args, ctx) {\n const res: any = await ctx.swarm.request_humanInput({\n title: `Deploy ${args.service}?`,\n questions: [{ id: \"go\", type: \"approval\", label: \"Ship it to production?\" }],\n detached: true,\n });\n return { requestId: res?.data?.requestId ?? res?.requestId };\n}\n```\n\n```json\n{\n \"askBtn\": { \"type\": \"Button\", \"props\": { \"label\": \"Request deploy\", \"busyWith\": \"requestDeploy\" },\n \"on\": { \"press\": { \"action\": \"app.action\", \"params\": { \"name\": \"requestDeploy\", \"input\": { \"service\": \"api\" } } } } },\n \"approve\": {\n \"type\": \"Approval\",\n \"props\": {\n \"requestId\": { \"$state\": \"/actions/requestDeploy/result/requestId\" },\n \"onResolved\": [\n { \"action\": \"app.action\", \"params\": { \"name\": \"applyDecision\",\n \"input\": { \"status\": { \"$chain\": \"status\" }, \"responses\": { \"$chain\": \"responses\" } } } },\n { \"action\": \"ui.toast\", \"params\": { \"message\": \"Decision applied\", \"tone\": \"success\" } }\n ]\n }\n }\n}\n```\n\nDurable wait: when the follow-up must run even if nobody watches the page, put it in a workflow whose human-in-the-loop node waits server-side, and use `Approval` only to answer. A script action starts the run with `ctx.swarm.workflow_trigger({ id, triggerData, wait: false })` and returns `runId`. The request appears once the run reaches its human-in-the-loop node, so a second script action (pressed from the page, or retried) finds it and returns its id: `ctx.swarm.db_query({ sql: \"SELECT id FROM approval_requests WHERE workflowRunId = ? AND status = 'pending' ORDER BY createdAt DESC LIMIT 1\", params: [args.runId] })`, then `{ requestId: res.data.rows[0]?.[0] }`. Bind `Approval.requestId` to that action's result. The workflow resumes on the answer whether or not the page is open.\n\nSessionThread details — a chat on an app page, one session per viewer and `sessionKey`:\n\n- `sessionKey` names the session, a plain token (`^[A-Za-z0-9_-]{1,128}$`): a literal such as `\"main\"`, or a `$state` binding to a token such as a route param or row id (`{ \"$state\": \"/route/params/itemId\" }`) for one session per item. No row stores the session: the server keys every task the thread's `app.action` creates as `task:app:<appId>:<sessionKey>:user:<viewer>`, and the thread shows the viewer's newest session with that key. A page can only write sessions of its own app.\n- `scope` is `\"user\"` (the default): each viewer has their own session per key. The viewer needs an identity; with none picked the composer is disabled. `scope: \"shared\"` (one session everyone on the page writes to) comes in a follow-up PR: the validator rejects it today. The planned design adds an everyone:write session share on the root when the server creates it.\n- It renders the same conversation as the dashboard's \"Session about this page\" panel: the session turn timeline (each person message with the sender's name, the swarm's replies with a live Queued / Working status, worker steps, approvals) and the shared composer. A person bubble shows the `message` of an app-action input instead of the whole agent prompt, cut at 4,000 characters. The composer's attachments and mic are off: a message is text only.\n- Sending a message takes one of three routes:\n 1. No session yet → run `onDispatch` with `$form = { message }` and `$chain = { leafTaskId: null, newTaskId: null }`. Its `app.action` creates the session's root task.\n 2. A task in the session is not finished → the composer steers the newest such task, on any agent, with `source: \"app-page\"`. It offers Queue, and Interrupt where the harness supports it. The server promotes a steer it cannot deliver into a follow-up task (source `ui`), and a toast says so.\n 3. Every task is finished (completed, failed, cancelled, superseded, skipped, or draft) → run `onDispatch` again with `$chain.leafTaskId` set to the newest task id, so `\"parentTaskId\": { \"$chain\": \"leafTaskId\" }` chains the new task under it. The follow-up keeps the session's key.\n- Each `app.action` step of `onDispatch` is sent with the session (`{ key, scope }`) and with `followUp: false` unless the step sets `followUp` itself, so the Lead adds no review task to the chain and each message stays one task. A Lead review that is in the chain anyway (a steer the server promoted to a task) is never steered or chained under.\n- \"New session\" (shown once a session exists) starts over: the next message creates a new root, and the thread shows only sessions created after the current one. Nothing is deleted; older sessions stay in the dashboard's Sessions list.\n- While the session loads, the composer is disabled with a loading notice. A session whose chain cannot be found blocks sending. After a send, the composer stays busy until the new task shows up, for at most 30 seconds.\n- Without `fill` the thread is 420 px tall; `fill: true` fills a `fill`-aware parent. Inside an element instance, `id` is namespaced per instance, so two instances keep separate drafts.\n\n```json\n{ \"type\": \"SessionThread\", \"props\": {\n \"id\": \"chat\",\n \"sessionKey\": { \"$state\": \"/route/params/screenId\" },\n \"onDispatch\": [{ \"action\": \"app.action\", \"params\": {\n \"name\": \"editScreen\", \"input\": { \"$form\": \"\" }, \"parentTaskId\": { \"$chain\": \"leafTaskId\" } } }]\n} }\n```\n\nForm details:\n\n- `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, `enum`, or `file`, and enum fields need `options`.\n- `kind: \"file\"` adds `dir`, `accept` (e.g. `[\".pdf\", \"image/*\"]`), `multiple` and `source`: `\"upload\"` (default) chooses local files, `\"pick\"` opens a browser of `dir` (or `/`) to attach a file that already exists in agent-fs, `\"both\"` offers both. `dir` is an absolute agent-fs folder, required unless `source` is `\"pick\"`. Files use the viewer's own agent-fs key on the swarm's default drive, like `Files`.\n- On submit, chosen files upload first, create-only, to `<dir>/<timestamp>-<id>-<n>-<sanitized name>`: a random id per submit and a counter across all fields, so two fields or two submits never write the same path; then the chain runs. `$form.<name>` is the stored path, or an array of paths with `multiple: true`. An upload failure (the error shows agent-fs's text, e.g. its size limit) stops the chain and keeps the form's values. Without an agent-fs connection the field shows a \"Connect agent-fs\" card, and a required file field disables submit.\n- Values live at `/forms/<formId>/<fieldName>`. `onSubmit` is an action chain.\n- The submit button shows a pending spinner while the chain runs, and `app.mutate` failures in the chain render inline under the fields (not the page banner) — no extra wiring needed.\n\nDrawer details:\n\n- `param` must name a param declared on the containing page. The drawer is open exactly when `/route/params/<param>` has a non-empty value, so its open state survives refresh and is shareable. Its children mount only while open; closing it clears that param with history replacement.\n- `actions[]`: `{ label, variant?, icon?, confirm?, actions }`, rendered as buttons in a sticky footer under the scrolling body. Confirmation follows Table `rowActions`: destructive variants confirm by default, and a chain with an `app.mutate` delete always confirms. Chains have no `$row`; address the open record with `{ \"$state\": \"/route/params/<param>\" }`, for example `{ \"action\": \"app.mutate\", \"params\": { \"model\": \"order\", \"op\": \"delete\", \"rowId\": { \"$state\": \"/route/params/panel\" } } }`. Prev/next record navigation is not available.\n- `presentation: \"split\"` renders the Drawer as an inline right pane beside the page instead of a sheet over it. The page canvas shrinks while it is open; the pane has a draggable left edge (arrow keys, Shift for big steps, Home/End for the min/max, double-click or Enter to reset) and the viewer's width is kept per app in the browser. `size` sets its starting width (360/480/640/800px). Opening, closing, refresh and shared links work exactly as for the sheet. Below 768px it falls back to the sheet. At most one split Drawer per page; `side` does not apply.\n\nList + detail recipe (a row click opens the record beside the table):\n\n```json\n\"params\": { \"issue\": { \"kind\": \"string\" } },\n\"elements\": {\n \"root\": { \"type\": \"Stack\", \"props\": {}, \"children\": [\"table\", \"issue\"] },\n \"table\": { \"type\": \"Table\", \"props\": {\n \"data\": { \"$state\": \"/queries/issues/data\" },\n \"columns\": [{ \"key\": \"title\" }, { \"key\": \"status\", \"kind\": \"status\" }],\n \"selectedId\": { \"$state\": \"/route/params/issue\" },\n \"onRowClick\": [{ \"action\": \"app.navigate\", \"params\": { \"page\": \"main\", \"params\": { \"issue\": { \"$row\": \"id\" } } } }] } },\n \"issue\": { \"type\": \"Drawer\", \"props\": { \"param\": \"issue\", \"presentation\": \"split\", \"size\": \"md\", \"title\": \"Issue\" },\n \"children\": [\"issueDetail\"] },\n \"issueDetail\": { \"type\": \"DetailList\", \"props\": { \"data\": { \"$state\": \"/queries/issue/data/0\" }, \"fields\": [{ \"key\": \"title\" }] } }\n}\n```\n\nDetailList details:\n\n- `fields[]`: `{ key, label?, kind?, tones? }`. Kinds reuse Table formatting (`text`, `string`, `number`, `boolean`, `date`, `badge`, `enum`) and the Table cell renderers (`status`: lifecycle chip or `tones` pill; `user`: avatar plus name; `relative`: smart time, exact on hover; `copy`: value plus copy button; `link`: a smart link from the value, or from the row field named by `href`, with `linkLabel` as an optional label template), and add `code` for a monospace block and `json` for a collapsible JSON tree (objects, or a string holding JSON). `currency` and `percent` (with `currency?: \"<ISO 4217>\"`) format numbers like the Table kinds. Bind `data` to one record, commonly `/queries/<detailQuery>/data/0`.\n\nMotion details:\n\n- Every `Stack` fades its direct children in and lifts them 4px over 200ms on first paint, staggered 30ms (capped at the 10th child). It never replays on the 5s data poll. A Stack nested inside another one does not add its own entrance. `motion: \"fade\"` drops the lift; `motion: \"none\"` turns it off. Viewers with reduced motion get a 150ms fade.\n\nCardGrid details — the visual counterpart to Table for record browsers (projects, documents, media):\n\n- `titleKey` (required) picks the row field shown as the card title (an object value shows a JSON preview; titles are capped at 500 characters).\n- `imageKey` (optional) picks a row field holding an absolute http(s) image URL and adds an image tile to every card. When it is set, a non-URL value, a missing value, or a failed load shows a placeholder tile. Omit it for text-only cards with no tile.\n- `fields[]`: `{ key, kind?, tones?, href?, linkLabel? }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge` (with `tones`), `link` (a smart link, with `href` / `linkLabel`), or `json` (no `label`, no `format`). A field with no `kind` whose value is an object renders like `json`. They render as an unlabeled `·`-joined meta line under the title, e.g. a `date` field for \"created\" and a `text` field for the author.\n- `columns`: same responsive shorthand as `Grid.columns` (default `{ \"base\": 1, \"sm\": 2, \"md\": 3 }`).\n- `onClick`: an action chain with `$row` / `$rowIndex`, run when a card is clicked or activated with Enter or Space. Commonly `app.navigate` into a detail page, the CardGrid equivalent of Table's `onRowClick`.\n- Bind `data` / `loading` / `error` to a named query like Table. Loading shows skeleton cards, an error shows a callout, and no rows shows `emptyMessage`.\n- It renders 200 cards at a time with a Show more button below the grid that reveals the next 200.\n\nShortcut details:\n\n- `Button.shortcut` and `SearchInput.shortcut` are one key. Letters and digits match without Shift; symbols such as `/` and `?` match as typed. They do nothing while focus is in a text field, while Ctrl, Cmd, or Alt is held, or while a dialog or menu is open (unless the control is inside it, such as a Button in an open Drawer).\n\n## Layout & interactivity\n\nFor a multi-page app that should feel like a product (a sidebar of pages, a sticky title bar with actions), set `layout: \"sidebar\"` (see Pages, routes, and page trees) instead of building navigation out of Tabs or button rows. Pair `Metric` tiles (with `sparkline`) in a `Grid` with `Chart`s inside `Card`s for dashboards.\n\nUse `Stack` as the primary page and section layout; `Container` is the legacy two-prop primitive retained for existing pages. Stack supports vertical or horizontal flow, shared spacing, alignment, justification, wrapping, and padding; row Stacks (filter bars, button rows) should set `collapseBelow: \"sm\"|\"md\"|\"lg\"` so they stack vertically on phones. Use `Grid` for responsive card or metric strips: a bare column count is responsive shorthand (1 column on phones, 2 from `sm`, the count from `md` up), or pin breakpoints explicitly with `{ \"base\": 1, \"md\": 2, \"lg\": 3 }`. `Grid` and `Split` also accept `padding` on the shared spacing scale.\n\n`Stack` and `Split` size to their content by default, so a page scrolls as a whole. Set `fill: true` to make one grow to fill the remaining height of a `fill`-aware parent (another `fill` Stack or Split) instead; chain it from the page root down through every container on the path to the element that should scroll, and that element scrolls within whatever height is left while the page itself does not. A non-`fill` sibling (a toolbar, a header) keeps its natural height and the `fill` sibling absorbs the rest. A `fill` Split stretches both panes to the full row height, so nesting a `fill` Split inside one pane of another `fill` Split is the way to build a three-or-more column viewport-height layout (`ratio` is only ever two panes).\n\n`Split` and `Tabs` children are positional. For Split, `children[0]` is the first pane, `children[1]` is the second, and extra children append inside the second pane. Below `collapseBelow`, panes stack; `reverse` changes only that narrow-layout stacking order. For Tabs, `children[i]` is the body for `tabs[i]`; keep both arrays in the same order and with the same count. Inactive tab children stay mounted but hidden, so Tables keep polling. Use `Divider` to separate sections and `Markdown` for richer explanatory content.\n\nSearchInput, Select, NumberInput, Chips, and Tree are client-side controls: each needs a literal `id` and writes state under `/ui/<id>/value` (Tree writes the clicked node key; a `selectable` Table writes its selected row ids to `/ui/<id>/selected`); Tabs writes its active key to `/ui/<id>/tab`. Bind those values into a Table's `search` and `filters` props. This filters already-polled rows locally; it does not alter or re-run the named query.\n\n```json\n{\n \"filters\": { \"type\": \"Stack\", \"props\": { \"gap\": \"sm\" }, \"children\": [\"query\", \"status\"] },\n \"query\": { \"type\": \"SearchInput\", \"props\": { \"id\": \"ideaSearch\", \"placeholder\": \"Search ideas\" } },\n \"status\": { \"type\": \"Select\", \"props\": { \"id\": \"ideaStatus\", \"options\": [\"open\", \"done\"] } },\n \"ideas\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIdeas/data\" },\n \"columns\": [{ \"key\": \"title\" }, { \"key\": \"status\" }],\n \"search\": { \"$state\": \"/ui/ideaSearch/value\" },\n \"filters\": { \"status\": { \"$state\": \"/ui/ideaStatus/value\" } }\n }\n }\n}\n```\n\n`visible` accepts a boolean, a `$state` truthiness binding, comparisons, and logical groups. Put exactly one comparison key in each condition object. The renderer evaluates the first matching key in fixed priority order (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`; otherwise truthiness), so additional comparison keys in the same object are ignored. Use `$and` / `$or` arrays to combine conditions. `not` is a negation FLAG inside a condition object (`\"not\": true`), never a wrapper around one — `{ \"not\": { \"$state\": … } }` is invalid and the validator rejects it. The absent-record pattern (e.g. an alert when a detail query matched nothing) is `{ \"$state\": \"/queries/<q>/data/0/id\", \"not\": true }`:\n\n```json\n[\n { \"$state\": \"/route/params/issueId\", \"gt\": 0 },\n {\n \"$and\": [\n { \"$state\": \"/route/page\", \"eq\": \"detail\" },\n { \"$state\": \"/route/params/panel\", \"neq\": \"hidden\" }\n ]\n }\n]\n```\n\n## Bindings, sentinels, and action chains\n\nUse this exact query binding shape; do not invent `$query`, `$item`, or template strings:\n\n```json\n{\n \"data\": { \"$state\": \"/queries/allIdeas/data\" },\n \"loading\": { \"$state\": \"/queries/allIdeas/loading\" },\n \"error\": { \"$state\": \"/queries/allIdeas/error\" }\n}\n```\n\nValid `$state` roots are:\n\n- `/queries/<declaredQuery>/...`\n- `/forms/<formId>/...`, where a `Form` element has that literal `props.id`\n- `/ui/<id>/...`, where a SearchInput, Select, Chips, or Tabs element has that literal `props.id` (SearchInput, Select, and Chips use `/value`; Tabs uses `/tab`)\n- `/actions/<declaredAction>/...`\n- `/route/page` for the active page name\n- `/route/params/<declaredParam>` for a param declared on the current page\n\n`/route` is mirrored as `{ page, params }`. Only declared params appear. Values are coerced by their declared kind: `number` becomes a number when possible; boolean strings `true`/`1` become true; failed number coercion remains the raw string.\n\nOnly inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `Table.bulkActions[].actions`, `Form.onSubmit`, or a component chain prop such as `Approval.onResolved` or `SessionThread.onDispatch`) these scoped sentinels are valid, recursively inside objects and arrays:\n\n| Sentinel | Resolves to |\n|---|---|\n| `{ \"$row\": \"id\" }` | Current Table row's `id`; another column name selects that field. |\n| `{ \"$row\": \"\" }` | Entire current Table row. |\n| `{ \"$rowIndex\": true }` | Current Table row index. |\n| `{ \"$form\": \"title\" }` | One current Form value. |\n| `{ \"$form\": \"\" }` | All current Form values. |\n| `{ \"$state\": \"/queries/allIdeas/data\" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |\n| `{ \"$chain\": \"leafTaskId\" }` | One chain-scope value, published by the component that runs the chain: a task chain (`SessionThread`) carries `leafTaskId` and `newTaskId`; `Approval.onResolved` carries `status`, `responses` and `resolvedBy`. The component publishes every key, `null` when it has no value yet; a `null` key resolves to nothing and its param is dropped (a `parentTaskId` bound to a `null` `leafTaskId` creates a root task). Where no chain scope is published (Table, Form), or the key is not one the scope carries (a typo), the sentinel is left in place and the action fails instead of silently dropping the parent. An empty string is not \"no parent\": a `$state` slot meaning \"no parent yet\" must hold `null`. |\n| `{ \"$chain\": \"\" }` | The whole chain scope. |\n\nEach sentinel object must contain exactly the single key shown.\n\nAn action-chain step is `{ \"action\": \"<type>\", \"params\": {...} }`. Available action types:\n\n- `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `\"create\"`, `\"update\"`, or `\"delete\"`. `update`/`delete` require `rowId` (usually `{ \"$row\": \"id\" }`, or `{ \"$state\": \"/route/params/<param>\" }` in a Drawer footer); literal `values` keys must be model columns. Successful mutation refetches all queries on that model.\n- `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.\n- `app.action`: `{ name, input?, parentTaskId?, followUp? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { \"$row\": \"\" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ \"$chain\": \"leafTaskId\" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400. `followUp: false` creates the task with no Lead follow-up (the review task the Lead adds when a worker task finishes); script and sync actions ignore it. A task an action creates is attributed to the viewer's identity. `session: { key, scope }` (SessionThread sets it) keys a task-kind action's task into the viewer's session; the server builds the key, never the page.\n- `app.navigate`: `{ page, params? }`; `page` must be declared, supplied keys must be params of the target page, and every required target param must be supplied. `params` replace the current route params wholesale and may contain action sentinels. Navigation pushes history, so browser Back returns to the previous page/params; only `mode` is preserved automatically.\n- `ui.toast`: `{ message, description?, tone?, undo? }`, where `tone` is `\"success\"`, `\"error\"`, `\"info\"` (default), or `\"warning\"`. `undo: { label?, actions }` adds an Undo button (default label `Undo`) that runs `actions` as a chain; its steps are validated like any chain. Put it after the step it confirms, e.g. a row delete followed by `{ \"action\": \"ui.toast\", \"params\": { \"message\": \"Order deleted\", \"undo\": { \"actions\": [{ \"action\": \"app.mutate\", \"params\": { \"model\": \"order\", \"op\": \"create\", \"values\": { \"title\": { \"$row\": \"title\" } } } }] } } }`. Undo params resolve `$state` when Undo is pressed; `$row` / `$form` resolve when the toast is shown.\n- `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.\n- `swarm.call`: `{ method, endpoint: \"/api/...\", body? }`, where `method` is `\"GET\"`, `\"POST\"`, `\"PUT\"`, `\"DELETE\"`, or `\"PATCH\"`; raw authenticated API call.\n\nA failed step halts its chain: when `app.action`, `app.mutate`, `swarm.sdk` or `swarm.call` fails (a thrown error, a script action that returns `ok: false`, a non-2xx `swarm.call`), the steps after it do not run and the error shows as an error toast. A step's `onError` (`{ set }` or `{ action }`) runs first, and the chain still halts. So a `ui.toast` after a write is a real success message. A `Form`'s failed `app.mutate` shows inline under the fields instead of a toast. A task-backed `app.action` succeeds once the task is created; the task's own failure shows in the page banner and does not halt the chain. A Table bulk action reads each step's own outcome, as before.\n\n## Patch semantics\n\n`app-patch.definition` is RFC 7396 JSON Merge Patch applied to the stored definition:\n\n- omitted keys stay unchanged;\n- object keys merge recursively;\n- arrays and scalar values replace;\n- `null` deletes a key;\n- reusable-element disambiguation: a patch value for `elements.<name>` containing ONLY the `elements` key merges node-by-node; any other key present (`mode`, `root`, `props`, or `export`) makes it a full element replace — restate every field you want kept. In that node-by-node form, `elements.<name>.elements.<id>: null` deletes one node. Literal null nodes are rejected in a full element replace so they cannot be mistaken for deletions.\n- otherwise every supplied `pages.<page>.elements.<id>`, `pages.<page>.params.<param>`, `actions.<name>`, `models.<name>.columns.<col>`, and `models.<name>.sources.<src>` value is atomic and replaces that complete declaration; `null` deletes it (deleting a source detaches its rows — see the source lifecycle above).\n\n`pages.<page>: null` deletes a page, except the current `defaultPage` cannot be deleted. `root`, `title`, and top-level `defaultPage` use ordinary merge semantics. A top-level `page` patch is rejected with guidance to patch `pages.<name>` instead.\n\nBecause elements, param declarations, actions, and columns are atomic, include the complete desired object when changing one. For example, changing only a Table's `emptyMessage` requires sending its full `{ \"type\": \"Table\", \"props\": ... }` element. The merged result is validated as a whole; on failure, read `issues[]`, correct the paths, and retry without assuming anything was written.\n\n```json\n{\n \"appId\": \"<app-id>\",\n \"description\": null,\n \"definition\": {\n \"models\": {\n \"idea\": {\n \"columns\": {\n \"priority\": { \"kind\": \"enum\", \"enum\": [\"low\", \"high\"], \"default\": \"low\" }\n }\n }\n },\n \"queries\": { \"openIdeas\": null },\n \"pages\": {\n \"main\": {\n \"elements\": {\n \"title\": { \"type\": \"Heading\", \"props\": { \"text\": \"Prioritized ideas\", \"level\": \"h1\" } }\n }\n }\n }\n }\n}\n```\n\n## Worked example: ideas tracker\n\nCreate this with `app-upsert`:\n\n```json\n{\n \"name\": \"Ideas Tracker\",\n \"description\": \"Collect and manage product ideas\",\n \"definition\": {\n \"models\": {\n \"idea\": {\n \"columns\": {\n \"title\": { \"kind\": \"string\", \"required\": true },\n \"status\": { \"kind\": \"enum\", \"enum\": [\"open\", \"done\"], \"default\": \"open\" }\n }\n }\n },\n \"queries\": {\n \"allIdeas\": { \"model\": \"idea\", \"sort\": { \"column\": \"createdAt\", \"dir\": \"desc\" } }\n },\n \"actions\": {\n \"triage\": { \"kind\": \"task\", \"prompt\": \"Review current ideas and recommend the next one to pursue\" }\n },\n \"pages\": {\n \"main\": {\n \"root\": \"root\",\n \"elements\": {\n \"root\": {\n \"type\": \"Container\",\n \"props\": { \"direction\": \"column\", \"gap\": \"lg\" },\n \"children\": [\"heading\", \"formCard\", \"ideasCard\", \"triage\"]\n },\n \"heading\": { \"type\": \"Heading\", \"props\": { \"text\": \"Ideas\", \"level\": \"h1\" } },\n \"formCard\": {\n \"type\": \"Card\",\n \"props\": { \"title\": \"Add an idea\" },\n \"children\": [\"ideaForm\"]\n },\n \"ideaForm\": {\n \"type\": \"Form\",\n \"props\": {\n \"id\": \"newIdea\",\n \"fields\": [{ \"name\": \"title\", \"label\": \"Title\", \"required\": true }],\n \"submitLabel\": \"Add\",\n \"onSubmit\": [{\n \"action\": \"app.mutate\",\n \"params\": { \"model\": \"idea\", \"op\": \"create\", \"values\": { \"$form\": \"\" } }\n }]\n }\n },\n \"ideasCard\": {\n \"type\": \"Card\",\n \"props\": { \"title\": \"All ideas\" },\n \"children\": [\"ideasTable\"]\n },\n \"ideasTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIdeas/data\" },\n \"loading\": { \"$state\": \"/queries/allIdeas/loading\" },\n \"error\": { \"$state\": \"/queries/allIdeas/error\" },\n \"columns\": [\n { \"key\": \"title\", \"label\": \"Title\" },\n { \"key\": \"status\", \"label\": \"Status\", \"kind\": \"badge\", \"tones\": { \"open\": \"info\", \"done\": \"success\" } }\n ],\n \"rowActions\": [{\n \"label\": \"Delete\",\n \"variant\": \"destructive-outline\",\n \"actions\": [{ \"action\": \"app.mutate\", \"params\": { \"model\": \"idea\", \"op\": \"delete\", \"rowId\": { \"$row\": \"id\" } } }]\n }]\n }\n },\n \"triage\": {\n \"type\": \"Button\",\n \"props\": { \"label\": \"Ask swarm to triage\", \"variant\": \"secondary\" },\n \"on\": { \"press\": [{ \"action\": \"app.action\", \"params\": { \"name\": \"triage\" } }] }\n }\n }\n }\n },\n \"defaultPage\": \"main\"\n }\n}\n```\n\nThe tool returns `{ appId, url: \"/apps/<id>\" }`. Open that URL to verify the live UI, then continue with the read-patch-validate loop above.\n\n## View and screenshot a live app\n\n- An app renders at `<dashboard>/apps/<id>`. Two view modes are set by query string: `?mode=full` (full-viewport overlay with a slim header) and `?mode=chromeless` (only the rendered page, the embed surface). `app.navigate` keeps only `?mode`.\n- Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the \"Who are you?\" dialog.\n- Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.\n- App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.\n- Follow-up edit to a live app: list in the brief the control numbers the edit must not move, and assert them from the backing script before publishing. Take a signed-in screenshot of each changed selector at 1440px wide, save the shots to agent-fs, critique, and repeat at least 3 times. If the backing script caches results, bump its version or force a fresh run so the shots show new data.\n\n\n### Rows from agents and scripts\n\nEvery row tool requires `appId` and `model`. Scripts use underscore names, such as `ctx.swarm.app_row_create` and `ctx.swarm.app_rows_list`.\nResults use the usual `data` wrapper, so scripts read `res?.data ?? res`. Rows contain system fields and declared columns at the top level.\nWrites record `agent:<agentId>` in `createdBy` and `updatedBy`. Source projections and join keys remain read-only. Each row input must fit within 1 MiB.\n\n`app-rows-list` accepts `equals`, `sort: \"<column>:asc|desc\"`, and `limit` from 1 to 1000 (default 200).\nEquality filters accept declared columns and system columns. Filter values must match the column kind and use strict equality.\n`app-rows-delete` requires at least one equality filter and accepts a limit from 1 to 1000 (default 1000).\n\n`app-action-run` returns the REST action body under `data`. Script actions run with the script owner's identity and receive the verified invoking agent as `caller`.\nScripts and extensions cannot invoke `app-action-run`.\n";
15119
+ var content_default2 = "# Swarm Apps\n\nSwarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot.\n\n> **Capability gate**: app tools are available when the server's `CAPABILITIES` includes `pages` (for example `CAPABILITIES=core,task-pool,pages`). There is no separate `apps` capability. If these tools are absent from your MCP list, this is why.\n\n## Tools and iteration loop\n\n| Tool | Use it for |\n|---|---|\n| `app-list` | Discover apps by id, name, description, and timestamps. Definitions are omitted. |\n| `app-get` | Read one complete stored definition before changing it. |\n| `app-upsert` | Create an app, or replace an existing app's entire definition when you intentionally have the full desired state. |\n| `app-patch` | Make a focused change while preserving everything not mentioned in the patch. Prefer this for iteration. |\n| `app-query` | Run one declared named query and return its rows. Use this when an agent or saved script needs to consume app data rather than render the app UI. |\n| `app-rows-list` | List rows with typed equality filters, sorting, and a limit. Returns `{ rows, total }`. |\n| `app-row-get` | Read a row by `rowId`. Returns `{ row }`. |\n| `app-row-create` | Create a row from `values`. Returns `{ row }`. |\n| `app-rows-create` | Create 1 to 500 rows from a `rows: values[]` array, within 10 MiB. Returns `{ rows }`. |\n| `app-row-patch` | Patch a row by `rowId` with `values`. Returns `{ row }`. |\n| `app-row-delete` | Delete a row by `rowId`. Returns `{ ok: true }`. |\n| `app-rows-delete` | Delete matching rows with a non-empty `equals` filter. Returns `{ deleted }`. |\n| `app-action-run` | Run a declared script, task, or sync action with `{ appId, action, input? }`. Agents can invoke it through MCP only. |\n| `app-history` | List definition snapshots and their compact model/column digests before choosing a restore point. |\n| `app-diff` | Show a unified definition diff; defaults to newest snapshot → CURRENT. |\n| `app-rollback` | Restore a snapshot through the normal schema-migration engine. |\n\nFor every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch` -> if rejected, fix every returned `issues[]` entry (`path` + `message`) and retry. Validation happens before storage, so a rejected update leaves the saved app unchanged. Do not guess at the current definition or use `app-upsert` with a partial definition.\n\n`app-patch` can also change `name`; omit `description` to preserve it or pass `description: null` to clear it.\n\n### Reading an app's callable surface\n\nOne `app-get` returns everything needed to drive an app you did not write: `definition.queries` are runnable with `app-query` (supply every `$param` the query references), and `definition.actions` are invocable with `app-action-run` or `POST /api/apps/<id>/actions/<name>` (a `script` action runs its script, a `task` action spawns a task, a `sync` action refreshes sources). Read the query parameters and action arguments from the definition before invocation. Do not guess parameter names.\n\n### Verified action caller\n\nScript actions receive `caller` as a reserved, server-stamped argument. The server overwrites `caller` from definition defaults and request input.\n\n```typescript\ntype AppActionCaller = {\n kind: \"user\" | \"agent\" | \"operator\" | \"guest\";\n id: string | null;\n name?: string;\n pageId?: string;\n};\n```\n\nThe caller identifies the authenticated user or agent. Operator and guest callers have `id: null`. A signed page session adds `pageId`.\nWith the swarm key, a registered `X-Agent-ID` produces an agent caller and `agent:<id>` row provenance. Missing or unknown agent IDs remain operator callers.\nTask actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.\n\n### Verified action caller\n\nScript actions receive `caller` as a reserved, server-stamped argument. The server overwrites `caller` from definition defaults and request input.\n\n```typescript\ntype AppActionCaller = {\n kind: \"user\" | \"agent\" | \"operator\" | \"guest\";\n id: string | null;\n name?: string;\n pageId?: string;\n};\n```\n\nThe caller identifies the authenticated user or agent. Operator and guest callers have `id: null`. A signed page session adds `pageId`.\nWith the swarm key, a registered `X-Agent-ID` produces an agent caller and `agent:<id>` row provenance. Missing or unknown agent IDs remain operator callers.\nTask actions include the same caller as server-verified JSON in the task prompt. Script execution still uses the saved script owner's bindings.\n\n## Safe schema evolution and rollback\n\nPrefer **hiding** a column over deleting it. A hidden column's values stay on every existing row, so an unhide or rollback can make it visible again. Hiding is metadata-only: hidden columns cannot be used in queries, page bindings, `app.mutate` values, or new row writes, and `required` is ignored while hidden. Row GETs still expose the historical value for backward compatibility.\n\nDo not reuse a hidden column name. The name remains held until you either unhide it or explicitly purge its stored values. To permanently remove a column, delete its declaration with `null` and include `{ \"columnName\": { \"purge\": true } }` in the same `migration` object. That is deliberately one-shot and irreversible for row data.\n\nSchema-changing writes can carry this sibling `migration` object:\n\n```json\n{\n \"migration\": {\n \"priority\": { \"from\": \"flag\", \"map\": { \"urgent\": \"high\", \"watch\": \"low\" }, \"else\": \"none\" },\n \"status\": { \"from\": \"flag\", \"map\": { \"watch\": \"watching\", \"done\": \"done\" }, \"else\": \"open\" },\n \"oldColumn\": { \"purge\": true },\n \"count\": { \"coerce\": true, \"else\": 0 },\n \"owner\": { \"set\": \"unassigned\" }\n }\n}\n```\n\nUse `set` to backfill a changed column, `from` with optional `map`/`else` to derive it from one existing (including hidden) column, `coerce` for a kind change, and `purge` only for explicit destruction. Non-purge directives target a column changed in that same write. The server fails loudly before writing when a lossy change needs a directive: inspect every returned `issues[]` item, including its per-value row counts, then choose an explicit policy and retry. Never guess a migration just to get a 200.\n\n**Source lifecycle** rides the same engine with the same all-or-nothing guarantees. Free: adding a source, adding a NEW column with a `source` binding, binding an existing column that holds zero values, changing a binding's `field`/`transform`, and changing a source's `args`/`config`/`connection`/`scriptId` (window changes churn staleness on the next pass — expect `stale` flips when narrowing). Rejected with a path-bearing issue: changing `joinKey` (immutable — remove the source and add it again), changing `connector` while the source owns rows (row count in the message), and binding an existing column that already holds values (purge it — or add a fresh column — and bind that instead; a sync pass would otherwise overwrite the data). Removing a source **detaches** its rows: values survive as ordinary columns, the `source`/`syncedAt`/`stale` envelope is stripped, and the report counts them in `detachedRows`. A patch removing a source must drop its column bindings in the same call — a dangling `source.of` is rejected before anything is written.\n\nSync never adopts rows it does not own: a pulled record whose join key matches an unowned row creates a second, source-owned row. Adding a source over a join-key column that already holds values therefore duplicates those records on the first pass — and remove-source → re-add duplicates for the same reason, because detached rows keep their values. To convert a hand-maintained model into a synced one, purge the old rows first or use a fresh join-key column.\n\nFor example, split a legacy `flag` into `priority` and `status` without losing data in one patch: add the two columns, map both from `flag`, update every affected query/page binding, then hide `flag`.\n\n```json\n{\n \"appId\": \"<app-id>\",\n \"definition\": {\n \"models\": {\n \"ticket\": {\n \"columns\": {\n \"priority\": { \"kind\": \"enum\", \"enum\": [\"none\", \"low\", \"high\"] },\n \"status\": { \"kind\": \"enum\", \"enum\": [\"open\", \"watching\", \"done\"] },\n \"flag\": { \"kind\": \"string\", \"hidden\": true }\n }\n }\n }\n },\n \"migration\": {\n \"priority\": { \"from\": \"flag\", \"map\": { \"urgent\": \"high\", \"watch\": \"low\" }, \"else\": \"none\" },\n \"status\": { \"from\": \"flag\", \"map\": { \"watch\": \"watching\", \"done\": \"done\" }, \"else\": \"open\" }\n }\n}\n```\n\nEvery schema migration returns `{ scanned, backfilled, coerced, mapped, elsed, purgedValues, idxRebuilt, detachedRows, orphanFields }`. Read `orphanFields`: it reports extra row fields that predate or no longer appear in the definition; they are preserved until an explicit purge. `schemaVersion` is server-managed: never set it in an input patch or try to use it as application data.\n\nEvery successful definition write snapshots the previous definition. Use `app-history` to select a version, `app-diff({ appId, from: <version> })` to inspect it against CURRENT, then `app-rollback({ appId, version: <version>, migration? })` to restore it. Rollback is a forward migration over live rows, not row-level time travel: it creates a new pre-rollback snapshot and may reject a lossy restore with the same migration directives and counts. A rejected rollback changes nothing.\n\n### Per-user configuration\n\n`userConfig` declares up to 20 typed settings in the versioned definition; its values are deliberately stored outside the definition, separately for each user (and the operator dashboard). Each field is `{ \"kind\": \"string\" | \"number\" | \"boolean\" | \"date\" | \"enum\", \"default\"?: ..., \"enum\"?: [...], \"label\"?: \"...\" }`. Defaults follow column rules, including enum membership; `required` is not allowed. A missing or obsolete stored value reads as its default, or `null` when no default is declared.\n\nUse `{ \"$state\": \"/user/<field>\" }` on a page for the read-only current-user binding; the field must be declared and the path cannot continue below it. Pure and bound reusable elements cannot bind `/user` directly — pass the value through an element prop from the consuming page. An agent acting on an owned user-requested task reads and edits that requester's preferences. `userConfig` schema changes are always migration-compatible and appear in migration reports; no migration directives are needed. Rollback restores the historical schema but never alters saved per-user values, so values can resurface when a field returns.\n\n### Theming\n\nAn optional top-level `\"theme\"` sets the preset the dashboard applies to the app's rendered canvas: a lowercase slug validated by shape only. The preset catalog ships with the dashboard and lives in `src/themes/presets.ts` and `src/themes/classics.ts`. Update this list and the `app-upsert` tool description when it changes. Current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, `paper` (the warm editorial paper look), and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette: hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `\"hive\"` is an explicit reset to the stock look even inside a themed dashboard.\n\nViewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.\n\nAn optional top-level `\"icon\"` sets the app's icon on the dashboard Apps page. It takes one of three shapes:\n\n- `{ \"type\": \"lucide\", \"icon\": \"<kebab-case lucide name>\", \"color\": \"#RRGGBB\" }` (`color` optional). The dashboard looks the name up in its curated icon catalog and shows a generic grid icon for an unknown name.\n- `{ \"type\": \"url\", \"url\": \"https://...\" }`: an https image link, at most 2048 characters, no credentials.\n- `{ \"type\": \"agent-fs\", \"path\": \"/apps/<appId>/icon.png\" }`: an image on the swarm's agent-fs drive. Add both `orgId` and `driveId` for another drive; never just one.\n\nThe server validates shape only. The dashboard shows the grid glyph while an image loads, when it fails to load, and when the viewer has no agent-fs connected, so omitting `icon` is always safe. `app-patch` replaces `icon` whole, so switching shapes leaves no keys from the old one.\n\n\nDistinguish the two rollback 400s. A lossy-migration 400 is fixable: copy the required `migration` entries from the message and retry. A target-snapshot validation 400 explicitly says that directives cannot repair that historical definition; use `app-history` and choose a different version.\n\nWhen a schema patch reports stale page/query bindings, repair them in that same patch. Page elements are atomic: replace the complete `pages.<page>.elements.<id>` declaration, removing any reference to a hidden or deleted column, instead of sending only the changed nested prop. This is also the repair move for older apps whose stored page already references an undeclared column; full-definition validation otherwise blocks every patch.\n\n## Definition reference\n\n```json\n{\n \"models\": {\n \"modelName\": {\n \"columns\": {\n \"externalId\": { \"kind\": \"string\" },\n \"title\": { \"kind\": \"string\" }\n }\n }\n },\n \"queries\": { \"queryName\": { \"model\": \"modelName\" } },\n \"actions\": { \"actionName\": { \"kind\": \"task\", \"prompt\": \"Review the current rows and report\" } },\n \"pages\": {\n \"main\": {\n \"root\": \"root\",\n \"elements\": { \"root\": { \"type\": \"Container\", \"props\": {} } }\n }\n },\n \"defaultPage\": \"main\",\n \"theme\": \"ember\"\n}\n```\n\nOptional top-level `layout: \"sidebar\"` turns on the app shell (see Pages, routes, and page trees). Without it every page renders on the plain canvas, exactly as before.\n\nModel, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-10 models and at most 20 reusable elements; each declared model has 1-40 columns. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.\n\n### Reusable elements\n\nTop-level `elements` are versioned inside the app definition and can be reused from the app's own pages or, when explicitly exported, from another app. They are private by default. Each entry declares a `mode`, optional typed `props`, one `root`, and a flat `elements` node map using the same validated tree vocabulary as a page:\n\n```json\n{\n \"elements\": {\n \"statCard\": {\n \"mode\": \"pure\",\n \"export\": true,\n \"props\": {\n \"label\": { \"kind\": \"string\", \"required\": true },\n \"value\": { \"kind\": \"number\", \"default\": 0 }\n },\n \"root\": \"card\",\n \"elements\": {\n \"card\": { \"type\": \"Card\", \"props\": {}, \"children\": [\"label\", \"slot\"] },\n \"label\": { \"type\": \"Metric\", \"props\": { \"label\": { \"$state\": \"/props/label\" }, \"value\": { \"$state\": \"/props/value\" } } },\n \"slot\": { \"type\": \"ElementSlot\", \"props\": {} }\n }\n }\n }\n}\n```\n\n- `pure` elements may read only their declared `/props/<name>` state; `$item` and `$index` are also legal inside repeated nodes. They cannot invoke any action step. A pure tree may contain at most one leaf `ElementSlot` where consumer children are inserted.\n- `bound` elements may additionally read the defining app's declared queries and actions and use its models. Those references are validated against the defining app, including hidden-column rules. Exported bound elements cannot use `app.navigate`; private bound elements may navigate within their defining app.\n- Prop kinds are `string`, `number`, `boolean`, `date`, or `enum`. An enum prop requires a non-empty `enum: [\"value\", ...]` values array. A literal default and each literal consumer value must match the kind and, for enums, be one of those values. A required prop without a default must be supplied.\n\nReference an element with an `ElementRef` node. Omit `app` for same-app reuse; cross-app references name the defining app id and require `export: true`. `instanceKey` is optional. Consumer `children` are accepted only when the target has an `ElementSlot`:\n\n```json\n{\n \"type\": \"ElementRef\",\n \"props\": {\n \"app\": \"<defining-app-id>\",\n \"element\": \"statCard\",\n \"props\": { \"label\": \"Open issues\", \"value\": 12 },\n \"instanceKey\": \"openIssues\"\n },\n \"children\": [\"details\"]\n}\n```\n\nElement references float to the defining app's current definition. `app` and `element` must be literal strings; dynamic references are not supported. The server rejects reference cycles and expansion deeper than five, missing/private targets, invalid props, and a breaking write to an exported element that other apps reference. Removing or unexporting an exported element, changing its mode, removing a declared prop, changing a prop kind, or adding a required prop without a default is breaking; publish the new contract under a new element name. If consumers are abandoned intentionally, retry the PUT, PATCH, or rollback with `\"forceElementBreak\": [\"elementName\"]`. The named consumers will then render an error once element rendering is available; deleting an entire app is deliberately not compatibility-gated.\n\n### Models\n\nEach column is `{ \"kind\": ..., \"required\"?: boolean, \"default\"?: ..., \"index\"?: boolean, \"enum\"?: string[], \"hidden\"?: boolean }`.\n\n| `kind` | Values and indexing |\n|---|---|\n| `string` | String value; set `index: true` only when equality lookups need it. |\n| `number` | Finite number; never indexed. |\n| `boolean` | Boolean; set `index: true` only when equality lookups need it. |\n| `date` | ISO-8601 string; never indexed. |\n| `enum` | String from the non-empty unique `enum` list; always indexed, without `index: true`. |\n| `json` | Any JSON value (object, array, nested) up to 256 KB serialized by default (`APPS_JSON_COLUMN_MAX_BYTES`); never indexed, and a named query cannot `filter` or `sort` on it. Not allowed for `userConfig` fields or element props. |\n\n`default` must match the column kind (and be one of the enum values). `required: true` rejects missing/null values unless a default supplies the value. `id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` — and the sync envelope `source`, `syncedAt`, `stale` — are system columns and reserved names. An app created before the sync envelope that declared ordinary columns with these names surfaces `definitionError` after upgrade until they are renamed: patch in a fresh column with a `{from}` migration directive, then purge the old one. Rows always expose `id`/`createdAt`/`updatedAt`; `createdBy`/`updatedBy` record the acting principal (`user:<id>`, `agent:<id>`, `operator`, or `sync:<source>` for engine writes) and are system-managed on every row write.\n\n### Sources and sync\n\nA model may declare up to 4 named `sources` — one-way inbound projections of an external system into its rows. The `script` connector is THE way to bring external data in (GitHub, Linear, any API): a saved script owns the fetch, its auth placeholders, and its paging. `swarm-tasks` is the one native connector, projecting this swarm's own task pool (`config`: `status`/`tags` comma-lists, `agentId`, `assetKey` namespace prefix, `limit` up to 200 — default 100, `includeHeartbeat`). Synced rows are readable by EVERY principal with `app.use` on the app; an unscoped `swarm-tasks` source publishes task prompts (truncated, secret-scrubbed) to all of them, so scope it with `config.assetKey`/`config.agentId` unless that exposure is intended. A user-invoked sync only ever pulls the invoking user's own requested tasks. Script sources run with their run-as identity's credentials — an agent-owned script runs as its owner and only the owner may wire it; an owner-less catalog (global) script runs as the LEAD, so only the lead or the operator can wire or alter such a source (stored references stay valid with their args and connection pinned).\n\n```json\n{\n \"models\": {\n \"issue\": {\n \"columns\": {\n \"issueKey\": { \"kind\": \"string\" },\n \"title\": { \"kind\": \"string\", \"source\": { \"of\": \"gh\", \"field\": \"title\" } },\n \"openedAt\": { \"kind\": \"date\", \"source\": { \"of\": \"gh\", \"field\": \"created_at\", \"transform\": \"date-parse\" } },\n \"note\": { \"kind\": \"string\" }\n },\n \"sources\": {\n \"gh\": { \"connector\": \"script\", \"scriptId\": \"<script-uuid>\", \"joinKey\": \"issueKey\", \"args\": { \"repo\": \"owner/name\" }, \"connection\": \"github\" }\n }\n }\n }\n}\n```\n\n- **Join key**: each source names a `joinKey` — an owned, non-hidden `string` column carrying the external identity. It must not be `required`, must not declare a `default`, and cannot itself be source-bound. A row belongs to at most ONE source (`row.source`).\n- **Column bindings**: `{ \"of\": \"<sourceName>\", \"field\": \"user.login\", \"transform\"? }` projects a (dotted-path) field of the pulled record into the column on every pass. Transforms and their required column kinds: `slug`/`lower`/`upper` → `string`, `cents` → `number` (×100, rounded), `date-parse` → `date` (ISO). A failed transform nulls that one column and warns; it never fails the pass.\n- **Read-only contract**: source-bound columns and the join key reject every direct write (row create/patch/bulk) with a path-bearing issue — mutate them via the source or a sync refresh. Owned columns on the same model stay writable. Every `required` owned column on a sourced model must declare a `default`, because sync-created rows cannot supply it.\n- **Provenance**: synced rows carry `source` (owner), `syncedAt` (last confirmed presence — sortable), and `stale` (true when a complete pull no longer returned the record; clears on reappearance). `syncedAt` advances on every confirmed row WITHOUT touching `updatedAt`; `updatedAt` moves only when projected data actually changed.\n- **`connection`** (optional, script sources): names a connections-system slug the source depends on. It buys write-time validation plus a preflight before every pull; it does not by itself gate egress. Credentials resolve for the sync run-as identity — the script's owner when it has one, else the lead agent — so global connections always work and agent-scoped ones need matching script ownership. The slug is injected into the script's args as `connection`, letting one generic script serve N connections.\n\n**The canonical sync-script contract** (every sync script, always):\n\n```ts\nexport default async function run(args, ctx) {\n // args = { ...source.args, app: { id }, model: \"<model>\", source: \"<sourceName>\", connection?: \"<slug>\" }\n const records = [{ key: \"42\", fields: { title: \"…\", created_at: \"…\" } }];\n return { records, complete: true }; // or return the bare array — a bare array IS a complete snapshot\n}\n```\n\nReturn `Array<{ key, fields }>` or `{ records, complete? }`. `key` is the external identity the engine joins on `joinKey` (numbers are coerced to strings); `fields` is the bag bindings project from. Return `complete: false` whenever the pull window may have missed records — a paged fetch, a hit `limit`, or client-side filtering of a full page. An incomplete pull skips the stale sweep, so rows outside a narrow window are not falsely marked stale; compute `complete` BEFORE any client-side filtering. Hard cap 500 records per pull (over-cap pulls truncate and count as incomplete). An invalid return shape, thrown error, or non-zero exit fails the pass with zero row churn.\n\nThe seeded catalog script `github-issues-pull` is the worked example (placeholder auth via `[REDACTED:GITHUB_TOKEN]`, PR filtering, `complete` computed before filtering). For scheduled refreshes, point a `targetType: \"script\"` schedule at the seeded `app-sync-run` with `scriptArgs: { \"appId\": \"<id>\", \"model\"?, \"source\"? }`.\n\n**Three refresh doors, one engine**: `POST /api/apps/<id>/sync` (body `{ \"model\"?, \"source\"? }`), a `sync` action kind, and the `app-sync` MCP tool (`ctx.swarm.app_sync` from scripts). `{model?, source?}` fans out to every matching (model × source) pair; each pass reports `{ pulled, created, updated, refreshed, unchanged, markedStale, warnings }`. A pair already syncing in this API process short-circuits with `alreadyRunning: true` instead of pulling twice. Each pair's last-pass status (`lastFinishedAt`, counts, `error?`) comes back as `syncStatus` — keyed `\"<model>:<source>\"` — on `GET /api/apps/<id>` and in `app-get` data, so UI and agents can render \"last synced / last error\" without extra calls.\n\n### Freshness and the refresh button\n\nFreshness renders with the existing column kinds — no special components. Give the table `{ \"key\": \"syncedAt\", \"kind\": \"date\" }` and `{ \"key\": \"stale\", \"kind\": \"badge\", \"tones\": { \"true\": \"warning\" } }` columns, declare a `sync` action, and wire a Button to it:\n\n```json\n{\n \"actions\": { \"refresh\": { \"kind\": \"sync\" } },\n \"pages\": {\n \"main\": {\n \"root\": \"root\",\n \"elements\": {\n \"root\": { \"type\": \"Container\", \"props\": {}, \"children\": [\"refreshBtn\", \"issuesTable\"] },\n \"refreshBtn\": {\n \"type\": \"Button\",\n \"props\": { \"label\": \"Refresh\" },\n \"on\": { \"press\": [{ \"action\": \"app.action\", \"params\": { \"name\": \"refresh\" } }] }\n },\n \"issuesTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIssues/data\" },\n \"columns\": [\n { \"key\": \"title\", \"label\": \"Issue\" },\n { \"key\": \"syncedAt\", \"label\": \"Synced\", \"kind\": \"date\" },\n { \"key\": \"stale\", \"label\": \"Stale\", \"kind\": \"badge\", \"tones\": { \"true\": \"warning\" } }\n ]\n }\n }\n }\n }\n }\n}\n```\n\nA `sync` action answers the script-action state shape (`/actions/refresh` → `running` → `ok`/`error`, result under `result.passes`), so the page's queries refetch when it completes. Use `app-query` to READ rows (named queries may filter on `stale`/`source` and sort by `syncedAt`); use `app-sync` to REFRESH sources; never poll a sync door in a loop — schedule it or give people the button.\n\n### Queries\n\nA named query is:\n\n```json\n{\n \"model\": \"idea\",\n \"filter\": { \"status\": \"open\" },\n \"sort\": { \"column\": \"createdAt\", \"dir\": \"desc\" },\n \"limit\": 100\n}\n```\n\n`filter` is a strict AND of equality checks. A filter may target a declared model column or a system column (`id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and on synced models `source`, `syncedAt`, `stale`) — filtering on `id` is the universal way to select one row for a detail view, and `{ \"stale\": true }` selects rows a complete pull stopped confirming. A literal value must match the column's kind; date filters compare the stored raw ISO string, not parsed instants. Omit `limit` for the default 200 rows, or set an integer from 1 through 1000. `sort.column` is a non-`json` model column, `createdAt`, `updatedAt`, or `syncedAt`; `dir` is `asc` or `desc`. Query runtime state is `{ data, loading, error }` under `/queries/<queryName>`.\n\nA filter value may instead be exactly `{ \"$param\": \"<name>\" }`. At execution, the caller supplies that name and the server coerces its value to the filtered column's kind before equality matching:\n\n```json\n{\n \"queries\": {\n \"issueDetail\": { \"model\": \"issue\", \"filter\": { \"issueId\": { \"$param\": \"issueId\" } }, \"limit\": 1 }\n }\n}\n```\n\nThe placeholder object must contain only `$param`. Missing caller values fail loudly rather than returning unfiltered rows: HTTP reports 400 and `app-query` returns a tool error listing every missing name. Supplying a param name the query does not reference is also an error. The app UI supplies current declared route params automatically. Direct calls use `app-query({ appId, query: \"issueDetail\", params: { issueId: 42 } })` or `ctx.swarm.app_query({ appId, query: \"issueDetail\", params: { issueId: 42 } })`.\n\n### Custom actions\n\nActions are optional (maximum 20) and are invoked from the page with the `app.action` runtime action.\n\n```json\n{\n \"actions\": {\n \"recalculate\": {\n \"kind\": \"script\",\n \"scriptId\": \"00000000-0000-4000-8000-000000000000\",\n \"args\": { \"mode\": \"fast\" }\n },\n \"triage\": {\n \"kind\": \"task\",\n \"prompt\": \"Triage this idea and report a recommendation\"\n }\n }\n}\n```\n\n| Kind | Contract |\n|---|---|\n| `script` | `scriptId` must identify an existing script; optional `args` are defaults. Invocation input overrides same-named defaults, and the runtime also supplies `app: { id }`. |\n| `task` | `prompt` must be non-empty; omit `agentId` to use default (lead) assignment. Only set `agentId` to a real agent UUID. Invocation `input` is included as context for the task prompt. Spawned tasks carry asset key `shared/app:<appId>/action:<name>/`, so a `swarm-tasks` source with `config.assetKey: \"shared/app:<appId>/\"` pulls back the tasks this app spawned. |\n| `sync` | Optional `model` and `source` narrow which (model × source) pairs refresh; omitting both syncs every pair the app declares. At least one pair must exist. Answers the script-kind state shape with per-pass results under `result.passes`. |\n\n- Invocation state lands at `/actions/<name>` as `{ status, result?, error?, taskId?, taskStatus? }`, where `status` is `\"running\"`, `\"ok\"`, or `\"error\"`.\n\nUse a task action named Tackle when a person should hand one issue row to the swarm. Pass the complete current row under `input.issue`; `{ \"$row\": \"\" }` resolves to the whole row and that context lands in the task prompt.\n\n```json\n{\n \"actions\": {\n \"tackle\": { \"kind\": \"task\", \"prompt\": \"Tackle this issue. Inspect the supplied issue context, do the work, and report the outcome.\" }\n },\n \"pages\": {\n \"main\": {\n \"root\": \"issuesTable\",\n \"elements\": {\n \"issuesTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIssues/data\" },\n \"columns\": [{ \"key\": \"title\", \"label\": \"Issue\" }],\n \"rowActions\": [{\n \"label\": \"Tackle\",\n \"actions\": [{\n \"action\": \"app.action\",\n \"params\": { \"name\": \"tackle\", \"input\": { \"issue\": { \"$row\": \"\" } } }\n }]\n }]\n }\n }\n }\n }\n },\n \"defaultPage\": \"main\"\n}\n```\n\nFor direct MCP calls, `app-query` accepts `{ appId, query, params? }` and returns rows from that declared named query; every supplied param must be referenced by a `$param` filter in that query. Use it when an agent needs to read app state without scraping the UI.\n\nSaved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.\n\n### Pages, routes, and page trees\n\n`pages` is a map of independently validated page trees and `defaultPage` must name one entry. Each page may also declare a display `title` and typed route `params`. On every non-default page the runtime automatically renders breadcrumbs (`<default page title> › <current page title>`, first crumb navigates back) — including in chromeless embeds — so a detail page does NOT need its own back button; give pages good `title`s instead. This complete pattern connects a table row to a typed detail route and its parameterized query:\n\n```json\n{\n \"models\": {\n \"issue\": {\n \"columns\": {\n \"issueId\": { \"kind\": \"number\" },\n \"title\": { \"kind\": \"string\" },\n \"status\": { \"kind\": \"string\" }\n }\n }\n },\n \"queries\": {\n \"allIssues\": { \"model\": \"issue\" },\n \"issueDetail\": {\n \"model\": \"issue\",\n \"filter\": { \"issueId\": { \"$param\": \"issueId\" } },\n \"limit\": 1\n }\n },\n \"pages\": {\n \"issues\": {\n \"title\": \"Issues\",\n \"root\": \"issuesTable\",\n \"elements\": {\n \"issuesTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIssues/data\" },\n \"columns\": [\n { \"key\": \"title\", \"label\": \"Issue\" },\n { \"key\": \"status\", \"label\": \"Status\", \"kind\": \"badge\" }\n ],\n \"rowActions\": [{\n \"label\": \"Open\",\n \"actions\": [{\n \"action\": \"app.navigate\",\n \"params\": {\n \"page\": \"detail\",\n \"params\": { \"issueId\": { \"$row\": \"issueId\" } }\n }\n }]\n }]\n }\n }\n }\n },\n \"detail\": {\n \"title\": \"Issue detail\",\n \"params\": { \"issueId\": { \"kind\": \"number\", \"required\": true } },\n \"root\": \"detail\",\n \"elements\": {\n \"detail\": {\n \"type\": \"DetailList\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/issueDetail/data/0\" },\n \"fields\": [{ \"key\": \"title\", \"label\": \"Issue\" }]\n }\n }\n }\n }\n },\n \"defaultPage\": \"issues\"\n}\n```\n\nDrawer variant: declare a route param on the containing page, set the Drawer `props.param` to that literal param name, and use the same `app.navigate` shape targeting that page with the row id assigned to the Drawer's param. The Drawer then opens from route state without a separate action contract.\n\nApp shell (`layout: \"sidebar\"` at the top level of the definition): every page renders inside a left sidebar that lists the app's pages and a sticky page header. Per page:\n\n- `title`: the sidebar label and the header heading (defaults to the page name).\n- `icon`: one catalog icon name (the list under Component catalog) before the sidebar label; unknown names are rejected.\n- `description`: one line under the header title (at most 280 characters).\n- `headerActions`: the key of one element of this page, rendered in the header's actions slot (right side), e.g. a Refresh `Button` with `on.press: [{ \"action\": \"app.refresh\" }]` or a row `Stack` of buttons. It is a second root: it must exist in the page's `elements` and must NOT also be reachable from `root`. It shares the page's state and actions.\n- `nav: false`: leave the page out of the sidebar. Pages with a `required` param never list (they cannot open without it); open them with `app.navigate`.\n\nThe sidebar lists pages in definition order and marks the current one. Below 768px it folds into a menu button at the left of the header. Crumbs back to the default page show in the header only on pages the sidebar does not list. The shell renders in every view mode: inside the bordered canvas (default view, under the dashboard header that names the app), under the slim bar in `?mode=full`, and as the whole viewport in `?mode=chromeless`, where the sidebar also shows the app name (it is the only navigation inside an iframe). `headerActions` and `nav` without `layout: \"sidebar\"` are rejected; `icon` and `description` are accepted and unused.\n\n```json\n{\n \"layout\": \"sidebar\",\n \"defaultPage\": \"overview\",\n \"pages\": {\n \"overview\": {\n \"title\": \"Overview\",\n \"icon\": \"activity\",\n \"description\": \"Deploys and spend, last 14 days.\",\n \"headerActions\": \"refresh\",\n \"root\": \"root\",\n \"elements\": {\n \"root\": { \"type\": \"Stack\", \"props\": {}, \"children\": [\"spend\"] },\n \"spend\": {\n \"type\": \"Chart\",\n \"props\": {\n \"kind\": \"area\",\n \"data\": { \"$state\": \"/queries/days/data\" },\n \"loading\": { \"$state\": \"/queries/days/loading\" },\n \"x\": \"date\",\n \"xType\": \"time\",\n \"format\": \"currency\",\n \"series\": [{ \"key\": \"spend\", \"label\": \"Spend\" }]\n }\n },\n \"refresh\": {\n \"type\": \"Button\",\n \"props\": { \"label\": \"Refresh\", \"icon\": \"refresh-cw\", \"variant\": \"outline\", \"size\": \"sm\" },\n \"on\": { \"press\": [{ \"action\": \"app.refresh\" }] }\n }\n }\n },\n \"settings\": { \"title\": \"Settings\", \"icon\": \"pencil\", \"root\": \"root\", \"elements\": { \"root\": { \"type\": \"Text\", \"props\": { \"content\": \"…\" } } } }\n }\n}\n```\n\nParam `kind` is `string` by default, or `number` / `boolean`; `required` defaults to false. The names `mode`, `apiUrl`, `apiKey`, `email`, and `name` are reserved. `/apps/<id>` renders `defaultPage`; `/apps/<id>/p/<page>?issueId=42` is the shareable deep link for another page. Browser navigation is client-side, so app state and polled data stay warm across page changes.\n\nWithin each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Accordion, Container, Card, Section, Drawer, and Dialog). `watch` maps state paths to an action step or chain.\n\n## Component catalog (all 45)\n\nProps reject unknown keys. A `{\"$state\":\"...\"}` binding may replace a literal prop value at any depth.\n\nIcons: every `icon` prop (and the `Icon` block) takes one name from a curated lucide set: `plus`, `refresh-cw`, `search`, `filter`, `download`, `upload`, `external-link`, `copy`, `check`, `x`, `trash-2`, `pencil`, `eye`, `calendar`, `clock`, `user`, `users`, `bot`, `git-pull-request`, `git-branch`, `github`, `slack`, `mail`, `link`, `file-text`, `folder`, `database`, `zap`, `sparkles`, `flag`, `star`, `tag`, `alert-triangle`, `info`, `circle-check`, `trending-up`, `trending-down`, `dollar-sign`, `activity`, `rocket`. Any other name is rejected.\n\nTones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `error`, `info`, `pending`, `warning`, or `paused`.\n\n| Component | Required props | Optional props / values |\n|---|---|---|\n| `Stack` | none | Primary layout; `direction: \"column\", \"row\"`, `gap`, `padding: \"none\", \"xs\", \"sm\", \"md\", \"lg\", \"xl\"`; `align: \"start\", \"center\", \"end\", \"stretch\"`, `justify: \"start\", \"center\", \"end\", \"between\"`, `wrap`; `motion: \"rise\"` (default), `\"fade\"`, or `\"none\"` (see Motion below); `fill` (grow to fill a `fill`-aware parent; see Layout below); has the `default` child slot. |\n| `Grid` | none | Responsive `columns`: integer 1 through 6, or `{ base, sm, md, lg }` counts 1 through 6; `gap` uses the Stack spacing values; has the `default` child slot. |\n| `Split` | none | `ratio: \"1-1\", \"1-2\", \"2-1\", \"1-3\", \"3-1\"`, `gap`, `collapseBelow: \"sm\", \"md\", \"lg\"`, `reverse`, `fill` (same contract as Stack); has the positional `default` child slot. |\n| `Divider` | none | `label`, `orientation: \"horizontal\"` (default) or `\"vertical\"` (a rule between the items of a row `Stack`, as tall as the row); no children. |\n| `Tabs` | `id`, `tabs` | `tabs` entries are `{ key, label?, icon?, count? }` (`count` is a number shown as a small pill); `defaultTab`; `variant: \"line\"` (default) or `\"segmented\"` (a compact segmented control, same state and warm panels); has the positional `default` child slot. |\n| `Accordion` | `id`, `items` | Grouped collapsible sections. `items` entries are `{ key, title, description?, icon? }`; children are positional like Tabs (`children[i]` is the body of `items[i]`, same count, validated). `type: \"single\"` (default: opening one closes the others, and the open one can close) or `\"multiple\"`. Open keys are client state at `{ \"$state\": \"/ui/<id>/open\" }`, always an array; `defaultOpen` lists the keys open on first render. Bodies mount only while open. `Section collapsible` stays the one-item form. |\n| `Container` | none | Legacy layout primitive; prefer Stack. `direction: \"row\", \"column\"`, `gap: \"none\", \"sm\", \"md\", \"lg\"`; has the `default` child slot. |\n| `Card` | none | `title`, `description`; has the `default` child slot. |\n| `Heading` | `text` | `level: \"h1\", \"h2\", or \"h3\"`. |\n| `Text` | `content` | `tone: \"default\" or \"muted\"`. |\n| `Markdown` | `content` | Rendered Markdown for help, instructions, and rich prose; no children. A link to a GitHub PR, issue, commit or repo, a dashboard task, agent, session or app, or an agent-fs file renders as a chip (icon plus short label), like agent output in a session; `[text](url)` keeps its text. |\n| `SearchInput` | `id` | `placeholder`, `label`, `shortcut` (one key, usually `\"/\"`: shows a keycap and focuses the field); writes debounced text to `/ui/<id>/value`; no children. |\n| `Select` | `id`, `options` | `options` are strings or `{ value, label?, icon?, hint? }`; `placeholder`, `label`, `clearable`, `searchable` (type to filter; on by default past 8 options), `searchPlaceholder`, `multiple`, `defaultValue` (seeds `/ui/<id>/value` once, before any interaction; a one-entry array with `multiple`; a value bound to a query that is still loading seeds when it arrives, unless the viewer already picked); writes a string or null to `/ui/<id>/value`, or with `multiple` a string array (empty = nothing picked); no children. |\n| `NumberInput` | `id` | `label`, `placeholder`, `min`, `max`; a text field with a decimal keyboard that writes the parsed number to `/ui/<id>/value` on every change (no debounce), or null when the field is empty; non-numeric text (a bare `-` mid-edit, letters) leaves the stored value untouched; `min`/`max` clamp the stored value and the visible text snaps to it when the field loses focus; no children. |\n| `Chips` | `id`, `options` | Toggle chips for quick filters. `options` are strings or `{ value, label?, icon? }`; `multiple`; `label` (group name for screen readers). Writes a string or null to `/ui/<id>/value`, or a string array with `multiple`; pressing the selected chip clears it. |\n| `Button` | `label` | `variant: \"default\", \"secondary\", \"outline\", \"ghost\", \"destructive\", or \"destructive-outline\"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: \"<actionName>\"` swaps the label for a spinner while that custom action's `/actions/<name>/status` is `\"running\"` (presses are ignored), then shows a check and `successLabel` for about 1.5s when it turns `\"ok\"`; `icon`, `iconPosition: \"start\" or \"end\"`; `size: \"sm\", \"default\", or \"lg\"`; `shortcut` (one key, shown as a keycap, presses the button); `hint` (tooltip); dispatch with element-level `on.press`. |\n| `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: \"up\", \"down\", or \"flat\", label }`; `info` (explanation tooltip next to the label). `sparkline`: a small trend line under the value in the `tone` color, from an array of numbers (`null` is a gap) or from rows (bind `/queries/<name>/data`) read through `sparklineKey`; fewer than two points draws nothing. `format: \"number\"`, `\"currency\"` (with `currency`, an ISO code, default `USD`) or `\"percent\"` (a ratio: 0.42 is 42%) formats a numeric `value`, like Chart; a string value shows as is. |\n| `Chart` | `kind`, `x`, `series` | `kind: \"line\", \"area\", \"bar\", \"pie\" or \"donut\"`; bind `data` / `loading` / `error` to a named query like Table. `x` is the row field on the x axis; `xType: \"category\"` (default, row order) or `\"time\"` (ISO date or epoch ms, sorted, date ticks; rows whose `x` does not parse are dropped). `series`: 1-8 `{ key, label?, color? }`, `color` one of `chart-1`..`chart-5`, `primary`, `success`, `warning`, `error`, `info`, `muted` (default palette, in order: `primary`, `chart-2`..`chart-5`). `stacked` stacks area and bar series (lines never stack). `format: \"number\"` (default), `\"currency\"` (with `currency`, an ISO code, default `USD`) or `\"percent\"` (values are ratios: 0.42 is 42%). Tooltip on hover; the legend shows with two or more series (`legend` forces it on or off). `height` 120-640 px (default 240); `emptyMessage` (default \"No data yet\"). `x` and every `series[].key` must be columns of the bound query's model. `pie` and `donut` take exactly one series: `x` is the slice label, each row with a positive value is a slice labelled with its share, the tooltip adds the share to the formatted value, and the legend defaults on (`xType` and `stacked` do not apply). Wrap it in a `Card` for a title. |\n| `Alert` | `message` | `title`, `tone: \"info\", \"success\", \"warning\", or \"error\"`, `icon` (overrides the tone icon), `actionLabel` (a button inside the callout that emits `press`; wire it with `on.press`). |\n| `Badge` | `text` | `text` is string or number; `tone`; `icon` replaces the dot; `variant: \"tag\"` (default uppercase chip), `\"status\"` (sentence-case pill), `\"count\"` (numeric pill), or `\"beta\"` (the BETA tag); `status` (a lifecycle value renders the dashboard status chip); `hint` (tooltip; the beta tag's explanation). |\n| `Icon` | `name` | `size: \"sm\", \"md\", or \"lg\"`, `tone: \"default\", \"muted\", \"success\", \"warning\", \"error\", or \"info\"`, `label` (accessible name; decorative without it). |\n| `Progress` | `value` | `max` (default 100), `tone`, `label`, `variant: \"bar\"` (default) or `\"ring\"` (the dashboard progress ring; ignores `tone`), `showValue` (default true: percent for a bar, `value / max` for a ring). |\n| `EmptyState` | `title` | `icon` (default inbox), `body`, `actionLabel` (a button that emits `press`; wire it with `on.press`). |\n| `CopyButton` | `value` | `value` is string or number; `label` is the visible text, icon-only without it. Renders nothing for an empty value. |\n| `Kbd` | `keys` | Keycaps, one per string (`[\"⌘\", \"K\"]`). Display only. |\n| `Skeleton` | `shape` | `shape: \"line\", \"block\", \"rows\", \"metric\", or \"card\"`; `count` (1-20: lines, rows, tiles, or cards); `height` (px, `block` only, default 128). Show it with `visible` bound to a query's `loading`. |\n| `Spinner` | none | `variant: \"ring\", \"ellipsis\", or \"bars\"` (default: the dashboard spinner), `size: \"sm\" or \"md\"`, `label` (visible text and accessible name). |\n| `AvatarStack` | `users` | `users` are display names (initials avatars); `max` (default 4) before a `+N` count. Hover lists every name. |\n| `Section` | `title` | `description`, `collapsible`, `defaultOpen` (default true); has the `default` child slot. |\n| `Table` | `columns` | `data`, `loading`, `refreshing`, `error`, `emptyMessage`, `emptyState`, `rowActions`, `id`, `selectable`, `bulkActions`, `filterable`, `clearState`, `onRetry`, `onRowClick`, `selectedId`, `rowId`, `mobile`, `mobileFields`, `search`, `filters`; see below. |\n| `Form` | `id`, `fields`, `onSubmit` | `title`, `submitLabel`; see below. |\n| `Drawer` | `param` | `title`, `description`, `side: \"right\" or \"left\"`, `size: \"sm\", \"md\" (default), \"lg\", or \"xl\"` (about 480/660/900/1010px at 1440px; grows with the viewport up to 640/960/1280/1600px; full width on phones), `actions` (sticky footer buttons; see below), `presentation: \"sheet\"` (default) or `\"split\"` (an inline right pane beside the page; see below); has the `default` child slot. |\n| `Dialog` | `param` | A centered modal with the Drawer route contract: open exactly while the page param named by `param` is set; Escape, the X or a click outside clears it. `title`, `description`, `size: \"sm\", \"md\" (default), or \"lg\"`, `actions` (footer buttons, Drawer rules). Use it for a short form opened from `headerActions`; after the write, an `app.navigate` without the param closes it. Has the `default` child slot. |\n| `DetailList` | `fields` | `data`, `emptyMessage`, `columns: 1 or 2`, `loading` (bind `/queries/<name>/loading` for skeleton fields while loading); renders one record without edit controls; see below for field kinds. |\n| `CardGrid` | `titleKey` | `data`, `loading`, `error`, `emptyMessage`, `imageKey`, `fields`, `columns`, `onClick`; one card per row for record browsers; see below. |\n| `Kanban` | `columnField`, `columns`, `titleField` | `data`, `loading`, `cardFields`, `idField` (default `id`), `onMove`, `onCardClick`; see below. |\n| `Calendar` | `startField`, `titleField` | `data`, `loading`, `endField`, `idField`, `onSelect`; read-only month grid; see below. |\n| `ContributionGraph` | none | `data`, `loading`, `dateField` (default `date`), `countField`, `days` (7-730, default 365); read-only activity heatmap. |\n| `Tree` | `id`, `nodes` | `label`, `maxHeight` (default `480px`), `fill`; collapsible outline of a doc-shaped value that writes the clicked node key to `/ui/<id>/value`; see below. |\n| `Files` | `path` | `mode: \"list\"` (default) or `\"browser\"`, `selectedPath`, `emptyMessage`, `maxHeight` (default `480px`), `fill`, `onSelect`, `upload`; an agent-fs folder listing read as the viewer; see below. |\n| `File` | `path` | `height`, `fill`; one agent-fs file (Markdown, image, PDF, text) read as the viewer; see below. |\n| `DateRange` | `id` | `presets` (any of `7d`, `30d`, `90d`, `mtd`, `custom`; default all five), `defaultPreset` (default the first), `label`; writes `/ui/<id>/from` and `/ui/<id>/to`; see below. |\n| `Timeline` | `timeField`, `titleField` | `data`, `loading`, `descriptionField`, `statusField`, `tones`, `icon`, `emptyMessage`, `onSelect`; vertical event list, newest first, grouped by day; see below. |\n| `SchemaForm` | `id`, `schema` | `value`, `baseDoc`, `nodeKey`, `onChange`, `fill`; form generated from a JSON schema's `properties`, mirrored to `/ui/<id>/value`; see below. |\n| `Approval` | `requestId` | `showResolved` (default true), `compact`, `onResolved`; one approval request answered in place by the viewer; see below. |\n| `SessionThread` | `id`, `sessionKey` | `scope`, `placeholder`, `onDispatch`, `fill`; the dashboard's session conversation (the \"Session about this page\" panel) for one session per viewer and key, with a composer that steers or chains tasks; the draft is mirrored to `/ui/<id>/value`; see below. |\n| `PageFrame` | `pageId` | `device` (`desktop` default, or `mobile`: a 390 px wide frame), `height` (default `640px`), `fill`; a live, clickable swarm Page that reloads when the page changes; see below. |\n\nTable details:\n\n- `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: \"left\" or \"right\", align?: \"start\" or \"end\", truncate?: \"end\" or \"middle\", icon?, tooltip?: \"<row field>\", hint?: string, popover?: { title?, fields, trigger? }, href?: \"<row field>\", linkLabel?: \"<template>\", max?: number, format?: \"<template>\", currency?: \"<ISO 4217>\", onChange?: chain, filter?: \"values\" or \"text\" or false, muted?: string[] }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `checkbox`, `link`, `json`, `currency`, or `percent`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. `currency` shows a number as money in the column's `currency` (an uppercase ISO 4217 code, default `USD`): `1234.5` is `$1,234.50`. `percent` reads a ratio: `0.42` is `42%`. Both right-align and show a non-numeric value as is. Pin id/actions columns so they survive horizontal scroll on narrow viewports.\n - `status`: lifecycle values (`pending`, `in_progress`, `running`, `completed`, `failed`, `cancelled`, `paused`, `reviewing`, ...) render the dashboard status chip with its icon; other values use `tones` like `badge`.\n - `user` / `agent`: avatar plus name. `relative` (and `date`): smart time, exact time on hover. `duration`: milliseconds as `1m 23s`. `progress`: a bar against `max` (default 100). `copy`: the value plus a copy button. `link`: a smart link (see Smart links, tooltips and popovers below); any other http(s) URL opens in a new tab and other values render as text.\n - `switch` / `checkbox`: a toggle or a checkbox bound to a boolean column. `onChange` runs with `$row` = the row with this column already set to the new value, e.g. `[{ \"action\": \"app.mutate\", \"params\": { \"model\": \"m\", \"op\": \"update\", \"rowId\": { \"$row\": \"id\" }, \"values\": { \"enabled\": { \"$row\": \"enabled\" } } } }]`. Without `onChange` the control is read-only. Each toggle is a model write, so to pick rows for a bulk action use `selectable` (below), not a boolean column.\n - Numbers, durations and progress right-align by default. `truncate: \"middle\"` keeps both ends of ids and paths. `icon` shows in the header; `tooltip` names a row field shown in a styled tooltip on the cell (when the cell is plain text that gets cut off, the tooltip shows its full text without any config).\n - `format`: a `{{field}}` template that combines several row fields into one cell, e.g. `\"{{name}} ({{status}})\"`. Placeholder names match `[\\w.]+` (letters, digits, `_` and `.`; no hyphens or spaces). Each placeholder reads that row field as-is (a dotted name such as `{{owner.name}}` is a literal column name, not a nested path); a missing or null field becomes an empty string and an object or array becomes a JSON preview cut to 120 characters. The whole cell is capped at 500 characters. A templated column ignores `kind`, shows the same text in the phone list, and sorts by the composed text. `search` and `filters` still read the column's `key`.\n - `muted: [\"none\", \"no\"]`: those cell values (matched case-insensitively) render as a quiet `—` instead of a pill or text, for columns that are mostly `none` / `no`. The value stays in the data, in the filter list, as a hover title and for screen readers; the phone list leaves it out. Not applied to `switch` / `checkbox` cells.\n- `selectable` + `id`: a leading pinned checkbox column. The header checkbox selects every row left after `search` / `filters` (checked, unchecked or indeterminate; clicking it again clears those rows), and shift-click selects a range in the order shown. The selection is client state at `{ \"$state\": \"/ui/<id>/selected\" }`, an array of row ids (the `rowId` field, default `id`, as strings). It is never a model write and is not shared with other viewers. `id` is a literal like `SearchInput.id`, and the validator requires it with `selectable` or `bulkActions`. Selected rows that disappear from the data drop out of the selection.\n- `bulkActions[]`: `{ label, variant?, icon?, confirm?, actions }`, the `rowActions` shape without `placement`; a non-empty list implies `selectable`. A bar under the table shows `N selected`, the buttons and Clear while the selection is non-empty. Chains have no `$row`; pass the ids with `{ \"$state\": \"/ui/<id>/selected\" }`, e.g. `{ \"action\": \"app.action\", \"params\": { \"name\": \"enqueue\", \"input\": { \"prs\": { \"$state\": \"/ui/prTable/selected\" } } } }`. Confirm rules match `rowActions`; the dialog always adds the selection size (`Applies to 3 selected rows.`). The selection is locked while the chain runs. It clears (only the rows the chain acted on) once every step succeeded, waiting for a task-backed `app.action` to finish; a failed `app.mutate` or a failed task stops the chain and keeps the selection for a retry.\n- `filterable: true` + `id`: built-in column filters. Each filterable column gets a filter button in its header: `badge`, `status`, `enum`, `boolean`, `user` and `agent` columns open a checkbox list of the distinct values with row counts (the counts follow the other active filters, so a second tick shows what it adds); a column with no kind (or `text` / `string`) opens a contains-text field; numbers, dates, links and `format` columns get none. `columns[].filter` overrides per column: `\"values\"` or `\"text\"` (works without `filterable`, and is how a `format` column opts in), or `false` to opt out. Active filters show as removable pills above the table with Clear all. The state is client state at `{ \"$state\": \"/ui/<id>/filters\" }`, an object with one entry per column (`/ui/<id>/filters/<column>`): a string array for a list, a string for text; other elements can read it. It composes with `search` and `filters`: a row must pass all three. Below 768px the header menus become one Filters button above the card list. `id` is required (the validator checks it).\n- `clearState`: state paths the Table's Clear filters button and the pills' Clear all also reset, e.g. `[\"/ui/prSearch/value\"]` for the `SearchInput` feeding `search`. Only `/ui/<id>/...` paths of controls on the page. Without it, those controls keep their value and the no-match state only offers Clear filters for the built-in filters.\n- Loading and errors: the first load (no rows yet) shows a skeleton shaped like the table, with its header labels. `loading` (`/queries/<name>/loading`) is the first load only. Bind `refreshing` to `{ \"$state\": \"/queries/<name>/fetching\" }` (true during any fetch, including the 5s poll and `app.refresh`) and a refetch with rows showing runs a slim bar along the top edge, on phones too, and never dims, covers or blanks a row. A failed query shows the error callout with a Retry button; `onRetry` is the chain it runs (default `[{ \"action\": \"app.refresh\" }]`, which re-runs every query on the page). With rows already loaded the callout sits above the stale rows; with none, it is the whole state (no empty message). A search or filter that hides every row shows \"No rows match\" with a Clear filters button; with header filters the table stays in place (header and open filter input included) and the button sits under it.\n- Smart links, tooltips and popovers (Table, DetailList, CardGrid, Markdown):\n - A `link` cell (Table `kind: \"link\"`, DetailList and CardGrid `kind: \"link\"`) shows a chip with an icon and a short label when its value is a GitHub PR, issue, commit or repo URL (`agent-swarm#2605`, `agent-swarm@a1b2c3d`, `owner/repo`), the GitHub shorthand `owner/repo#N` or `owner/repo@sha`, a dashboard task, agent, session, app, page or workflow URL (shown by its name once the dashboard knows it, else `Task 1f6feea0`), or an agent-fs file. GitHub links open in a new tab; dashboard links stay in the app. Any other http(s) URL is a plain external link, and any other value is text. Only `github.com` links are GitHub links.\n - `href: \"<row field>\"` (Table column, DetailList or CardGrid field) takes the URL from another row field, so a cell can show one field and link with another: `{ \"key\": \"number\", \"label\": \"PR\", \"format\": \"{{repo}}#{{number}}\", \"href\": \"url\" }` shows `agent-swarm#2605` as a PR chip. With `href` the cell's own text (or `format`) is the label. `linkLabel: \"<template>\"` (same `{{field}}` rules as `format`) sets the label instead, e.g. `\"Lead review\"` on a `kind: \"link\"` column.\n - `hint: \"<text>\"` on a column adds a header tooltip. A header cut off by the column width also shows its full label in the tooltip, with no config.\n - `popover: { title?: \"<template>\", fields: [...], trigger?: \"hover\" | \"click\" }` on a Table column opens a popover from the cell that lists up to 12 fields of the row, in the DetailList field shape (`{ key, label?, kind?, tones?, href?, linkLabel? }`, any DetailList kind). It opens on hover or keyboard focus by default and lets the pointer move into it; `trigger: \"click\"` toggles it from the cell; on a cell with its own controls (link, copy, switch) it opens from a separate Details button beside the content. In the phone list, link columns render as chips under the row and each popover column gets a Details button that opens on tap. Use it for detail that does not fit a column, such as a merge reason or CI status. `key` and `href` must name model columns.\n- `onRowClick`: action chain with `$row` / `$rowIndex`, run when a row is clicked (or Enter on a focused cell). Pair it with `app.navigate` that sets a Drawer param, and bind `selectedId` to `{ \"$state\": \"/route/params/<param>\" }` so the open row stays highlighted. `rowId` names the id field (default `id`).\n- Phones (below 768px): the table renders as a card list. `mobileFields: { title, subtitle?, meta?: string or string[], status? }` picks the columns; by default the first text column is the title and the first `status`/`badge` column the chip. `mobile: \"scroll\"` keeps the grid; it is the default when the table has `rowActions` but no `onRowClick`. With `selectable`, each phone card gets a checkbox beside it and a Select all row sits above the list. An editable `checkbox` / `switch` column (one with `onChange`) becomes a real control beside the card, not a line of text.\n- `emptyState: { icon?, title, body? }` replaces the plain empty message. A search or filter that hides every row shows its own \"No rows match\" state.\n- `pagination`: boolean; defaults to auto-enabling past 200 rows (set `false` to force one scroll region). `density: \"compact\"` tightens row height for dense readouts.\n- `rowActions[]`: `{ label, variant?, icon?, placement?: \"inline\" or \"menu\", confirm?, actions }`. `placement: \"menu\"` moves the action into the row's More menu. Variants add `destructive-outline` to the Button variants. `destructive` and `destructive-outline` confirm by default; customize with `{ \"title\": ..., \"description\": ..., \"confirmLabel\": ... }`, or use a bare `confirm` string as the dialog description (use `confirm: false` only for a reversible action).\n- `search`: optional string; case-insensitive substring matching across the listed string and number columns. Bind a SearchInput value for client-side search.\n- `filters`: optional record of per-column string, number, boolean, null, or array values. An array means \"the cell is one of these\" (what a `multiple` Chips or Select writes). Null, empty strings, empty arrays, or absent values disable one filter. Bind Select or Chips values for client-side filters.\n\nKanban details:\n\n- One card per `data` row, grouped by the row's `columnField` value. `columns[]` are plain strings or `{ id, label? }`, in display order; rows matching no column are hidden.\n- `cardFields[]` uses the DetailList field shape (`{ key, label?, kind?, tones? }`, same kinds) for extra lines under the title.\n- `onMove` is an action chain run when a card is dropped in another column. `$row` is the moved row with `columnField` already set to the new column: `[{ \"action\": \"app.mutate\", \"params\": { \"model\": \"deal\", \"op\": \"update\", \"rowId\": { \"$row\": \"id\" }, \"values\": { \"stage\": { \"$row\": \"stage\" } } } }]`. Without `onMove`, cards cannot be dragged.\n- `onCardClick` is an action chain with `$row`; pair it with `app.navigate` and a `Drawer` to open a card.\n\nCalendar details:\n\n- `startField` / `endField` hold ISO dates, ISO datetimes, or epoch ms. An event shows on every day from start to end; without `endField` it shows on its start day.\n- Each Calendar keeps its own visible month (prev/next controls in its header). `onSelect` is an action chain with `$row`, run when an event is clicked.\n\nContributionGraph details:\n\n- Buckets `data` rows by the calendar day of `dateField` over the trailing `days`. Each row counts 1, or adds its numeric `countField` when set.\n\nTree details:\n\n- `nodes` is a doc-shaped value: `{ root: string | string[], elements: { <key>: { type, children?: string[] } } }`, the json-render flat element map. Usually bind it to a json column: `{ \"$state\": \"/queries/<name>/data/0/<column>\" }`. A malformed or absent value renders an empty state; a `children` key missing from `elements` shows as `key — ?`. Outlines are cut at 2,000 rows with a notice; branches deeper than 32 levels keep a disabled chevron.\n- Each row shows `key — type`. Clicking a row writes its key to `/ui/<id>/value`, and the row bound to that path renders selected; read the selection with `{ \"$state\": \"/ui/<id>/value\" }`. The Tree never writes `null`: when the selected key leaves the doc (a refetch, an edit) the stored key stays and no row renders selected. Selection and collapse are keyed by node key, so a key reachable through two parents selects and collapses in both places.\n- Rows scroll inside `maxHeight` (default `480px`). Set `fill: true` inside a `fill` Stack or Split pane to grow to that height instead and scroll within it (ignores `maxHeight`).\n\nFiles and File details:\n\n- Both read agent-fs as the viewer, with the viewer's own agent-fs key (the one Comb saves in their browser), from the swarm's default drive (`agent_fs.comb` in `/status`). There is no `drive` prop yet. The swarm key never reaches agent-fs, and the viewer sees only what their drive membership allows; an app cannot widen it.\n- A viewer who has not connected agent-fs sees a \"Connect agent-fs\" card that opens Comb's connect flow. In a `?mode=chromeless` iframe the card links to the app in the dashboard instead, because the iframe has no saved key.\n- `path` is absolute. A literal path must not contain `..`; bind it with `$state` to follow a route param. A folder that does not exist yet lists as empty (`emptyMessage`).\n- `Files` sorts folders first. `mode: \"browser\"` opens subfolders in place, with crumbs that never go above `path`, and reopens on the folder holding `selectedPath`. A file click (in list mode, any row) runs `onSelect` with `$row` = `{ path, name, type, size, modifiedAt }`; `type` is `file` or `directory`, and a folder's `path` ends with `/`. Usually: `[{ \"action\": \"app.navigate\", \"params\": { \"page\": \"docs\", \"params\": { \"file\": { \"$row\": \"path\" } } } }]`, plus `\"selectedPath\": { \"$state\": \"/route/params/file\" }`.\n- `File` renders Markdown with raw HTML shown as text, images as `<img>` (SVG too, so its scripts never run), PDFs in the browser's viewer, video and audio in a player, CSV as a table, and text files (HTML as source) as lines. Other types show Download and \"Open in agent-fs\". An empty `path` shows \"No file selected\".\n- List and view: a `Split` with `Files` in the left pane and `File` with `\"path\": { \"$state\": \"/route/params/file\" }` in the right; declare `file` in the page's `params`.\n- `upload: true` adds an Upload button and a drop zone over the list. Files upload with the viewer's key into the folder on screen (the opened subfolder in browser mode), create-only: a taken name asks Keep both or Skip. The list refreshes when a file lands. agent-fs's own upload limit applies.\n- Scripts: an `app.action` script runs as its owner agent, so `ctx.fs` `/afs` reads that agent's default drive, not the viewer's. It sees the same files only when the agent's default drive is the swarm's comb drive.\n\nDateRange and Timeline details:\n\n- `DateRange` writes inclusive `YYYY-MM-DD` dates (the viewer's local calendar) to `/ui/<id>/from` and `/ui/<id>/to`, and the active preset to `/ui/<id>/preset`. On first load it writes `defaultPreset` unless the state already holds a range. Bind query params with `{ \"$state\": \"/ui/<id>/from\" }` so the query refetches when the range changes. `7d` is today and the six days before it; `mtd` starts on the 1st. `custom` opens two date inputs in a popover; Apply needs both dates, from not after to. `id` must match `[A-Za-z0-9_-]+`, and `defaultPreset` must be one of `presets`.\n- `Timeline` reads `timeField` as an ISO date or epoch ms (rows that do not parse are left out), sorts newest first and groups under day headings: Today, Yesterday, then the date. Each event shows `titleField`, the time, `descriptionField` (two lines at most) and a `statusField` pill (`tones` maps value to tone; lifecycle values get the status chip). `icon` replaces the marker dot. `onSelect` runs with `$row` (the row) and `$rowIndex` (its index in `data`); without it events are not clickable.\n\nSchemaForm details:\n\n- `schema` is a JSON schema object held in state (usually `{ \"$state\": ... }`). Each entry of `properties` becomes one control: `type: \"boolean\"` a switch, `enum` of strings a select, `type: \"number\"` or `\"integer\"` a number input, anything else a text input. `description` is the tooltip. Fields seed from `value[key]`, else the property `default`. At most 100 fields and 200 enum options render. `id` must match `[A-Za-z0-9_-]+`. Rebinding `schema` resets the form.\n- Typing updates `/ui/<id>/value` with the draft object; switches and selects commit at once and text and number inputs commit on blur. Each commit runs `onChange` with `$form` = the draft.\n- Nested document editing: bind `baseDoc` to a doc-shaped value (`{ root, elements }`) and `nodeKey` to an element key, such as a Tree's `{ \"$state\": \"/ui/<tree>/value\" }`. The form then edits `baseDoc.elements[nodeKey].props`, and `/ui/<id>/value` holds the whole doc with the edit merged in, so one `app.mutate` with `values: { <jsonColumn>: { \"$state\": \"/ui/<id>/value\" } }` persists it. Props the schema does not list are kept. Edits the query has not returned yet stay applied, so two quick edits on different nodes both survive. A `nodeKey` that is not a key of `elements` falls back to plain mode, and a `baseDoc` over 5,000 elements is not editable. Typing writes `/ui/<id>/value` on every keystroke, before the commit on blur, so another component's `app.mutate` that reads that path can persist half-typed text; persist from the SchemaForm's own `onChange`.\n\nApproval details (human-in-the-loop):\n\n- `requestId` names one approval request, usually the id an `app.action` script returned: `{ \"$state\": \"/actions/<name>/result/requestId\" }`. An empty value renders nothing, so the element can sit on the page before the request exists.\n- While the request is pending, the card shows its questions with the dashboard's answer flow and polls every 5s; polling stops once it resolves. The viewer answers with their own credential, so the server records them and enforces the approvers list and RBAC.\n- A viewer whose role cannot answer, or whose answer the server refuses (not an approver), sees a read-only card with an \"Open in dashboard\" link. If the request was answered or expired meanwhile, the card refetches and shows that state instead of an error. With an `all` or `{ min: N }` policy, an answer that does not resolve it shows \"Your answer is recorded\".\n- `showResolved: false` shows only the outcome line after resolution, not the answers. `compact: true` drops the card chrome.\n- `onResolved` is an action chain run once, when the page sees the request leave `pending`. Its params may read `{ \"$chain\": \"status\" }` (`approved`, `rejected`, `timeout`, `cancelled`), `{ \"$chain\": \"responses\" }` (answers keyed by question id; `{ \"$chain\": \"responses/<questionId>\" }` reads one), and `{ \"$chain\": \"resolvedBy\" }`. A request that was already resolved when the page loaded does not run it, so a reload never repeats the follow-up. Use `onResolved`, not `on.resolved`: the validator rejects the latter.\n\nIn-session wait: the follow-up runs in the viewer's browser, so if they close the tab before the answer, nothing continues. The script behind the action creates the request detached and returns its id:\n\n```ts\nexport default async function run(args, ctx) {\n const res: any = await ctx.swarm.request_humanInput({\n title: `Deploy ${args.service}?`,\n questions: [{ id: \"go\", type: \"approval\", label: \"Ship it to production?\" }],\n detached: true,\n });\n return { requestId: res?.data?.requestId ?? res?.requestId };\n}\n```\n\n```json\n{\n \"askBtn\": { \"type\": \"Button\", \"props\": { \"label\": \"Request deploy\", \"busyWith\": \"requestDeploy\" },\n \"on\": { \"press\": { \"action\": \"app.action\", \"params\": { \"name\": \"requestDeploy\", \"input\": { \"service\": \"api\" } } } } },\n \"approve\": {\n \"type\": \"Approval\",\n \"props\": {\n \"requestId\": { \"$state\": \"/actions/requestDeploy/result/requestId\" },\n \"onResolved\": [\n { \"action\": \"app.action\", \"params\": { \"name\": \"applyDecision\",\n \"input\": { \"status\": { \"$chain\": \"status\" }, \"responses\": { \"$chain\": \"responses\" } } } },\n { \"action\": \"ui.toast\", \"params\": { \"message\": \"Decision applied\", \"tone\": \"success\" } }\n ]\n }\n }\n}\n```\n\nDurable wait: when the follow-up must run even if nobody watches the page, put it in a workflow whose human-in-the-loop node waits server-side, and use `Approval` only to answer. A script action starts the run with `ctx.swarm.workflow_trigger({ id, triggerData, wait: false })` and returns `runId`. The request appears once the run reaches its human-in-the-loop node, so a second script action (pressed from the page, or retried) finds it and returns its id: `ctx.swarm.db_query({ sql: \"SELECT id FROM approval_requests WHERE workflowRunId = ? AND status = 'pending' ORDER BY createdAt DESC LIMIT 1\", params: [args.runId] })`, then `{ requestId: res.data.rows[0]?.[0] }`. Bind `Approval.requestId` to that action's result. The workflow resumes on the answer whether or not the page is open.\n\nSessionThread details — a chat on an app page, one session per viewer and `sessionKey`:\n\n- `sessionKey` names the session, a plain token (`^[A-Za-z0-9_-]{1,128}$`): a literal such as `\"main\"`, or a `$state` binding to a token such as a route param or row id (`{ \"$state\": \"/route/params/itemId\" }`) for one session per item. No row stores the session: the server keys every task the thread's `app.action` creates as `task:app:<appId>:<sessionKey>:user:<viewer>`, and the thread shows the viewer's newest session with that key. A page can only write sessions of its own app.\n- `scope` is `\"user\"` (the default): each viewer has their own session per key. The viewer needs an identity; with none picked the composer is disabled. `scope: \"shared\"` (one session everyone on the page writes to) comes in a follow-up PR: the validator rejects it today. The planned design adds an everyone:write session share on the root when the server creates it.\n- It renders the same conversation as the dashboard's \"Session about this page\" panel: the session turn timeline (each person message with the sender's name, the swarm's replies with a live Queued / Working status, worker steps, approvals) and the shared composer. A person bubble shows the `message` of an app-action input instead of the whole agent prompt, cut at 4,000 characters. The composer's attachments and mic are off: a message is text only.\n- Sending a message takes one of three routes:\n 1. No session yet → run `onDispatch` with `$form = { message }` and `$chain = { leafTaskId: null, newTaskId: null }`. Its `app.action` creates the session's root task.\n 2. A task in the session is not finished → the composer steers the newest such task, on any agent, with `source: \"app-page\"`. It offers Queue, and Interrupt where the harness supports it. The server promotes a steer it cannot deliver into a follow-up task (source `ui`), and a toast says so.\n 3. Every task is finished (completed, failed, cancelled, superseded, skipped, or draft) → run `onDispatch` again with `$chain.leafTaskId` set to the newest task id, so `\"parentTaskId\": { \"$chain\": \"leafTaskId\" }` chains the new task under it. The follow-up keeps the session's key.\n- Each `app.action` step of `onDispatch` is sent with the session (`{ key, scope }`) and with `followUp: false` unless the step sets `followUp` itself, so the Lead adds no review task to the chain and each message stays one task. A Lead review that is in the chain anyway (a steer the server promoted to a task) is never steered or chained under.\n- \"New session\" (shown once a session exists) starts over: the next message creates a new root, and the thread shows only sessions created after the current one. Nothing is deleted; older sessions stay in the dashboard's Sessions list.\n- While the session loads, the composer is disabled with a loading notice. A session whose chain cannot be found blocks sending. After a send, the composer stays busy until the new task shows up, for at most 30 seconds.\n- Without `fill` the thread is 420 px tall; `fill: true` fills a `fill`-aware parent, and keeps at least 420 px on a phone, where a `Split` or `Grid` stacks its panes. Inside an element instance, `id` is namespaced per instance, so two instances keep separate drafts.\n\n```json\n{ \"type\": \"SessionThread\", \"props\": {\n \"id\": \"chat\",\n \"sessionKey\": { \"$state\": \"/route/params/screenId\" },\n \"onDispatch\": [{ \"action\": \"app.action\", \"params\": {\n \"name\": \"editScreen\", \"input\": { \"$form\": \"\" }, \"parentTaskId\": { \"$chain\": \"leafTaskId\" } } }]\n} }\n```\n\nPageFrame details — a live swarm Page inside the app, for a preview pane next to a `SessionThread`:\n\n- It renders the body `/pages/<pageId>` shows: an HTML page in a sandboxed iframe (scripts, forms and popups; never top navigation), a JSON page inline. The viewer can click and scroll it.\n- It checks the page every 3 s and reloads by itself when the page's `updatedAt` moves: a new version, a restore, a theme switch. A reload resets scroll and any state inside the page.\n- `pageId` is a page id (32 hex characters), usually bound: `{ \"$state\": \"/queries/project/data/0/pageId\" }`. A literal slug is rejected; an empty id shows \"No page selected\".\n- The viewer needs read access to the page: an authed page launches a page session for them, a password page asks for its password.\n- `device: \"mobile\"` centers a 390 px wide frame, so the page's own media queries see a phone. A JSON page follows the dashboard viewport instead. Switch devices with two `PageFrame`s in `Tabs`, or bind `device` to a `Select`.\n\n```json\n{ \"type\": \"PageFrame\", \"props\": {\n \"pageId\": { \"$state\": \"/queries/project/data/0/pageId\" },\n \"device\": { \"$state\": \"/ui/device/value\" },\n \"fill\": true\n} }\n```\n\nForm details:\n\n- `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, `enum`, or `file`, and enum fields need `options`.\n- `kind: \"file\"` adds `dir`, `accept` (e.g. `[\".pdf\", \"image/*\"]`), `multiple` and `source`: `\"upload\"` (default) chooses local files, `\"pick\"` opens a browser of `dir` (or `/`) to attach a file that already exists in agent-fs, `\"both\"` offers both. `dir` is an absolute agent-fs folder, required unless `source` is `\"pick\"`. Files use the viewer's own agent-fs key on the swarm's default drive, like `Files`.\n- On submit, chosen files upload first, create-only, to `<dir>/<timestamp>-<id>-<n>-<sanitized name>`: a random id per submit and a counter across all fields, so two fields or two submits never write the same path; then the chain runs. `$form.<name>` is the stored path, or an array of paths with `multiple: true`. An upload failure (the error shows agent-fs's text, e.g. its size limit) stops the chain and keeps the form's values. Without an agent-fs connection the field shows a \"Connect agent-fs\" card, and a required file field disables submit.\n- Values live at `/forms/<formId>/<fieldName>`. `onSubmit` is an action chain.\n- The submit button shows a pending spinner while the chain runs, and `app.mutate` failures in the chain render inline under the fields (not the page banner) — no extra wiring needed.\n\nDrawer details:\n\n- `param` must name a param declared on the containing page. The drawer is open exactly when `/route/params/<param>` has a non-empty value, so its open state survives refresh and is shareable. Its children mount only while open; closing it clears that param with history replacement.\n- `actions[]`: `{ label, variant?, icon?, confirm?, actions }`, rendered as buttons in a sticky footer under the scrolling body. Confirmation follows Table `rowActions`: destructive variants confirm by default, and a chain with an `app.mutate` delete always confirms. Chains have no `$row`; address the open record with `{ \"$state\": \"/route/params/<param>\" }`, for example `{ \"action\": \"app.mutate\", \"params\": { \"model\": \"order\", \"op\": \"delete\", \"rowId\": { \"$state\": \"/route/params/panel\" } } }`. Prev/next record navigation is not available.\n- `presentation: \"split\"` renders the Drawer as an inline right pane beside the page instead of a sheet over it. The page canvas shrinks while it is open; the pane has a draggable left edge (arrow keys, Shift for big steps, Home/End for the min/max, double-click or Enter to reset) and the viewer's width is kept per app in the browser. `size` sets its starting width (360/480/640/800px). Opening, closing, refresh and shared links work exactly as for the sheet. Below 768px it falls back to the sheet. At most one split Drawer per page; `side` does not apply.\n\nList + detail recipe (a row click opens the record beside the table):\n\n```json\n\"params\": { \"issue\": { \"kind\": \"string\" } },\n\"elements\": {\n \"root\": { \"type\": \"Stack\", \"props\": {}, \"children\": [\"table\", \"issue\"] },\n \"table\": { \"type\": \"Table\", \"props\": {\n \"data\": { \"$state\": \"/queries/issues/data\" },\n \"columns\": [{ \"key\": \"title\" }, { \"key\": \"status\", \"kind\": \"status\" }],\n \"selectedId\": { \"$state\": \"/route/params/issue\" },\n \"onRowClick\": [{ \"action\": \"app.navigate\", \"params\": { \"page\": \"main\", \"params\": { \"issue\": { \"$row\": \"id\" } } } }] } },\n \"issue\": { \"type\": \"Drawer\", \"props\": { \"param\": \"issue\", \"presentation\": \"split\", \"size\": \"md\", \"title\": \"Issue\" },\n \"children\": [\"issueDetail\"] },\n \"issueDetail\": { \"type\": \"DetailList\", \"props\": { \"data\": { \"$state\": \"/queries/issue/data/0\" }, \"fields\": [{ \"key\": \"title\" }] } }\n}\n```\n\nDetailList details:\n\n- `fields[]`: `{ key, label?, kind?, tones? }`. Kinds reuse Table formatting (`text`, `string`, `number`, `boolean`, `date`, `badge`, `enum`) and the Table cell renderers (`status`: lifecycle chip or `tones` pill; `user`: avatar plus name; `relative`: smart time, exact on hover; `copy`: value plus copy button; `link`: a smart link from the value, or from the row field named by `href`, with `linkLabel` as an optional label template), and add `code` for a monospace block and `json` for a collapsible JSON tree (objects, or a string holding JSON). `currency` and `percent` (with `currency?: \"<ISO 4217>\"`) format numbers like the Table kinds. Bind `data` to one record, commonly `/queries/<detailQuery>/data/0`.\n\nMotion details:\n\n- Every `Stack` fades its direct children in and lifts them 4px over 200ms on first paint, staggered 30ms (capped at the 10th child). It never replays on the 5s data poll. A Stack nested inside another one does not add its own entrance. `motion: \"fade\"` drops the lift; `motion: \"none\"` turns it off. Viewers with reduced motion get a 150ms fade.\n\nCardGrid details — the visual counterpart to Table for record browsers (projects, documents, media):\n\n- `titleKey` (required) picks the row field shown as the card title (an object value shows a JSON preview; titles are capped at 500 characters).\n- `imageKey` (optional) picks a row field holding an absolute http(s) image URL and adds an image tile to every card. When it is set, a non-URL value, a missing value, or a failed load shows a placeholder tile. Omit it for text-only cards with no tile.\n- `fields[]`: `{ key, kind?, tones?, href?, linkLabel? }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge` (with `tones`), `link` (a smart link, with `href` / `linkLabel`), or `json` (no `label`, no `format`). A field with no `kind` whose value is an object renders like `json`. They render as an unlabeled `·`-joined meta line under the title, e.g. a `date` field for \"created\" and a `text` field for the author.\n- `columns`: same responsive shorthand as `Grid.columns` (default `{ \"base\": 1, \"sm\": 2, \"md\": 3 }`).\n- `onClick`: an action chain with `$row` / `$rowIndex`, run when a card is clicked or activated with Enter or Space. Commonly `app.navigate` into a detail page, the CardGrid equivalent of Table's `onRowClick`.\n- Bind `data` / `loading` / `error` to a named query like Table. Loading shows skeleton cards, an error shows a callout, and no rows shows `emptyMessage`.\n- It renders 200 cards at a time with a Show more button below the grid that reveals the next 200.\n\nShortcut details:\n\n- `Button.shortcut` and `SearchInput.shortcut` are one key. Letters and digits match without Shift; symbols such as `/` and `?` match as typed. They do nothing while focus is in a text field, while Ctrl, Cmd, or Alt is held, or while a dialog or menu is open (unless the control is inside it, such as a Button in an open Drawer).\n\n## Layout & interactivity\n\nFor a multi-page app that should feel like a product (a sidebar of pages, a sticky title bar with actions), set `layout: \"sidebar\"` (see Pages, routes, and page trees) instead of building navigation out of Tabs or button rows. Pair `Metric` tiles (with `sparkline`) in a `Grid` with `Chart`s inside `Card`s for dashboards.\n\nUse `Stack` as the primary page and section layout; `Container` is the legacy two-prop primitive retained for existing pages. Stack supports vertical or horizontal flow, shared spacing, alignment, justification, wrapping, and padding; row Stacks (filter bars, button rows) should set `collapseBelow: \"sm\"|\"md\"|\"lg\"` so they stack vertically on phones. Use `Grid` for responsive card or metric strips: a bare column count is responsive shorthand (1 column on phones, 2 from `sm`, the count from `md` up), or pin breakpoints explicitly with `{ \"base\": 1, \"md\": 2, \"lg\": 3 }`. `Grid` and `Split` also accept `padding` on the shared spacing scale.\n\n`Stack` and `Split` size to their content by default, so a page scrolls as a whole. Set `fill: true` to make one grow to fill the remaining height of a `fill`-aware parent (another `fill` Stack or Split) instead; chain it from the page root down through every container on the path to the element that should scroll, and that element scrolls within whatever height is left while the page itself does not. A non-`fill` sibling (a toolbar, a header) keeps its natural height and the `fill` sibling absorbs the rest. A `fill` Split stretches both panes to the full row height, so nesting a `fill` Split inside one pane of another `fill` Split is the way to build a three-or-more column viewport-height layout (`ratio` is only ever two panes).\n\n`Split` and `Tabs` children are positional. For Split, `children[0]` is the first pane, `children[1]` is the second, and extra children append inside the second pane. Below `collapseBelow`, panes stack; `reverse` changes only that narrow-layout stacking order. For Tabs, `children[i]` is the body for `tabs[i]`; keep both arrays in the same order and with the same count. Inactive tab children stay mounted but hidden, so Tables keep polling. Use `Divider` to separate sections and `Markdown` for richer explanatory content.\n\nSearchInput, Select, NumberInput, Chips, and Tree are client-side controls: each needs a literal `id` and writes state under `/ui/<id>/value` (Tree writes the clicked node key; a `selectable` Table writes its selected row ids to `/ui/<id>/selected`); Tabs writes its active key to `/ui/<id>/tab`. Bind those values into a Table's `search` and `filters` props. This filters already-polled rows locally; it does not alter or re-run the named query.\n\n```json\n{\n \"filters\": { \"type\": \"Stack\", \"props\": { \"gap\": \"sm\" }, \"children\": [\"query\", \"status\"] },\n \"query\": { \"type\": \"SearchInput\", \"props\": { \"id\": \"ideaSearch\", \"placeholder\": \"Search ideas\" } },\n \"status\": { \"type\": \"Select\", \"props\": { \"id\": \"ideaStatus\", \"options\": [\"open\", \"done\"] } },\n \"ideas\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIdeas/data\" },\n \"columns\": [{ \"key\": \"title\" }, { \"key\": \"status\" }],\n \"search\": { \"$state\": \"/ui/ideaSearch/value\" },\n \"filters\": { \"status\": { \"$state\": \"/ui/ideaStatus/value\" } }\n }\n }\n}\n```\n\n`visible` accepts a boolean, a `$state` truthiness binding, comparisons, and logical groups. Put exactly one comparison key in each condition object. The renderer evaluates the first matching key in fixed priority order (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`; otherwise truthiness), so additional comparison keys in the same object are ignored. Use `$and` / `$or` arrays to combine conditions. `not` is a negation FLAG inside a condition object (`\"not\": true`), never a wrapper around one — `{ \"not\": { \"$state\": … } }` is invalid and the validator rejects it. The absent-record pattern (e.g. an alert when a detail query matched nothing) is `{ \"$state\": \"/queries/<q>/data/0/id\", \"not\": true }`:\n\n```json\n[\n { \"$state\": \"/route/params/issueId\", \"gt\": 0 },\n {\n \"$and\": [\n { \"$state\": \"/route/page\", \"eq\": \"detail\" },\n { \"$state\": \"/route/params/panel\", \"neq\": \"hidden\" }\n ]\n }\n]\n```\n\n## Bindings, sentinels, and action chains\n\nUse this exact query binding shape; do not invent `$query`, `$item`, or template strings:\n\n```json\n{\n \"data\": { \"$state\": \"/queries/allIdeas/data\" },\n \"loading\": { \"$state\": \"/queries/allIdeas/loading\" },\n \"error\": { \"$state\": \"/queries/allIdeas/error\" }\n}\n```\n\nValid `$state` roots are:\n\n- `/queries/<declaredQuery>/...`\n- `/forms/<formId>/...`, where a `Form` element has that literal `props.id`\n- `/ui/<id>/...`, where a SearchInput, Select, Chips, or Tabs element has that literal `props.id` (SearchInput, Select, and Chips use `/value`; Tabs uses `/tab`)\n- `/actions/<declaredAction>/...`\n- `/route/page` for the active page name\n- `/route/params/<declaredParam>` for a param declared on the current page\n\n`/route` is mirrored as `{ page, params }`. Only declared params appear. Values are coerced by their declared kind: `number` becomes a number when possible; boolean strings `true`/`1` become true; failed number coercion remains the raw string.\n\nOnly inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `Table.bulkActions[].actions`, `Form.onSubmit`, or a component chain prop such as `Approval.onResolved` or `SessionThread.onDispatch`) these scoped sentinels are valid, recursively inside objects and arrays:\n\n| Sentinel | Resolves to |\n|---|---|\n| `{ \"$row\": \"id\" }` | Current Table row's `id`; another column name selects that field. |\n| `{ \"$row\": \"\" }` | Entire current Table row. |\n| `{ \"$rowIndex\": true }` | Current Table row index. |\n| `{ \"$form\": \"title\" }` | One current Form value. |\n| `{ \"$form\": \"\" }` | All current Form values. |\n| `{ \"$state\": \"/queries/allIdeas/data\" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |\n| `{ \"$chain\": \"leafTaskId\" }` | One chain-scope value, published by the component that runs the chain: a task chain (`SessionThread`) carries `leafTaskId` and `newTaskId`; `Approval.onResolved` carries `status`, `responses` and `resolvedBy`; `Form.onSubmit` carries `createdRowId` (the row its newest `app.mutate` create step made). The component publishes every key, `null` when it has no value yet; a `null` key resolves to nothing and its param is dropped (a `parentTaskId` bound to a `null` `leafTaskId` creates a root task). Where no chain scope is published (Table), or the key is not one the scope carries (a typo), the sentinel is left in place and the action fails instead of silently dropping the parent. An empty string is not \"no parent\": a `$state` slot meaning \"no parent yet\" must hold `null`. |\n| `{ \"$chain\": \"\" }` | The whole chain scope. |\n\nEach sentinel object must contain exactly the single key shown.\n\nAn action-chain step is `{ \"action\": \"<type>\", \"params\": {...} }`. Available action types:\n\n- `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `\"create\"`, `\"update\"`, or `\"delete\"`. `update`/`delete` require `rowId` (usually `{ \"$row\": \"id\" }`, or `{ \"$state\": \"/route/params/<param>\" }` in a Drawer footer); literal `values` keys must be model columns. Successful mutation refetches all queries on that model. In a `Form.onSubmit` chain, steps after a `create` read the new row's id as `{ \"$chain\": \"createdRowId\" }`, e.g. to navigate to the new row (not `$state`: the renderer resolves a chain's `$state` reads when the form renders, before the row exists).\n- `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.\n- `app.action`: `{ name, input?, parentTaskId?, followUp? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { \"$row\": \"\" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ \"$chain\": \"leafTaskId\" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400. `followUp: false` creates the task with no Lead follow-up (the review task the Lead adds when a worker task finishes); script and sync actions ignore it. A task an action creates is attributed to the viewer's identity. `session: { key, scope? }` keys a task-kind action's task into the viewer's `SessionThread` session for that key; the server builds the key, never the page. SessionThread sets it on its own `onDispatch` steps (replacing any value there). Any other chain can set it to start a session: `key` is a literal plain token (validated like `sessionKey`) or a binding; a key that does not resolve to a token fails the step instead of creating a task outside the session, `scope: \"shared\"` is rejected, and a session step defaults to `followUp: false`. Example, a create form that sends the idea as the chat's first message:\n\n```json\n\"onSubmit\": [\n { \"action\": \"app.mutate\", \"params\": { \"model\": \"project\", \"op\": \"create\", \"values\": { \"name\": { \"$form\": \"name\" } } } },\n { \"action\": \"app.action\", \"params\": { \"name\": \"build\", \"input\": { \"message\": { \"$form\": \"idea\" } }, \"session\": { \"key\": { \"$chain\": \"createdRowId\" } } } },\n { \"action\": \"app.navigate\", \"params\": { \"page\": \"studio\", \"params\": { \"projectId\": { \"$chain\": \"createdRowId\" } } } }\n]\n```\n\nThe `studio` page's `SessionThread` with `\"sessionKey\": { \"$state\": \"/route/params/projectId\" }` then shows the idea as its first message and the running task, with no second send.\n- `app.navigate`: `{ page, params? }`; `page` must be declared, supplied keys must be params of the target page, and every required target param must be supplied. `params` replace the current route params wholesale and may contain action sentinels. Navigation pushes history, so browser Back returns to the previous page/params; only `mode` is preserved automatically.\n- `ui.toast`: `{ message, description?, tone?, undo? }`, where `tone` is `\"success\"`, `\"error\"`, `\"info\"` (default), or `\"warning\"`. `undo: { label?, actions }` adds an Undo button (default label `Undo`) that runs `actions` as a chain; its steps are validated like any chain. Put it after the step it confirms, e.g. a row delete followed by `{ \"action\": \"ui.toast\", \"params\": { \"message\": \"Order deleted\", \"undo\": { \"actions\": [{ \"action\": \"app.mutate\", \"params\": { \"model\": \"order\", \"op\": \"create\", \"values\": { \"title\": { \"$row\": \"title\" } } } }] } } }`. Undo params resolve `$state` when Undo is pressed; `$row` / `$form` resolve when the toast is shown.\n- `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.\n- `swarm.call`: `{ method, endpoint: \"/api/...\", body? }`, where `method` is `\"GET\"`, `\"POST\"`, `\"PUT\"`, `\"DELETE\"`, or `\"PATCH\"`; raw authenticated API call.\n\nA failed step halts its chain: when `app.action`, `app.mutate`, `swarm.sdk` or `swarm.call` fails (a thrown error, a script action that returns `ok: false`, a non-2xx `swarm.call`), the steps after it do not run and the error shows as an error toast. A step's `onError` (`{ set }` or `{ action }`) runs first, and the chain still halts. So a `ui.toast` after a write is a real success message. A `Form`'s failed `app.mutate` shows inline under the fields instead of a toast. A task-backed `app.action` succeeds once the task is created; the task's own failure shows in the page banner and does not halt the chain. A Table bulk action reads each step's own outcome, as before.\n\n## Patch semantics\n\n`app-patch.definition` is RFC 7396 JSON Merge Patch applied to the stored definition:\n\n- omitted keys stay unchanged;\n- object keys merge recursively;\n- arrays and scalar values replace;\n- `null` deletes a key;\n- reusable-element disambiguation: a patch value for `elements.<name>` containing ONLY the `elements` key merges node-by-node; any other key present (`mode`, `root`, `props`, or `export`) makes it a full element replace — restate every field you want kept. In that node-by-node form, `elements.<name>.elements.<id>: null` deletes one node. Literal null nodes are rejected in a full element replace so they cannot be mistaken for deletions.\n- otherwise every supplied `pages.<page>.elements.<id>`, `pages.<page>.params.<param>`, `actions.<name>`, `models.<name>.columns.<col>`, and `models.<name>.sources.<src>` value is atomic and replaces that complete declaration; `null` deletes it (deleting a source detaches its rows — see the source lifecycle above).\n\n`pages.<page>: null` deletes a page, except the current `defaultPage` cannot be deleted. `root`, `title`, and top-level `defaultPage` use ordinary merge semantics. A top-level `page` patch is rejected with guidance to patch `pages.<name>` instead.\n\nBecause elements, param declarations, actions, and columns are atomic, include the complete desired object when changing one. For example, changing only a Table's `emptyMessage` requires sending its full `{ \"type\": \"Table\", \"props\": ... }` element. The merged result is validated as a whole; on failure, read `issues[]`, correct the paths, and retry without assuming anything was written.\n\n```json\n{\n \"appId\": \"<app-id>\",\n \"description\": null,\n \"definition\": {\n \"models\": {\n \"idea\": {\n \"columns\": {\n \"priority\": { \"kind\": \"enum\", \"enum\": [\"low\", \"high\"], \"default\": \"low\" }\n }\n }\n },\n \"queries\": { \"openIdeas\": null },\n \"pages\": {\n \"main\": {\n \"elements\": {\n \"title\": { \"type\": \"Heading\", \"props\": { \"text\": \"Prioritized ideas\", \"level\": \"h1\" } }\n }\n }\n }\n }\n}\n```\n\n## Worked example: ideas tracker\n\nCreate this with `app-upsert`:\n\n```json\n{\n \"name\": \"Ideas Tracker\",\n \"description\": \"Collect and manage product ideas\",\n \"definition\": {\n \"models\": {\n \"idea\": {\n \"columns\": {\n \"title\": { \"kind\": \"string\", \"required\": true },\n \"status\": { \"kind\": \"enum\", \"enum\": [\"open\", \"done\"], \"default\": \"open\" }\n }\n }\n },\n \"queries\": {\n \"allIdeas\": { \"model\": \"idea\", \"sort\": { \"column\": \"createdAt\", \"dir\": \"desc\" } }\n },\n \"actions\": {\n \"triage\": { \"kind\": \"task\", \"prompt\": \"Review current ideas and recommend the next one to pursue\" }\n },\n \"pages\": {\n \"main\": {\n \"root\": \"root\",\n \"elements\": {\n \"root\": {\n \"type\": \"Container\",\n \"props\": { \"direction\": \"column\", \"gap\": \"lg\" },\n \"children\": [\"heading\", \"formCard\", \"ideasCard\", \"triage\"]\n },\n \"heading\": { \"type\": \"Heading\", \"props\": { \"text\": \"Ideas\", \"level\": \"h1\" } },\n \"formCard\": {\n \"type\": \"Card\",\n \"props\": { \"title\": \"Add an idea\" },\n \"children\": [\"ideaForm\"]\n },\n \"ideaForm\": {\n \"type\": \"Form\",\n \"props\": {\n \"id\": \"newIdea\",\n \"fields\": [{ \"name\": \"title\", \"label\": \"Title\", \"required\": true }],\n \"submitLabel\": \"Add\",\n \"onSubmit\": [{\n \"action\": \"app.mutate\",\n \"params\": { \"model\": \"idea\", \"op\": \"create\", \"values\": { \"$form\": \"\" } }\n }]\n }\n },\n \"ideasCard\": {\n \"type\": \"Card\",\n \"props\": { \"title\": \"All ideas\" },\n \"children\": [\"ideasTable\"]\n },\n \"ideasTable\": {\n \"type\": \"Table\",\n \"props\": {\n \"data\": { \"$state\": \"/queries/allIdeas/data\" },\n \"loading\": { \"$state\": \"/queries/allIdeas/loading\" },\n \"error\": { \"$state\": \"/queries/allIdeas/error\" },\n \"columns\": [\n { \"key\": \"title\", \"label\": \"Title\" },\n { \"key\": \"status\", \"label\": \"Status\", \"kind\": \"badge\", \"tones\": { \"open\": \"info\", \"done\": \"success\" } }\n ],\n \"rowActions\": [{\n \"label\": \"Delete\",\n \"variant\": \"destructive-outline\",\n \"actions\": [{ \"action\": \"app.mutate\", \"params\": { \"model\": \"idea\", \"op\": \"delete\", \"rowId\": { \"$row\": \"id\" } } }]\n }]\n }\n },\n \"triage\": {\n \"type\": \"Button\",\n \"props\": { \"label\": \"Ask swarm to triage\", \"variant\": \"secondary\" },\n \"on\": { \"press\": [{ \"action\": \"app.action\", \"params\": { \"name\": \"triage\" } }] }\n }\n }\n }\n },\n \"defaultPage\": \"main\"\n }\n}\n```\n\nThe tool returns `{ appId, url: \"/apps/<id>\" }`. Open that URL to verify the live UI, then continue with the read-patch-validate loop above.\n\n## View and screenshot a live app\n\n- An app renders at `<dashboard>/apps/<id>`. Two view modes are set by query string: `?mode=full` (full-viewport overlay with a slim header) and `?mode=chromeless` (only the rendered page, the embed surface). `app.navigate` keeps only `?mode`.\n- Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the \"Who are you?\" dialog.\n- Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.\n- App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.\n- Follow-up edit to a live app: list in the brief the control numbers the edit must not move, and assert them from the backing script before publishing. Take a signed-in screenshot of each changed selector at 1440px wide, save the shots to agent-fs, critique, and repeat at least 3 times. If the backing script caches results, bump its version or force a fresh run so the shots show new data.\n\n\n### Rows from agents and scripts\n\nEvery row tool requires `appId` and `model`. Scripts use underscore names, such as `ctx.swarm.app_row_create` and `ctx.swarm.app_rows_list`.\nResults use the usual `data` wrapper, so scripts read `res?.data ?? res`. Rows contain system fields and declared columns at the top level.\nWrites record `agent:<agentId>` in `createdBy` and `updatedBy`. Source projections and join keys remain read-only. Each row input must fit within 1 MiB.\n\n`app-rows-list` accepts `equals`, `sort: \"<column>:asc|desc\"`, and `limit` from 1 to 1000 (default 200).\nEquality filters accept declared columns and system columns. Filter values must match the column kind and use strict equality.\n`app-rows-delete` requires at least one equality filter and accepts a limit from 1 to 1000 (default 1000).\n\n`app-action-run` returns the REST action body under `data`. Script actions run with the script owner's identity and receive the verified invoking agent as `caller`.\nScripts and extensions cannot invoke `app-action-run`.\n";
14948
15120
 
14949
15121
  // templates/skills/ask-user/config.json
14950
15122
  var config_default3 = `{
@@ -20459,6 +20631,7 @@ Fetch the page as markdown: \`curl -fsSL https://docs.agent-swarm.dev/llms.mdx/d
20459
20631
 
20460
20632
  - [Choosing an AI operating model](https://docs.agent-swarm.dev/docs/guides/choosing-an-ai-operating-model). Reference.
20461
20633
  - [Small tech team operating model](https://docs.agent-swarm.dev/docs/guides/small-tech-team-operating-model). Reference.
20634
+ - [Customer renewal review](https://docs.agent-swarm.dev/docs/guides/customer-renewal-review). Reference.
20462
20635
  - [Deployment Guide](https://docs.agent-swarm.dev/docs/guides/deployment). When: Someone wants to run Agent Swarm on their own server with Docker Compose.
20463
20636
  - [One-click deploy](https://docs.agent-swarm.dev/docs/guides/one-click-deploy). When: Someone has no server yet and wants Agent Swarm running in the cloud with HTTPS.
20464
20637
  - [Kubernetes and Helm](https://docs.agent-swarm.dev/docs/guides/kubernetes). When: Someone wants to install Agent Swarm on Kubernetes.
@@ -20507,6 +20680,7 @@ Fetch the page as markdown: \`curl -fsSL https://docs.agent-swarm.dev/llms.mdx/d
20507
20680
  - [Multi-runtime agents](https://docs.agent-swarm.dev/docs/guides/multi-runtime-agents). Reference.
20508
20681
  - [Runtime pools (beta)](https://docs.agent-swarm.dev/docs/guides/runtime-pools). Reference.
20509
20682
  - [boxd runtime provider](https://docs.agent-swarm.dev/docs/guides/boxd-runtime-provider). Reference.
20683
+ - [Reviewing customer help content for conflicts with AI agents](https://docs.agent-swarm.dev/docs/guides/support-knowledge-conflict-review). Reference.
20510
20684
 
20511
20685
  ## Other docs
20512
20686
 
@@ -21506,8 +21680,161 @@ Before finalizing any TDD plan, verify:
21506
21680
  6. **No Speculative Code**: Don't add code "because we'll need it later"
21507
21681
  `;
21508
21682
 
21509
- // templates/skills/v-implementing/config.json
21683
+ // templates/skills/ui-spec/config.json
21510
21684
  var config_default50 = `{
21685
+ "kind": "skill",
21686
+ "name": "ui-spec",
21687
+ "displayName": "UI spec cards",
21688
+ "slug": "ui-spec",
21689
+ "title": "UI spec cards",
21690
+ "description": "Attach a rich card to a task result with the \`store-progress\` input \`uiSpec\`: a json-render spec for the chat catalog that renders in the Slack outcome card, the session view and Chat SDK channels. Covers the 12 components and their props, when to make a card and when not to, the caps and their Slack reasons, the https rule, buttons, the lead rule for worker specs, and 2 complete examples.",
21691
+ "version": "1.0.0",
21692
+ "category": "skills",
21693
+ "placeholders": [],
21694
+ "runAllSeedersCandidate": true,
21695
+ "systemDefault": true,
21696
+ "tags": ["ui-spec", "json-render", "cards", "slack", "visuals"]
21697
+ }
21698
+ `;
21699
+
21700
+ // templates/skills/ui-spec/content.md
21701
+ var content_default50 = `# UI spec cards
21702
+
21703
+ A task result can carry a rich card next to the prose answer. You attach it with the \`store-progress\` input \`uiSpec\` when you complete the task. The card renders in the Slack outcome card, in the session view, on the task page and in Chat SDK channels. Surfaces that show only text (Linear, Jira, the legacy Slack card, Slack Work Objects) get the card's fallback text.
21704
+
21705
+ The card is on only when the operator sets \`UI_SPEC_ENABLED=true\`. When the "Rich cards" section is in your system prompt, the flag is on.
21706
+
21707
+ ## When to make a card
21708
+
21709
+ Make a card in 2 cases:
21710
+
21711
+ - The requester asks for a visual, a chart, a table, a dashboard or a summary card.
21712
+ - The result holds numbers that compare, a series over time, shares of a whole, or records with the same fields.
21713
+
21714
+ Do not make a card for:
21715
+
21716
+ - a one-line answer;
21717
+ - a yes or no;
21718
+ - a status reply;
21719
+ - a delegation;
21720
+ - a result that is prose only.
21721
+
21722
+ ## \`output\` stays the prose answer
21723
+
21724
+ \`output\` stays the complete answer in prose. The card adds to it and never replaces it. A reader who sees only the text must get the full answer.
21725
+
21726
+ ## The shape of \`uiSpec\`
21727
+
21728
+ \`\`\`json
21729
+ {
21730
+ "spec": { "root": "<element id>", "elements": { "<element id>": { "type": "...", "props": {}, "children": [] } } },
21731
+ "actions": { "<action id>": { "kind": "follow_up", "prompt": "..." } }
21732
+ }
21733
+ \`\`\`
21734
+
21735
+ - \`spec.root\` names the root element. The root must be a \`Card\`.
21736
+ - \`spec.elements\` is a flat map. Each element has \`type\`, \`props\` and \`children\` (a list of element ids). Give \`children: []\` to a leaf.
21737
+ - \`actions\` is optional. It is for \`Button\` only (see "Buttons").
21738
+
21739
+ ## The 12 components
21740
+
21741
+ | Component | Props | Children |
21742
+ |---|---|---|
21743
+ | \`Card\` | \`title\`, \`subtitle\`, \`imageUrl\` (all optional) | Any. The root of every spec. \`title\` renders as the header. |
21744
+ | \`Section\` | none | Groups related elements. |
21745
+ | \`Text\` | \`content\` (markdown, required), \`style\`: \`plain\`, \`bold\` or \`muted\` | none. Use \`muted\` for footnotes and the source line. |
21746
+ | \`Fields\` | none | \`Field\` elements only. A grid of label and value pairs. |
21747
+ | \`Field\` | \`label\`, \`value\` (string or number) | none. Good for KPIs. |
21748
+ | \`Table\` | \`headers\` (string list), \`rows\` (list of lists of strings or numbers), \`align\` (\`left\`, \`center\`, \`right\` per column), \`caption\` | none. Every row has one cell per header. Right-align numeric columns. |
21749
+ | \`Chart\` | \`title\` (required), \`chart\` | none. See below. |
21750
+ | \`Divider\` | none | none. A separator between groups. |
21751
+ | \`Image\` | \`url\` (https), \`alt\` (required) | none. |
21752
+ | \`Actions\` | none | \`Button\` and \`LinkButton\` elements. A row of buttons. |
21753
+ | \`Button\` | \`id\`, \`label\`, \`style\`: \`primary\`, \`danger\` or \`default\`, \`value\` | none. Needs \`UI_SPEC_ACTIONS_ENABLED\`. |
21754
+ | \`LinkButton\` | \`label\`, \`url\` (https) | none. Opens the URL. |
21755
+
21756
+ \`Chart.chart\` has one of 2 forms:
21757
+
21758
+ - Pie, for shares of a whole: \`{ "type": "pie", "segments": [{ "label": "Enterprise", "value": 52 }] }\`. Each \`value\` is positive.
21759
+ - Series, for values over categories: \`{ "type": "bar" | "line" | "area", "categories": ["Jan", "Feb"], "series": [{ "name": "Revenue", "values": [1.02, 1.08] }], "xLabel": "...", "yLabel": "..." }\`. Each series has one value per category. \`xLabel\` and \`yLabel\` are optional.
21760
+
21761
+ Chart titles stay at 50 characters or fewer. Chart labels stay at 20 characters or fewer.
21762
+
21763
+ ## Caps
21764
+
21765
+ The engine checks every spec when you store it. It refuses a spec that breaks a cap and tells you which one. Fix the spec and call \`store-progress\` again.
21766
+
21767
+ | Cap | Reason |
21768
+ |---|---|
21769
+ | At most 2 charts | Slack renders a chart as a native \`data_visualization\` block, and Slack allows 2 of them per message. A 3rd number series goes in \`Fields\` or in the table. |
21770
+ | At most 1 table, of at most 100 rows and 20 columns | Slack renders 1 native table (\`data_table\`) per message. Above 100 rows or 20 columns, the Slack adapter falls back to ASCII text. |
21771
+ | A Slack table shows 5 rows per page | The native Slack table pages 5 rows at a time, with a pager. You cannot change the page size. Put the most important rows first. |
21772
+ | 32 KiB | The JSON of \`spec\` is at most 32,768 bytes. |
21773
+ | 45 Slack blocks, 25 elements in one \`Actions\` row | Slack Block Kit limits for one message. |
21774
+ | At most 25 entries in \`actions\` | Each \`script\` action is checked against the allowlist when the card is stored. |
21775
+ | https URLs only | \`LinkButton.url\`, \`Image.url\` and \`Card.imageUrl\` must start with \`https:\`. The engine refuses \`http:\`, \`javascript:\`, \`data:\` and \`file:\` URLs. |
21776
+
21777
+ ## Buttons
21778
+
21779
+ A \`Button\` needs \`UI_SPEC_ACTIONS_ENABLED=true\`. When that flag is off, the engine refuses a spec with a \`Button\`. Use \`LinkButton\` instead.
21780
+
21781
+ When the flag is on, each \`Button.props.id\` matches \`^[a-z][a-z0-9_]{0,39}$\` and names a key of \`uiSpec.actions\`. An action is one of:
21782
+
21783
+ - \`{ "kind": "follow_up", "prompt": "<at most 4000 characters>" }\`: a click starts one Lead task with the prompt. It runs once.
21784
+ - \`{ "kind": "script", "script": "<global script name>", "args": { ... } }\`: a click re-runs the script with these frozen args (at most 4 KB, checked against the script's args schema) and replaces the card with its result. No Lead task. The requester can click again after a 30-second cooldown.
21785
+
21786
+ A \`script\` action needs the script pinned in \`UI_SPEC_SCRIPT_ACTIONS\` (\`name@<contentHash prefix>\`). Only a human admin can pin one; an edited script stays refused until it is re-pinned. The script returns \`{ spec, actions? }\`, the same shape as \`uiSpec\`. When it omits \`actions\`, the stored actions carry over, so a Refresh button keeps working. Put an "Updated HH:MM" \`Text\` in the card so readers can tell when it ran.
21787
+
21788
+ ## Which card a Slack thread shows
21789
+
21790
+ A Slack card shows only the spec of its own task.
21791
+
21792
+ - A worker's spec shows on the worker's own task (session view, task page). It does not show on the lead's Slack ask card.
21793
+ - Lead rule: when a worker returns a spec that the requester must see, send that spec again in your own \`uiSpec\` when you complete the Slack ask.
21794
+
21795
+ ## Example: a small card
21796
+
21797
+ A KPI, a table and a link button.
21798
+
21799
+ \`\`\`json
21800
+ {"spec":{"root":"c","elements":{
21801
+ "c":{"type":"Card","props":{"title":"Weekly deploys"},"children":["f","t","a"]},
21802
+ "f":{"type":"Fields","props":{},"children":["k"]},
21803
+ "k":{"type":"Field","props":{"label":"Deploys","value":"1,284"},"children":[]},
21804
+ "t":{"type":"Table","props":{"headers":["Service","Deploys"],"rows":[["api",812],["ui",472]]},"children":[]},
21805
+ "a":{"type":"Actions","props":{},"children":["l"]},
21806
+ "l":{"type":"LinkButton","props":{"label":"Open dashboard","url":"https://example.com/deploys"},"children":[]}}}}
21807
+ \`\`\`
21808
+
21809
+ ## Example: a dashboard card
21810
+
21811
+ KPIs, 2 charts, a table and 2 rows of link buttons. The 3rd share ("Revenue by plan") is a bold \`Text\`, not a 3rd chart, because of the 2-chart cap.
21812
+
21813
+ \`\`\`json
21814
+ {"spec":{"root":"c","elements":{
21815
+ "c":{"type":"Card","props":{"title":"Q3 revenue at a glance"},"children":["a1","f","ch1","ch2","t1","tb","a2","src"]},
21816
+ "a1":{"type":"Actions","props":{},"children":["view"]},
21817
+ "view":{"type":"LinkButton","props":{"label":"View report","url":"https://example.com/q3"},"children":[]},
21818
+ "f":{"type":"Fields","props":{},"children":["f1","f2","f3","f4","f5","f6"]},
21819
+ "f1":{"type":"Field","props":{"label":"Revenue","value":"$4.2M (+18%)"},"children":[]},
21820
+ "f2":{"type":"Field","props":{"label":"New customers","value":"64"},"children":[]},
21821
+ "f3":{"type":"Field","props":{"label":"ARR","value":"$16.8M (+12%)"},"children":[]},
21822
+ "f4":{"type":"Field","props":{"label":"Avg deal","value":"$65.6K"},"children":[]},
21823
+ "f5":{"type":"Field","props":{"label":"Net retention","value":"118%"},"children":[]},
21824
+ "f6":{"type":"Field","props":{"label":"Win rate","value":"31%"},"children":[]},
21825
+ "ch1":{"type":"Chart","props":{"title":"Monthly revenue (2026, USD M)","chart":{"type":"line","categories":["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep"],"series":[{"name":"Revenue","values":[1.02,1.08,1.15,1.2,1.26,1.31,1.38,1.45,1.52]}]}},"children":[]},
21826
+ "ch2":{"type":"Chart","props":{"title":"Revenue by region (Q3, USD M)","chart":{"type":"bar","categories":["NA","EMEA","APAC","LATAM"],"series":[{"name":"Revenue","values":[1.7,1.3,0.8,0.4]}]}},"children":[]},
21827
+ "t1":{"type":"Text","props":{"content":"Revenue by plan: Enterprise 52%, Team 31%, Self-serve 17%","style":"bold"},"children":[]},
21828
+ "tb":{"type":"Table","props":{"headers":["Account","Region","Revenue","QoQ"],"rows":[["Halcyon Labs","NA","$412K","+22%"],["Brightline","EMEA","$356K","+31%"],["Kestrel Health","EMEA","$298K","+27%"],["Meridian Freight","APAC","$241K","+9%"]],"align":["left","left","right","right"],"caption":"Top accounts this quarter"},"children":[]},
21829
+ "a2":{"type":"Actions","props":{},"children":["open","csv"]},
21830
+ "open":{"type":"LinkButton","props":{"label":"Open dashboard","url":"https://example.com/dashboard"},"children":[]},
21831
+ "csv":{"type":"LinkButton","props":{"label":"Export CSV","url":"https://example.com/q3.csv"},"children":[]},
21832
+ "src":{"type":"Text","props":{"content":"Source: billing warehouse · Updated 2:41 PM","style":"muted"},"children":[]}}}}
21833
+ \`\`\`
21834
+ `;
21835
+
21836
+ // templates/skills/v-implementing/config.json
21837
+ var config_default51 = `{
21511
21838
  "category": "skills",
21512
21839
  "description": "Parallel DAG-plan implementation skill. Reads a v-planning plan directory (root.md + step-<n>.md files), topologically schedules ready steps, and fans them out as parallel sub-agents. Use whenever the user invokes /v-implement, points at a plan directory produced by /v-plan, or asks to \\"run the parallel plan\\", \\"implement the DAG\\", or \\"fan out the steps\\" — even without those exact words. For linear plans (single .md file), use \`implementing\` instead.",
21513
21840
  "displayName": "V-Implementing",
@@ -21528,10 +21855,10 @@ var config_default50 = `{
21528
21855
  `;
21529
21856
 
21530
21857
  // templates/skills/v-implementing/content.md
21531
- var content_default50 = "# v-implementing\n\nYou are implementing an approved DAG-structured plan produced by `v-planning`. The plan is a directory with `root.md` + one `step-<n>.md` per node. Your job is to act as a **topological scheduler**: at each tick, find steps whose dependencies are all done, fan them out as parallel sub-agents (one per ready step), wait, repeat — until the DAG is drained. Then run Global Verification.\n\nThis is the parallel sibling of `implementing`. The orchestration model is the same (sub-agents do the work, main session coordinates), only the scheduler is different.\n\n## Working Agreement\n\n**All user-facing questions go through `AskUserQuestion`** — see `desplega:ask-user` for conventions. Never ask in chat as plain bullets.\n\n**All read/research/validation work goes through sub-agents** — keep raw tool output out of the main session. Default to `run_in_background: true`. The fan-out scheduler below is built on this.\n\nThe autonomy mode (below) controls how often you check in. AskUserQuestion is always the mechanism.\n\nFile-review is on by default — when significant changes land in a step (or wave), invoke `/file-review:file-review <path>` for inline feedback (skip only if Autopilot).\n\n## Autonomy Mode\n\n| Mode | Behavior |\n|------|----------|\n| **Autopilot** | Drain the DAG without pausing. Only stop on blocker / failed step. |\n| **Critical** (Default) | Pause when each *wave* of parallel steps completes; wait for manual verification before unlocking the next wave. |\n| **Verbose** | Pause after each individual step (even within a wave). |\n\n## Initial Setup Questions\n\nAfter understanding the plan and before the scheduler loop starts, gather implementation-specific details (skip in Autopilot):\n\n### 1. Branch / Worktree Setup\n\nCheck the current branch: `git branch --show-current`. Then check if the `wts` plugin is installed (look for `wts:wts` in available skills).\n\n**If wts is installed**, use **AskUserQuestion**:\n\n| Question | Options |\n|----------|---------|\n| \"You're on `<current-branch>`. Where would you like to implement?\" | 1. Continue on current branch, 2. Create a new branch, 3. Create a wts worktree |\n\n**If wts is not installed**, drop the worktree option.\n\n### 2. Commit Strategy\n\nUse **AskUserQuestion**:\n\n| Question | Options |\n|----------|---------|\n| \"How would you like to handle commits during parallel implementation?\" | 1. Commit after each step completes (Recommended), 2. Commit at the end (single commit), 3. Let me decide as I go |\n\nIf \"Commit after each step\" is selected, after a step's manual verification passes, create a commit: `[step-N] <step name>`.\n\n### 3. Orchestration Mode (only if the `Workflow` tool is available)\n\n| Question | Options |\n|----------|---------|\n| \"Run the DAG waves as Workflow scripts? (deterministic scheduling, parallel steps as agent() calls)\" | 1. Yes — Workflow waves, 2. No — Agent fan-out (Default) |\n\nA \"yes\" is the explicit opt-in the Workflow tool requires. If opted in, each wave of the scheduler loop below runs as one Workflow script — a `parallel()` of `agent()` calls, one per ready step, with `model`/`effort` per `desplega:delegate-work`. Everything else is unchanged: step agents still follow the `step-running` contract (atomic frontmatter claim, three-bucket verification), and autonomy-mode pause points sit **between** Workflow invocations, never inside one. In Autopilot these questions are skipped, so there is no opt-in — use Agent fan-out unless the user pre-authorized workflows.\n\n### 4. Code Review Mode\n\n| Question | Options |\n|----------|---------|\n| \"Run an automatic code review after each wave?\" | 1. Automatic two-axis review per wave (Recommended), 2. Only at the end (single review after the DAG drains), 3. Off — I'll review myself |\n\nIn **Autopilot**, skip the question and default to automatic per-wave review.\n\n## Getting Started\n\nGiven a plan directory path:\n\n1. **Read `root.md` fully** (no `limit`/`offset`). Capture: Overview, Current State, Desired End State, Implementation Approach, Global Verification.\n2. **Read every `step-<n>.md`'s frontmatter** to build the dependency graph (`id`, `depends_on`). You don't need to read step bodies up front — the sub-agents will do that.\n3. **Validate the DAG:**\n - No cycles\n - Every `depends_on` ID exists as a step file\n - At least one step has `depends_on: []` (otherwise nothing can start)\n4. **Set `root.md` frontmatter `status: in-progress`.**\n5. **Build a TodoWrite list** with one entry per step, marked `pending`.\n6. **Resume support:** if any step's body has `- [x]` boxes already (or its frontmatter says `status: completed` if the user added it), trust them and treat that step as `done`.\n\nIf no path given, ask via AskUserQuestion.\n\n## The Scheduler Loop\n\nThe scheduler reads each step's frontmatter `status` (`ready` | `claimed` | `done`) and `depends_on`. The frontmatter `status` field is the **single source of truth** — multiple orchestrator instances on the same plan dir coordinate through it (each `desplega:step-running` sub-agent atomically claims its step before doing work).\n\n```\nwhile any step has status != done:\n ready = [step for step in steps\n if step.status == \"ready\"\n and all(dep.status == \"done\" for dep in step.depends_on)]\n if not ready:\n # DAG drained, OR every remaining undone step is claimed by another worker\n if any step has status == claimed: wait for in-flight claims to resolve\n else: report stuck (likely cycle or unrecoverable failure)\n continue\n fan out each step in `ready` as a parallel `desplega:step-running` sub-agent\n wait for the wave to complete\n review reports; step-running has already updated frontmatter\n (status: done on success, status: ready on retry-able failure, status: claimed if held for investigation)\n if Critical mode: pause for manual verification of newly-completed steps\n if any failed: stop and ask user how to proceed\n```\n\n### Spawning a Step Sub-agent\n\nUse the `Agent` tool with `run_in_background: true`, invoking `desplega:step-running`. Pass:\n\n- **Step path**: full path to `step-<n>.md`\n- **Plan dir**: full path to the parent plan directory\n- **Agent ID**: unique ID for this sub-agent (e.g. orchestrator session ID + step ID + timestamp). step-running uses this for atomic claim + stale-claim detection.\n- **Plan-level context** (optional): a quick brief from `root.md`. step-running re-reads `root.md` itself, so this is just to reduce round-trips.\n\n`step-running` owns:\n- Atomic claim (rewrite frontmatter `status: ready` → `status: claimed, assignee: <agent-id>, claimed_at: <ts>`)\n- Three-bucket verification (Automated Verification, Automated QA, QA Doc identification)\n- Terminal status transition (`status: done` on success, `status: ready` on retry-able failure)\n- Reporting back\n\nThe orchestrator does NOT do step work itself — it delegates. See `desplega:step-running` for the full sub-agent contract.\n\n**Executor routing**: if the `desplega:delegate-work` skill is available, pick each step's executor per its routing matrix instead of defaulting to a `step-running` sub-agent — a step may route to a Codex variant (one worktree per parallel slice) or a specific Claude model tier. Only the executor choice changes; the scheduler, frontmatter claim protocol, and all other semantics here stay unchanged. When a step routes to Codex, the orchestrator owns the frontmatter bookkeeping that `step-running` would normally do (Codex must not edit plan files).\n\n### Wave Completion\n\nWhen a wave finishes:\n1. **Review each agent's report.** Mark steps `done` only if `completed` was reported.\n2. **Run the wave code review** (unless review mode is Off) — invoke `desplega:code-reviewing` on the wave's combined diff: Standards + Spec axes as parallel background sub-agents (routed per `desplega:delegate-work`), spec source = the completed steps' bodies and Success Criteria. Critical findings block those steps' commits — fix and re-verify first. If \"Only at the end\" was selected, run one review over the full diff after the DAG drains instead.\n3. **Handle `QA Doc: <path>`** — for each step that reported a QA doc, invoke `desplega:qa` against that path. The Automated QA bucket inside the step is already handled by the sub-agent; only the linked doc needs separate orchestration here. (`QA: n/a` → proceed normally.)\n4. **Manual verification (if not Autopilot)** — present manual verification items from each completed step's body. Wait for user confirmation. Don't tick manual boxes until confirmed.\n5. **Commits (if commit-per-step was selected)** — after a step's manual verification passes, create a commit: `[step-N] <step name>`.\n6. **Loop** — recompute `ready` and start the next wave.\n\n## Handling Failures and Mismatches\n\nIf a sub-agent reports `failed` or `blocked`, or you spot a mismatch between plan and reality:\n\n| Question | Options |\n|----------|---------|\n| \"[step-N] [issue]. How should I proceed?\" | 1. Adapt step (edit step-N.md and retry), 2. Retry as-is, 3. Skip and continue (mark step blocked), 4. Stop the run |\n\nIn Autopilot mode, use best judgment, document the decision in the step file, and continue if non-fatal.\n\n## After the DAG Drains\n\nWhen every step is `done`:\n\n1. Run **Global Verification** from `root.md`. Tick automated checks; surface manual checks to the user.\n2. Set `root.md` frontmatter `status: completed`.\n3. Offer post-implementation auditing: \"Would you like me to run `/verify-plan` and `/review` on the plan directory?\"\n4. If commit-per-step was off, offer to create a single bundled commit now.\n5. If the work ships as a GitHub PR: once review comments land, address them with `desplega:tackle-gh-comments` (fetch threads, verify each claim, fix, reply, resolve — push last).\n\n## Important Guidelines\n\n1. **One step = one sub-agent.** Don't bundle steps into a single agent even if they're in the same wave — fan-out is the whole point.\n2. **Plan-level context goes to every sub-agent.** Sibling step bodies do not.\n3. **The DAG is canonical via step frontmatter** — if `root.md`'s table is out of sync, trust the frontmatter.\n4. **Resume works step-granular.** If the user re-runs `/v-implement` mid-DAG, completed steps stay completed; only undone ones rerun.\n5. **Don't tick manual checkboxes** until the user confirms — automated boxes can be ticked by the sub-agent or the orchestrator.\n\n## Review Integration\n\nIf `file-review` is available and the user opted in:\n- After each step's significant code changes, invoke `/file-review:file-review <changed-file>`.\n- Process feedback with `file-review:process-review` before treating the step as done.\n- Skip in Autopilot.\n";
21858
+ var content_default51 = "# v-implementing\n\nYou are implementing an approved DAG-structured plan produced by `v-planning`. The plan is a directory with `root.md` + one `step-<n>.md` per node. Your job is to act as a **topological scheduler**: at each tick, find steps whose dependencies are all done, fan them out as parallel sub-agents (one per ready step), wait, repeat — until the DAG is drained. Then run Global Verification.\n\nThis is the parallel sibling of `implementing`. The orchestration model is the same (sub-agents do the work, main session coordinates), only the scheduler is different.\n\n## Working Agreement\n\n**All user-facing questions go through `AskUserQuestion`** — see `desplega:ask-user` for conventions. Never ask in chat as plain bullets.\n\n**All read/research/validation work goes through sub-agents** — keep raw tool output out of the main session. Default to `run_in_background: true`. The fan-out scheduler below is built on this.\n\nThe autonomy mode (below) controls how often you check in. AskUserQuestion is always the mechanism.\n\nFile-review is on by default — when significant changes land in a step (or wave), invoke `/file-review:file-review <path>` for inline feedback (skip only if Autopilot).\n\n## Autonomy Mode\n\n| Mode | Behavior |\n|------|----------|\n| **Autopilot** | Drain the DAG without pausing. Only stop on blocker / failed step. |\n| **Critical** (Default) | Pause when each *wave* of parallel steps completes; wait for manual verification before unlocking the next wave. |\n| **Verbose** | Pause after each individual step (even within a wave). |\n\n## Initial Setup Questions\n\nAfter understanding the plan and before the scheduler loop starts, gather implementation-specific details (skip in Autopilot):\n\n### 1. Branch / Worktree Setup\n\nCheck the current branch: `git branch --show-current`. Then check if the `wts` plugin is installed (look for `wts:wts` in available skills).\n\n**If wts is installed**, use **AskUserQuestion**:\n\n| Question | Options |\n|----------|---------|\n| \"You're on `<current-branch>`. Where would you like to implement?\" | 1. Continue on current branch, 2. Create a new branch, 3. Create a wts worktree |\n\n**If wts is not installed**, drop the worktree option.\n\n### 2. Commit Strategy\n\nUse **AskUserQuestion**:\n\n| Question | Options |\n|----------|---------|\n| \"How would you like to handle commits during parallel implementation?\" | 1. Commit after each step completes (Recommended), 2. Commit at the end (single commit), 3. Let me decide as I go |\n\nIf \"Commit after each step\" is selected, after a step's manual verification passes, create a commit: `[step-N] <step name>`.\n\n### 3. Orchestration Mode (only if the `Workflow` tool is available)\n\n| Question | Options |\n|----------|---------|\n| \"Run the DAG waves as Workflow scripts? (deterministic scheduling, parallel steps as agent() calls)\" | 1. Yes — Workflow waves, 2. No — Agent fan-out (Default) |\n\nA \"yes\" is the explicit opt-in the Workflow tool requires. If opted in, each wave of the scheduler loop below runs as one Workflow script — a `parallel()` of `agent()` calls, one per ready step, with `model`/`effort` per `desplega:delegate-work`. Everything else is unchanged: step agents still follow the `step-running` contract (atomic frontmatter claim, three-bucket verification), and autonomy-mode pause points sit **between** Workflow invocations, never inside one. In Autopilot these questions are skipped, so there is no opt-in — use Agent fan-out unless the user pre-authorized workflows.\n\n### 4. Code Review Mode\n\n| Question | Options |\n|----------|---------|\n| \"Run an automatic code review after each wave?\" | 1. Automatic two-axis review per wave (Recommended), 2. Only at the end (single review after the DAG drains), 3. Off — I'll review myself |\n\nIn **Autopilot**, skip the question and default to automatic per-wave review.\n\n## Getting Started\n\nGiven a plan directory path:\n\n1. **Read `root.md` fully** (no `limit`/`offset`). Capture: Overview, Current State, Desired End State, Implementation Approach, Global Verification.\n2. **Read every `step-<n>.md`'s frontmatter** to build the dependency graph (`id`, `depends_on`). You don't need to read step bodies up front — the sub-agents will do that.\n3. **Validate the DAG:**\n - No cycles\n - Every `depends_on` ID exists as a step file\n - At least one step has `depends_on: []` (otherwise nothing can start)\n4. **Set `root.md` frontmatter `status: in-progress`.**\n5. **Build a TodoWrite list** with one entry per step, marked `pending`.\n6. **Resume support:** if any step's body has `- [x]` boxes already (or its frontmatter says `status: completed` if the user added it), trust them and treat that step as `done`.\n\nIf no path given, ask via AskUserQuestion.\n\n## The Scheduler Loop\n\nThe scheduler reads each step's frontmatter `status` (`ready` | `claimed` | `done`) and `depends_on`. The frontmatter `status` field is the **single source of truth** — multiple orchestrator instances on the same plan dir coordinate through it (each `desplega:step-running` sub-agent atomically claims its step before doing work).\n\n```\nwhile any step has status != done:\n ready = [step for step in steps\n if step.status == \"ready\"\n and all(dep.status == \"done\" for dep in step.depends_on)]\n if not ready:\n # DAG drained, OR every remaining undone step is claimed by another worker\n if any step has status == claimed: wait for in-flight claims to resolve\n else: report stuck (likely cycle or unrecoverable failure)\n continue\n fan out each step in `ready` as a parallel `desplega:step-running` sub-agent\n wait for the wave to complete\n review reports; step-running has already updated frontmatter\n (status: done on success, status: ready on retry-able failure, status: claimed if held for investigation)\n if Critical mode: pause for manual verification of newly-completed steps\n if any failed: stop and ask user how to proceed\n```\n\n### Spawning a Step Sub-agent\n\nUse the `Agent` tool with `run_in_background: true`, invoking `desplega:step-running`. Pass:\n\n- **Step path**: full path to `step-<n>.md`\n- **Plan dir**: full path to the parent plan directory\n- **Agent ID**: unique ID for this sub-agent (e.g. orchestrator session ID + step ID + timestamp). step-running uses this for atomic claim + stale-claim detection.\n- **Plan-level context** (optional): a quick brief from `root.md`. step-running re-reads `root.md` itself, so this is just to reduce round-trips.\n\n`step-running` owns:\n- Atomic claim (rewrite frontmatter `status: ready` → `status: claimed, assignee: <agent-id>, claimed_at: <ts>`)\n- Three-bucket verification (Automated Verification, Automated QA, QA Doc identification)\n- Terminal status transition (`status: done` on success, `status: ready` on retry-able failure)\n- Reporting back\n\nThe orchestrator does NOT do step work itself — it delegates. See `desplega:step-running` for the full sub-agent contract.\n\n**Executor routing**: if the `desplega:delegate-work` skill is available, pick each step's executor per its routing matrix instead of defaulting to a `step-running` sub-agent — a step may route to a Codex variant (one worktree per parallel slice) or a specific Claude model tier. Only the executor choice changes; the scheduler, frontmatter claim protocol, and all other semantics here stay unchanged. When a step routes to Codex, the orchestrator owns the frontmatter bookkeeping that `step-running` would normally do (Codex must not edit plan files).\n\n### Wave Completion\n\nWhen a wave finishes:\n1. **Review each agent's report.** Mark steps `done` only if `completed` was reported.\n2. **Run the wave code review** (unless review mode is Off) — invoke `desplega:code-reviewing` on the wave's combined diff: Standards + Spec axes as parallel background sub-agents (routed per `desplega:delegate-work`), spec source = the completed steps' bodies and Success Criteria. Critical findings block those steps' commits — fix and re-verify first. If \"Only at the end\" was selected, run one review over the full diff after the DAG drains instead.\n3. **Handle `QA Doc: <path>`** — for each step that reported a QA doc, invoke `desplega:qa` against that path. The Automated QA bucket inside the step is already handled by the sub-agent; only the linked doc needs separate orchestration here. (`QA: n/a` → proceed normally.)\n4. **Manual verification (if not Autopilot)** — present manual verification items from each completed step's body. Wait for user confirmation. Don't tick manual boxes until confirmed.\n5. **Commits (if commit-per-step was selected)** — after a step's manual verification passes, create a commit: `[step-N] <step name>`.\n6. **Loop** — recompute `ready` and start the next wave.\n\n## Handling Failures and Mismatches\n\nIf a sub-agent reports `failed` or `blocked`, or you spot a mismatch between plan and reality:\n\n| Question | Options |\n|----------|---------|\n| \"[step-N] [issue]. How should I proceed?\" | 1. Adapt step (edit step-N.md and retry), 2. Retry as-is, 3. Skip and continue (mark step blocked), 4. Stop the run |\n\nIn Autopilot mode, use best judgment, document the decision in the step file, and continue if non-fatal.\n\n## After the DAG Drains\n\nWhen every step is `done`:\n\n1. Run **Global Verification** from `root.md`. Tick automated checks; surface manual checks to the user.\n2. Set `root.md` frontmatter `status: completed`.\n3. Offer post-implementation auditing: \"Would you like me to run `/verify-plan` and `/review` on the plan directory?\"\n4. If commit-per-step was off, offer to create a single bundled commit now.\n5. If the work ships as a GitHub PR: once review comments land, address them with `desplega:tackle-gh-comments` (fetch threads, verify each claim, fix, reply, resolve — push last).\n\n## Important Guidelines\n\n1. **One step = one sub-agent.** Don't bundle steps into a single agent even if they're in the same wave — fan-out is the whole point.\n2. **Plan-level context goes to every sub-agent.** Sibling step bodies do not.\n3. **The DAG is canonical via step frontmatter** — if `root.md`'s table is out of sync, trust the frontmatter.\n4. **Resume works step-granular.** If the user re-runs `/v-implement` mid-DAG, completed steps stay completed; only undone ones rerun.\n5. **Don't tick manual checkboxes** until the user confirms — automated boxes can be ticked by the sub-agent or the orchestrator.\n\n## Review Integration\n\nIf `file-review` is available and the user opted in:\n- After each step's significant code changes, invoke `/file-review:file-review <changed-file>`.\n- Process feedback with `file-review:process-review` before treating the step as done.\n- Skip in Autopilot.\n";
21532
21859
 
21533
21860
  // templates/skills/v-planning/config.json
21534
- var config_default51 = `{
21861
+ var config_default52 = `{
21535
21862
  "category": "skills",
21536
21863
  "description": "Vertical / parallel implementation planning skill. Creates DAG-structured plan directories where each step is an independent, QA-able vertical slice that sub-agents can pick up and implement in parallel. Use whenever the user wants a plan that fans out (multiple independent features), invokes /v-plan, or asks for a \\"parallel plan\\", \\"DAG plan\\", \\"vertical plan\\", or \\"plan that can be parallelized\\" — even if they don't say those exact words. Prefer the linear \`planning\` skill for strictly sequential work.",
21537
21864
  "displayName": "V-Planning",
@@ -21552,7 +21879,7 @@ var config_default51 = `{
21552
21879
  `;
21553
21880
 
21554
21881
  // templates/skills/v-planning/content.md
21555
- var content_default51 = `# v-planning
21882
+ var content_default52 = `# v-planning
21556
21883
 
21557
21884
  You create implementation plans as a **DAG of vertical steps** — each step a complete, QA-able slice of value (DB + API + UI + tests for one feature). The DAG captures feature-level dependencies, so independent steps can be implemented in parallel by sub-agents.
21558
21885
 
@@ -21643,7 +21970,7 @@ Structure validation runs automatically (rule 9, Haiku sub-agent).
21643
21970
  `;
21644
21971
 
21645
21972
  // templates/skills/verifying/config.json
21646
- var config_default52 = `{
21973
+ var config_default53 = `{
21647
21974
  "category": "skills",
21648
21975
  "description": "Post-implementation plan verification. Cross-references plans against actual changes for completeness and accuracy.",
21649
21976
  "displayName": "Verifying",
@@ -21664,7 +21991,7 @@ var config_default52 = `{
21664
21991
  `;
21665
21992
 
21666
21993
  // templates/skills/verifying/content.md
21667
- var content_default52 = `# Verifying
21994
+ var content_default53 = `# Verifying
21668
21995
 
21669
21996
  You are performing a post-implementation audit of a plan, cross-referencing it against actual changes to ensure nothing was missed, nothing is stale, and the implementation matches what was planned.
21670
21997
 
@@ -21812,7 +22139,7 @@ File-review is on by default (unless Autopilot):
21812
22139
  `;
21813
22140
 
21814
22141
  // templates/skills/work-on-task/config.json
21815
- var config_default53 = `{
22142
+ var config_default54 = `{
21816
22143
  "kind": "skill",
21817
22144
  "name": "work-on-task",
21818
22145
  "displayName": "Work On Task",
@@ -21829,10 +22156,10 @@ var config_default53 = `{
21829
22156
  `;
21830
22157
 
21831
22158
  // templates/skills/work-on-task/content.md
21832
- var content_default53 = '# Working on a task\n\nThe taskId follows the command. Without one, call `get-tasks` with `mineOnly: true` and take your `pending` or `in_progress` task. If there is none, say so and stop.\n\nThis message carries the task text, its attachments, its output format, and memories from past sessions. If it does not (you invoked this command yourself, or the context was compacted), run the `task-context-gathering` script with the taskId.\n\nWhen the task names a skill (`researching`, `planning`, `implementing`), use it. Otherwise work directly.\n\nFinish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.\n\nA lesson that would change how the next agent works goes in `learning` on that last `store-progress` call: line 1 a title, line 2 the rule ("When X, do Y"), then evidence. Leave it out for a status line, a restatement of the output, or text already in a skill.\n\nResuming (a resume task, or work cut by a graceful shutdown): read the parent\'s last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief\'s agent-fs output path and the task attachments. Read the parent task\'s output and any agent-fs draft path it names before rewriting. Run `agent-fs ls` on that path, download any partial and extend it; a superseded parent with empty output and no draft means a rebuild, not an extension. Then list the task\'s local work directory: a shutdown can leave the newest draft only there, or leave cache files half-written. Parse every cache file, delete the ones that fail, and re-run only the stages whose output is missing. Before re-running a collection, call `list-script-runs` with your `agentId` and reuse the output (`get-script-run`) of each completed run that started after the parent task started. Never re-run collection steps that already produced artifacts. A render task (video, image, generated page) has no branch either: its live state is the local project directory plus the brief\'s agent-fs output. List both; timestamps are hints only. Before reusing an output, verify that it exists, is complete and valid, and corresponds to the current sources and render settings (for example, using recorded input/settings hashes). Download remote output and verify its bytes and provenance; agent-fs listing dates alone do not establish freshness. Re-render missing, invalid, incomplete or stale output. Hand over the file link from the Outputs section of your system prompt (the dashboard when configured) by default. Use a share link only when the requester asked for one or the reader has no agent-fs login: then reuse a usable one, and create a missing one or replace an expired, revoked or view-exhausted one without re-rendering a valid unchanged output. A task that covers several PRs re-reads every PR in scope (state, mergedAt, head SHA), not only the first: a PR that merged during the shutdown takes no more pushes. If your task\'s `model` differs from the parent\'s, say so in the output, because the result\'s provenance changed.\n\nWrite times in replies, outputs and defer notes in the requester\'s timezone when the Requester Profile names one, never raw UTC.\n\nIf the user interrupts, follow their instructions. To resume, call `/work-on-task <taskId>` again.\n';
22159
+ var content_default54 = '# Working on a task\n\nThe taskId follows the command. Without one, call `get-tasks` with `mineOnly: true` and take your `pending` or `in_progress` task. If there is none, say so and stop.\n\nThis message carries the task text, its attachments, its output format, and memories from past sessions. If it does not (you invoked this command yourself, or the context was compacted), run the `task-context-gathering` script with the taskId.\n\nWhen the task names a skill (`researching`, `planning`, `implementing`), use it. Otherwise work directly.\n\nFinish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.\n\nA lesson that would change how the next agent works goes in `learning` on that last `store-progress` call: line 1 a title, line 2 the rule ("When X, do Y"), then evidence. Leave it out for a status line, a restatement of the output, or text already in a skill.\n\nResuming (a resume task, or work cut by a graceful shutdown): read the parent\'s last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief\'s agent-fs output path and the task attachments. Read the parent task\'s output and any agent-fs draft path it names before rewriting. Run `agent-fs ls` on that path, download any partial and extend it; a superseded parent with empty output and no draft means a rebuild, not an extension. Then list the task\'s local work directory: a shutdown can leave the newest draft only there, or leave cache files half-written. Parse every cache file, delete the ones that fail, and re-run only the stages whose output is missing. Before re-running a collection, call `list-script-runs` with your `agentId` and reuse the output (`get-script-run`) of each completed run that started after the parent task started. Never re-run collection steps that already produced artifacts. A render task (video, image, generated page) has no branch either: its live state is the local project directory plus the brief\'s agent-fs output. List both; timestamps are hints only. Before reusing an output, verify that it exists, is complete and valid, and corresponds to the current sources and render settings (for example, using recorded input/settings hashes). Download remote output and verify its bytes and provenance; agent-fs listing dates alone do not establish freshness. Re-render missing, invalid, incomplete or stale output. Hand over the file link from the Outputs section of your system prompt (the dashboard when configured) by default. Use a share link only when the requester asked for one or the reader has no agent-fs login: then reuse a usable one, and create a missing one or replace an expired, revoked or view-exhausted one without re-rendering a valid unchanged output. A task that covers several PRs re-reads every PR in scope (state, mergedAt, head SHA), not only the first: a PR that merged during the shutdown takes no more pushes. If your task\'s `model` differs from the parent\'s, say so in the output, because the result\'s provenance changed.\n\nWrite times in replies, outputs and defer notes in the requester\'s timezone when the Requester Profile names one, never raw UTC.\n\nIf the user interrupts, follow their instructions. To resume, call `/work-on-task <taskId>` again.\n';
21833
22160
 
21834
22161
  // templates/skills/workflow-iterate/config.json
21835
- var config_default54 = `{
22162
+ var config_default55 = `{
21836
22163
  "kind": "skill",
21837
22164
  "name": "workflow-iterate",
21838
22165
  "displayName": "Workflow Iteration",
@@ -21854,7 +22181,7 @@ var config_default54 = `{
21854
22181
  `;
21855
22182
 
21856
22183
  // templates/skills/workflow-iterate/content.md
21857
- var content_default54 = `# Workflow Iteration
22184
+ var content_default55 = `# Workflow Iteration
21858
22185
 
21859
22186
  Use this skill when you need to change an existing workflow without breaking live runs. The goal is to make small, verified revisions: inspect the current workflow, diagnose the failing step, patch only the required node or edge, trigger a realistic run, and keep iterating until the run reaches the intended terminal state.
21860
22187
 
@@ -22128,7 +22455,7 @@ The same rules apply to a standalone \`request-human-input\` call.
22128
22455
  `;
22129
22456
 
22130
22457
  // templates/skills/workflow-structured-output/config.json
22131
- var config_default55 = `{
22458
+ var config_default56 = `{
22132
22459
  "kind": "skill",
22133
22460
  "name": "workflow-structured-output",
22134
22461
  "displayName": "Workflow Structured Output",
@@ -22145,10 +22472,10 @@ var config_default55 = `{
22145
22472
  `;
22146
22473
 
22147
22474
  // templates/skills/workflow-structured-output/content.md
22148
- var content_default55 = '# Workflow Structured Output\n\n> **Companion skill — `workflow-iterate` (author-side).** This skill is for *workers* assigned a task spawned by an `agent-task` workflow node with an `outputSchema`. The author-side counterpart `workflow-iterate` covers how the workflow defines that schema, why gates downstream depend on it, and how to debug failed runs. If you ever need to understand *why* a particular schema is shaped the way it is — or you\'re switching from worker to author mode — read `workflow-iterate`.\n\n## Failure reason → fix (read this first)\n\nIf you see this failure reason on a task, the fix is always the same:\n\n| failureReason contains | What it means | Fix |\n|---|---|---|\n| `Task has an outputSchema but no output was provided` | You called `store-progress` without an `output` when the task required a JSON object matching `outputSchema` | Re-call `store-progress` with `status: "completed"` and `output` = a **stringified JSON** matching the schema exactly |\n| `Task output must be valid JSON` / `Task output does not match the outputSchema` | You passed invalid JSON, omitted required fields, or used the wrong types | Re-read the schema, include every `required` field with the exact key names, re-call `store-progress` |\n\n**You can re-call `store-progress` even after a rejection.** Your prior progress updates do not count as the final output. Fix the JSON and try again.\n\n## Pre-flight checklist (run through before calling store-progress)\n\n1. **Do the task details contain an actual `outputSchema`?** If yes, runtime\n enforcement is active: continue with that exact schema.\n2. **If there is no `outputSchema`, does the user provide an explicit JSON Output\n Format or interface?** Honor it as the requested output contract even though\n the runner is not enforcing an `outputSchema`.\n3. **Are workflow origin or tags such as `deterministic`, `litmus`, `validation`,\n or `context` the only signals?** They are heuristics only. Re-read the task\n details for an actual schema or explicit format. If neither exists, do not\n invent one; plain-text output is allowed.\n4. **Can I quote the exact required shape from the task details?** Use its exact\n keys and types, with every required field and no guessed renames.\n5. **Is my `output` a string (stringified JSON), not an object?** For a structured\n contract, `store-progress.output` should be a JSON string.\n6. **Only after the applicable contract is clear:** call `store-progress` with\n `status: "completed"` and the stringified JSON, or use plain text when no\n structured contract exists.\n\nIf the required shape is unclear, re-read the task details. Never synthesize a\nschema from tags or workflow origin.\n\n## Why this exists\n\nWhen a task has an actual `outputSchema`, the runner validates\n`store-progress.output` against it and rejects missing output, invalid JSON, or\nschema mismatches with one of the current messages listed above. A JSON Output\nFormat or interface without `task.outputSchema` remains a user instruction, but\nit is not the same runtime enforcement mechanism. Missing the distinction can\nturn completed work into a rejected terminal update, so check the task contract\nbefore reporting completion.\n\n## How to spot a structured-output task\n\nTreat these signals differently:\n\n- An actual `task.outputSchema` means JSON is runtime-enforced.\n- An explicit "Output Format", "Return a JSON object", or TypeScript/JSON\n interface is a user contract to return that shape, even without runtime\n enforcement.\n- Tags such as `deterministic`, `litmus`, `validation`, `releases`, or `context`,\n and `source = workflow`, only tell you to inspect the task details carefully.\n They do not prove a schema exists.\n\nWhen in doubt, re-read the task details and its `outputSchema`. Do not invent a\nschema or required fields.\n\n## How to complete correctly\n\n1. **Build the JSON object** that matches the actual `outputSchema` or explicit\n user-provided JSON format. Include every required field and use the exact key\n names from that contract.\n2. **Stringify it** — `store-progress.output` must be a string, not an object. Use `JSON.stringify(obj)` in your head.\n3. **Call store-progress** with `status: "completed"` and that JSON string as `output`.\n\n### Example — skip case\n\nTask has schema `{skip: bool, reason?: str, contextPath?: str, ...}` and you\'re skipping because the release already exists:\n\n```\nstore-progress(\n taskId,\n status="completed",\n output=\'{"skip":true,"reason":"Release already exists for this week"}\'\n)\n```\n\n### Example — full run\n\n```\nstore-progress(\n taskId,\n status="completed",\n output=\'{"skip":false,"contextPath":"release-runs/2026-04-20/context.json","commitCount":42,"repos":["example-repo"],"repoPatternsSource":"cache","dateRange":"2026-04-13 to 2026-04-20"}\'\n)\n```\n\n### Example — litmus / validation verdict\n\n```\nstore-progress(\n taskId,\n status="completed",\n output=\'{"verdict":"publish","reason":"5 user-facing changes; threshold met"}\'\n)\n```\n\n## Anti-patterns for an `outputSchema` task\n\n- `output: "Done. Context written to agent-fs at release-runs/2026-04-20/context.json"`\n- `output: "Published release notes for week of 2026-04-20"`\n- `output: "Verdict: publish"`\n- Calling `store-progress` with `status: "completed"` and no `output` at all\n- JSON that\'s missing any `required` field from the schema\n- JSON with extra keys instead of the schema\'s exact keys\n\n## Recovery if you realize mid-task\n\nIf you\'ve done all the work but forgot the JSON contract, just call `store-progress` again with the correct JSON string in `output`. Your prior progress updates don\'t count as the final output.\n\n## Verify before completing\n\nRead your task description once more. Find the schema. Build the JSON. Then complete. Takes 30 seconds. Saves a workflow re-run.\n\n## See also\n\n- **`workflow-iterate`** — the author-side counterpart of this skill. Read it if you\'re editing the workflow that produced this task, or want to understand why this particular schema is shaped the way it is (which gates downstream depend on it, etc.).\n';
22475
+ var content_default56 = '# Workflow Structured Output\n\n> **Companion skill — `workflow-iterate` (author-side).** This skill is for *workers* assigned a task spawned by an `agent-task` workflow node with an `outputSchema`. The author-side counterpart `workflow-iterate` covers how the workflow defines that schema, why gates downstream depend on it, and how to debug failed runs. If you ever need to understand *why* a particular schema is shaped the way it is — or you\'re switching from worker to author mode — read `workflow-iterate`.\n\n## Failure reason → fix (read this first)\n\nIf you see this failure reason on a task, the fix is always the same:\n\n| failureReason contains | What it means | Fix |\n|---|---|---|\n| `Task has an outputSchema but no output was provided` | You called `store-progress` without an `output` when the task required a JSON object matching `outputSchema` | Re-call `store-progress` with `status: "completed"` and `output` = a **stringified JSON** matching the schema exactly |\n| `Task output must be valid JSON` / `Task output does not match the outputSchema` | You passed invalid JSON, omitted required fields, or used the wrong types | Re-read the schema, include every `required` field with the exact key names, re-call `store-progress` |\n\n**You can re-call `store-progress` even after a rejection.** Your prior progress updates do not count as the final output. Fix the JSON and try again.\n\n## Pre-flight checklist (run through before calling store-progress)\n\n1. **Do the task details contain an actual `outputSchema`?** If yes, runtime\n enforcement is active: continue with that exact schema.\n2. **If there is no `outputSchema`, does the user provide an explicit JSON Output\n Format or interface?** Honor it as the requested output contract even though\n the runner is not enforcing an `outputSchema`.\n3. **Are workflow origin or tags such as `deterministic`, `litmus`, `validation`,\n or `context` the only signals?** They are heuristics only. Re-read the task\n details for an actual schema or explicit format. If neither exists, do not\n invent one; plain-text output is allowed.\n4. **Can I quote the exact required shape from the task details?** Use its exact\n keys and types, with every required field and no guessed renames.\n5. **Is my `output` a string (stringified JSON), not an object?** For a structured\n contract, `store-progress.output` should be a JSON string.\n6. **Only after the applicable contract is clear:** call `store-progress` with\n `status: "completed"` and the stringified JSON, or use plain text when no\n structured contract exists.\n\nIf the required shape is unclear, re-read the task details. Never synthesize a\nschema from tags or workflow origin.\n\n## Why this exists\n\nWhen a task has an actual `outputSchema`, the runner validates\n`store-progress.output` against it and rejects missing output, invalid JSON, or\nschema mismatches with one of the current messages listed above. A JSON Output\nFormat or interface without `task.outputSchema` remains a user instruction, but\nit is not the same runtime enforcement mechanism. Missing the distinction can\nturn completed work into a rejected terminal update, so check the task contract\nbefore reporting completion.\n\n## How to spot a structured-output task\n\nTreat these signals differently:\n\n- An actual `task.outputSchema` means JSON is runtime-enforced.\n- An explicit "Output Format", "Return a JSON object", or TypeScript/JSON\n interface is a user contract to return that shape, even without runtime\n enforcement.\n- Tags such as `deterministic`, `litmus`, `validation`, `releases`, or `context`,\n and `source = workflow`, only tell you to inspect the task details carefully.\n They do not prove a schema exists.\n\nWhen in doubt, re-read the task details and its `outputSchema`. Do not invent a\nschema or required fields.\n\n## How to complete correctly\n\n1. **Build the JSON object** that matches the actual `outputSchema` or explicit\n user-provided JSON format. Include every required field and use the exact key\n names from that contract.\n2. **Stringify it** — `store-progress.output` must be a string, not an object. Use `JSON.stringify(obj)` in your head.\n3. **Call store-progress** with `status: "completed"` and that JSON string as `output`.\n\n### Example — skip case\n\nTask has schema `{skip: bool, reason?: str, contextPath?: str, ...}` and you\'re skipping because the release already exists:\n\n```\nstore-progress(\n taskId,\n status="completed",\n output=\'{"skip":true,"reason":"Release already exists for this week"}\'\n)\n```\n\n### Example — full run\n\n```\nstore-progress(\n taskId,\n status="completed",\n output=\'{"skip":false,"contextPath":"release-runs/2026-04-20/context.json","commitCount":42,"repos":["example-repo"],"repoPatternsSource":"cache","dateRange":"2026-04-13 to 2026-04-20"}\'\n)\n```\n\n### Example — litmus / validation verdict\n\n```\nstore-progress(\n taskId,\n status="completed",\n output=\'{"verdict":"publish","reason":"5 user-facing changes; threshold met"}\'\n)\n```\n\n## Anti-patterns for an `outputSchema` task\n\n- `output: "Done. Context written to agent-fs at release-runs/2026-04-20/context.json"`\n- `output: "Published release notes for week of 2026-04-20"`\n- `output: "Verdict: publish"`\n- Calling `store-progress` with `status: "completed"` and no `output` at all\n- JSON that\'s missing any `required` field from the schema\n- JSON with extra keys instead of the schema\'s exact keys\n\n## Recovery if you realize mid-task\n\nIf you\'ve done all the work but forgot the JSON contract, just call `store-progress` again with the correct JSON string in `output`. Your prior progress updates don\'t count as the final output.\n\n## Verify before completing\n\nRead your task description once more. Find the schema. Build the JSON. Then complete. Takes 30 seconds. Saves a workflow re-run.\n\n## See also\n\n- **`workflow-iterate`** — the author-side counterpart of this skill. Read it if you\'re editing the workflow that produced this task, or want to understand why this particular schema is shaped the way it is (which gates downstream depend on it, etc.).\n';
22149
22476
 
22150
22477
  // templates/skills/wts-expert/config.json
22151
- var config_default56 = `{
22478
+ var config_default57 = `{
22152
22479
  "category": "skills",
22153
22480
  "description": "Git worktree management expert for @desplega.ai/wts. Use when the user asks about git worktrees, wts commands, worktree workflows, or wants help managing multiple branches simultaneously.",
22154
22481
  "displayName": "WTS Expert",
@@ -22169,7 +22496,7 @@ var config_default56 = `{
22169
22496
  `;
22170
22497
 
22171
22498
  // templates/skills/wts-expert/content.md
22172
- var content_default56 = `# WTS Expert
22499
+ var content_default57 = `# WTS Expert
22173
22500
 
22174
22501
  You are an expert on \`@desplega.ai/wts\`, a CLI tool for managing Git worktrees with tmux integration, Claude Code launcher support, and GitHub PR creation.
22175
22502
 
@@ -25161,7 +25488,8 @@ var BUILT_IN_SKILL_SOURCES = [
25161
25488
  { config: config_default53, body: content_default53 },
25162
25489
  { config: config_default54, body: content_default54 },
25163
25490
  { config: config_default55, body: content_default55 },
25164
- { config: config_default56, body: content_default56 }
25491
+ { config: config_default56, body: content_default56 },
25492
+ { config: config_default57, body: content_default57 }
25165
25493
  ];
25166
25494
  function canonicalFiles(files) {
25167
25495
  return [...files].sort((a, b) => a.path.localeCompare(b.path)).map((file) => `${file.path}
@@ -25345,7 +25673,7 @@ var skillsSeeder = {
25345
25673
  var import_cron_parser = __toESM(require_dist(), 1);
25346
25674
 
25347
25675
  // templates/schedules/daily-blocker-digest/config.json
25348
- var config_default57 = `{
25676
+ var config_default58 = `{
25349
25677
  "kind": "schedule",
25350
25678
  "name": "daily-blocker-digest",
25351
25679
  "displayName": "Daily Blocker Digest",
@@ -25367,7 +25695,7 @@ var config_default57 = `{
25367
25695
  `;
25368
25696
 
25369
25697
  // templates/schedules/daily-blocker-digest/content.md
25370
- var content_default57 = `# Daily Blocker Digest
25698
+ var content_default58 = `# Daily Blocker Digest
25371
25699
 
25372
25700
  Delivery uses configured admin channels with an in-app fallback.
25373
25701
 
@@ -25536,7 +25864,7 @@ Call \`store-progress\` with status \`completed\` and an output paragraph coveri
25536
25864
  `;
25537
25865
 
25538
25866
  // templates/schedules/daily-compounding-reflection/config.json
25539
- var config_default58 = `{
25867
+ var config_default59 = `{
25540
25868
  "kind": "schedule",
25541
25869
  "name": "daily-compounding-reflection",
25542
25870
  "displayName": "Daily Evolution",
@@ -25559,7 +25887,7 @@ var config_default58 = `{
25559
25887
  `;
25560
25888
 
25561
25889
  // templates/schedules/daily-compounding-reflection/content.md
25562
- var content_default58 = `# Daily Compounding Reflection
25890
+ var content_default59 = `# Daily Compounding Reflection
25563
25891
 
25564
25892
  Delivery uses configured admin channels with an in-app fallback.
25565
25893
 
@@ -25786,7 +26114,7 @@ If you have zero changes across all three folds and zero deferred items, somethi
25786
26114
  `;
25787
26115
 
25788
26116
  // templates/schedules/daily-hn-briefing/config.json
25789
- var config_default59 = `{
26117
+ var config_default60 = `{
25790
26118
  "kind": "schedule",
25791
26119
  "name": "daily-hn-briefing",
25792
26120
  "displayName": "Daily Hacker News Briefing",
@@ -25803,7 +26131,7 @@ var config_default59 = `{
25803
26131
  `;
25804
26132
 
25805
26133
  // templates/schedules/daily-hn-briefing/content.md
25806
- var content_default59 = `# Daily Hacker News Briefing
26134
+ var content_default60 = `# Daily Hacker News Briefing
25807
26135
 
25808
26136
  Template parameters: {{REPORT_EMAIL}}
25809
26137
 
@@ -25905,7 +26233,7 @@ IMPORTANT:
25905
26233
  `;
25906
26234
 
25907
26235
  // templates/schedules/daily-status-report/config.json
25908
- var config_default60 = `{
26236
+ var config_default61 = `{
25909
26237
  "kind": "schedule",
25910
26238
  "name": "daily-status-report",
25911
26239
  "displayName": "Daily Status Report",
@@ -25927,7 +26255,7 @@ var config_default60 = `{
25927
26255
  `;
25928
26256
 
25929
26257
  // templates/schedules/daily-status-report/content.md
25930
- var content_default60 = `# Daily Status Report
26258
+ var content_default61 = `# Daily Status Report
25931
26259
 
25932
26260
  Give the operator one daily read on whether the swarm is healthy: what's running, what's failed, what's waiting on them.
25933
26261
 
@@ -26109,7 +26437,7 @@ More than 3 qualify ⇒ post the 3 that matter and put the rest in the task outp
26109
26437
  `;
26110
26438
 
26111
26439
  // templates/schedules/daily-swarm-update-check/config.json
26112
- var config_default61 = `{
26440
+ var config_default62 = `{
26113
26441
  "kind": "schedule",
26114
26442
  "name": "daily-swarm-update-check",
26115
26443
  "displayName": "Daily Agent-Swarm Update Check",
@@ -26131,10 +26459,10 @@ var config_default61 = `{
26131
26459
  `;
26132
26460
 
26133
26461
  // templates/schedules/daily-swarm-update-check/content.md
26134
- var content_default61 = '# Daily Agent-Swarm Update Check\n\nZero-config auto-update watchdog: compares the swarm\'s own running version against the latest published GitHub release of `desplega-ai/agent-swarm`, and flags the operator when an upgrade is available. No placeholders and no integration required — every install gets this by default.\n\nThis is a script schedule: each fire runs the global `swarm-update-check` script directly, with no agent task in between. The script:\n\n1. Reads the running version from the API server\'s own `/health` route.\n2. Fetches `https://api.github.com/repos/desplega-ai/agent-swarm/releases/latest` once and reads `tag_name` and `html_url`.\n3. Compares the two as numeric `major.minor.patch`, never as strings (`"1.9.0" < "1.10.0"` is false as strings).\n4. Only when the latest release is newer, sends the lead one task to post the notice to its configured admin delivery channel (the in-app fallback if none is configured).\n\nUp to date, a missing running version (reported as `unknown`, never as up to date) and an unreachable GitHub API all end the run without any agent task. A failed GitHub call is reported once and never retried in a loop. The check never attempts the upgrade; `weekly-harness-upgrade-check` is the separate routine that bumps pinned harness versions inside the repo.\n\n## Schedule\n\n```json\n{\n "cron": "0 9 * * *",\n "timezone": "UTC",\n "enabled": true,\n "targetType": "script",\n "scriptName": "swarm-update-check",\n "scriptArgs": {}\n}\n```\n';
26462
+ var content_default62 = '# Daily Agent-Swarm Update Check\n\nZero-config auto-update watchdog: compares the swarm\'s own running version against the latest published GitHub release of `desplega-ai/agent-swarm`, and flags the operator when an upgrade is available. No placeholders and no integration required — every install gets this by default.\n\nThis is a script schedule: each fire runs the global `swarm-update-check` script directly, with no agent task in between. The script:\n\n1. Reads the running version from the API server\'s own `/health` route.\n2. Fetches `https://api.github.com/repos/desplega-ai/agent-swarm/releases/latest` once and reads `tag_name` and `html_url`.\n3. Compares the two as numeric `major.minor.patch`, never as strings (`"1.9.0" < "1.10.0"` is false as strings).\n4. Only when the latest release is newer, sends the lead one task to post the notice to its configured admin delivery channel (the in-app fallback if none is configured).\n\nUp to date, a missing running version (reported as `unknown`, never as up to date) and an unreachable GitHub API all end the run without any agent task. A failed GitHub call is reported once and never retried in a loop. The check never attempts the upgrade; `weekly-harness-upgrade-check` is the separate routine that bumps pinned harness versions inside the repo.\n\n## Schedule\n\n```json\n{\n "cron": "0 9 * * *",\n "timezone": "UTC",\n "enabled": true,\n "targetType": "script",\n "scriptName": "swarm-update-check",\n "scriptArgs": {}\n}\n```\n';
26135
26463
 
26136
26464
  // templates/schedules/dreaming-daily/config.json
26137
- var config_default62 = `{
26465
+ var config_default63 = `{
26138
26466
  "kind": "schedule",
26139
26467
  "name": "dreaming-daily",
26140
26468
  "displayName": "Dreaming",
@@ -26156,7 +26484,7 @@ var config_default62 = `{
26156
26484
  `;
26157
26485
 
26158
26486
  // templates/schedules/dreaming-daily/content.md
26159
- var content_default62 = `# Dreaming Daily Trigger
26487
+ var content_default63 = `# Dreaming Daily Trigger
26160
26488
 
26161
26489
  Trigger the \`dreaming\` workflow once a day. It replaces the Daily Evolution schedule (\`daily-compounding-reflection\`), which now seeds disabled.
26162
26490
 
@@ -26178,7 +26506,7 @@ The \`dreaming\` workflow carries the double-run guard as a 20-hour cooldown: a
26178
26506
  `;
26179
26507
 
26180
26508
  // templates/schedules/gtm-weekly-review/config.json
26181
- var config_default63 = `{
26509
+ var config_default64 = `{
26182
26510
  "kind": "schedule",
26183
26511
  "name": "gtm-weekly-review",
26184
26512
  "displayName": "Weekly GTM Metrics Review",
@@ -26195,7 +26523,7 @@ var config_default63 = `{
26195
26523
  `;
26196
26524
 
26197
26525
  // templates/schedules/gtm-weekly-review/content.md
26198
- var content_default63 = `Template parameters: {{REPO_URL}}, {{GSC_PROPERTY}}
26526
+ var content_default64 = `Template parameters: {{REPO_URL}}, {{GSC_PROPERTY}}
26199
26527
 
26200
26528
  # Weekly GTM Metrics Review
26201
26529
 
@@ -26276,7 +26604,7 @@ This is part of your team's GTM goal; update the goal statement before enabling
26276
26604
  `;
26277
26605
 
26278
26606
  // templates/schedules/weekly-code-health-reports/config.json
26279
- var config_default64 = `{
26607
+ var config_default65 = `{
26280
26608
  "kind": "schedule",
26281
26609
  "name": "weekly-code-health-reports",
26282
26610
  "displayName": "Weekly Code Health Reports",
@@ -26293,7 +26621,7 @@ var config_default64 = `{
26293
26621
  `;
26294
26622
 
26295
26623
  // templates/schedules/weekly-code-health-reports/content.md
26296
- var content_default64 = `# Weekly Code Health Reports
26624
+ var content_default65 = `# Weekly Code Health Reports
26297
26625
 
26298
26626
  Template parameters: {{REPO_URL}}, {{BRANCH}}, {{SCOPE_PATH}}, {{REPORT_NAME}}, {{PAGE_ID}}
26299
26627
 
@@ -26358,7 +26686,7 @@ Call \`store-progress\` with status \`completed\` and an output summary that inc
26358
26686
  `;
26359
26687
 
26360
26688
  // templates/schedules/weekly-dependabot-triage/config.json
26361
- var config_default65 = `{
26689
+ var config_default66 = `{
26362
26690
  "kind": "schedule",
26363
26691
  "name": "weekly-dependabot-triage",
26364
26692
  "displayName": "Weekly Dependency Triage",
@@ -26375,7 +26703,7 @@ var config_default65 = `{
26375
26703
  `;
26376
26704
 
26377
26705
  // templates/schedules/weekly-dependabot-triage/content.md
26378
- var content_default65 = `# Weekly Dependency Triage
26706
+ var content_default66 = `# Weekly Dependency Triage
26379
26707
 
26380
26708
  Template parameters: {{SLACK_CHANNEL_ID}}, {{REPO_URL}}, {{TIMEZONE}}
26381
26709
 
@@ -26429,7 +26757,7 @@ Call \`store-progress\` with status \`completed\` and an output summary listing
26429
26757
  `;
26430
26758
 
26431
26759
  // templates/schedules/weekly-dora-metrics/config.json
26432
- var config_default66 = `{
26760
+ var config_default67 = `{
26433
26761
  "kind": "schedule",
26434
26762
  "name": "weekly-dora-metrics",
26435
26763
  "displayName": "Weekly DORA Metrics",
@@ -26446,7 +26774,7 @@ var config_default66 = `{
26446
26774
  `;
26447
26775
 
26448
26776
  // templates/schedules/weekly-dora-metrics/content.md
26449
- var content_default66 = `# Weekly DORA Metrics
26777
+ var content_default67 = `# Weekly DORA Metrics
26450
26778
 
26451
26779
  Template parameters: {{REPO_URL}}, {{BRANCH}}, {{TAG_PATTERN}}, {{REPORT_NAME}}, {{PAGE_ID}}
26452
26780
 
@@ -26512,7 +26840,7 @@ Call \`store-progress\` with status \`completed\` and an output summary that inc
26512
26840
  `;
26513
26841
 
26514
26842
  // templates/schedules/weekly-harness-upgrade-check/config.json
26515
- var config_default67 = `{
26843
+ var config_default68 = `{
26516
26844
  "kind": "schedule",
26517
26845
  "name": "weekly-harness-upgrade-check",
26518
26846
  "displayName": "Weekly Harness Upgrade Check",
@@ -26529,7 +26857,7 @@ var config_default67 = `{
26529
26857
  `;
26530
26858
 
26531
26859
  // templates/schedules/weekly-harness-upgrade-check/content.md
26532
- var content_default67 = '# Weekly Harness Upgrade Check\n\nThis is a topology-preserving, anonymized port of the live Sunday schedule. It keeps its bundle, deduplication, baseline, partial-fallback, and CI acceptance behavior.\n\n```json\n{"cron":"0 16 * * 0","timezone":"UTC","agentRole":"lead","enabled":true}\n```\n\n**Weekly Harness Upgrade — self-hosted repository Dockerfile.worker**\n\nRepo: `{{REPO_URL}}` (working dir: `/workspace/repo`)\nFile: `Dockerfile.worker`\n\nThe worker image pins these harnesses via `ARG`. Each week, check upstream for new versions and open ONE PR bundling ALL outdated harness bumps together ({{PR_REVIEWER}}\'s preference — bump ALL in one PR per run, do NOT stagger one-per-run).\n\n| ARG | Source | Sync requirement |\n|---|---|---|\n| `CLAUDE_CODE_VERSION` | npm `@anthropic-ai/claude-code` | none |\n| `PI_CODING_AGENT_VERSION` | npm `@earendil-works/pi-coding-agent` | MUST match `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-coding-agent` in `package.json` (family-pin, all same version) — bump all together |\n| `CODEX_VERSION` | npm `@openai/codex` | MUST match direct `@openai/codex` in `package.json` (enforced by `scripts/check-codex-default-model.sh`) |\n| `OPENCODE_VERSION` | npm `@opencode/sdk` | Installs both `@opencode/cli` and `@opencode/sdk`. MUST match `@opencode/sdk` and `@opencode/plugin` in `package.json` devDependencies. OpenCode 2 ships under the `@opencode/*` scope; never take a version from `opencode-ai`, `@opencode-ai/sdk`, or the `sst/opencode` GitHub releases (still the 1.x line, which would be a downgrade) |\n\n## Steps\n\n1. `cd /workspace/repo && git fetch origin && git checkout main && git pull --ff-only`\n2. Read current pinned versions from `Dockerfile.worker` (the `ARG` lines) and from `package.json` (for the pi family + `@openai/codex` + `@opencode/sdk`).\n3. For each harness, fetch the latest version:\n - npm claude-code: `npm view @anthropic-ai/claude-code version`\n - npm pi: `npm view @earendil-works/pi-coding-agent version` (use the SAME version for `@earendil-works/pi-agent-core` and `@earendil-works/pi-ai` — they\'re a family pin)\n - npm codex: `npm view @openai/codex version`\n - npm opencode: `npm view @opencode/sdk version` (one version for `@opencode/cli`, `@opencode/sdk`, `@opencode/plugin`)\n4. Check for an existing open bundled PR — `gh pr list --search "harness upgrade in:title" --state open --repo {{REPO_URL}}`. Look at the branch prefix `harness-upgrade/`. If one is already open AND was created within the last 48h (sibling schedule may have just opened it), skip and complete with `"Skipped: sibling harness upgrade PR already open"` + the existing PR URL.\n5. Collect ALL outdated harnesses. If none are outdated, complete with output `"All harnesses up to date as of YYYY-MM-DD"` (no PR).\n6. Branch: `harness-upgrade/weekly-YYYY-MM-DD` (e.g. `harness-upgrade/weekly-2026-06-03`).\n7. Edit `Dockerfile.worker` — bump every outdated ARG. Also update `package.json`:\n - Codex: bump direct `@openai/codex` to match `CODEX_VERSION`.\n - Pi family: bump `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-coding-agent` to the same new version as `PI_CODING_AGENT_VERSION`.\n - Opencode: bump `@opencode/sdk` and `@opencode/plugin` (devDependencies) to match `OPENCODE_VERSION`.\n Then re-run `bun install` so `bun.lock` updates.\n8. Local verification (all must pass before pushing):\n ```bash\n bun install --frozen-lockfile\n bun run lint\n bun run tsc:check\n bun test\n bash scripts/check-db-boundary.sh\n ```\n For Codex bumps: also run `bash scripts/check-codex-default-model.sh` (CI runs it too). It fails when `ARG CODEX_VERSION` differs from the direct `@openai/codex` pin in `package.json`, or when the Dockerfile\'s baseline `model = "..."` differs from `CODEX_DEFAULT_MODEL` in `src/providers/codex-models.ts`.\n Note: do NOT run `docker build -f Dockerfile.worker .` locally — the runner lacks docker. CI\'s `docker-worker-build` job is the acceptance gate.\n9. If any local check fails, apply the **partial-bundle fallback** before giving up — one harness must never block the others:\n **BASELINE FIRST — do this before ANY isolation work.** A red gate does NOT mean the bumps broke anything. Re-run the EXACT failing command on a pristine `origin/main` worktree with zero bumps applied (`git worktree add /tmp/hb-baseline origin/main && cd /tmp/hb-baseline && bun install --frozen-lockfile`) and compare. If the SAME checks fail with the SAME assertions and the same pass/skip/fail totals, the failure is **PRE-EXISTING and unrelated to the bumps** ⇒ it does NOT block this PR, and you must NOT attempt isolation for it. Proceed to step 10, open the PR, and add a `## Pre-existing failures (also fail on origin/main)` section quoting the verbatim error plus both totals (baseline vs branch) so the reviewer can see they match. Only a failure that is RED on your branch and GREEN on baseline was caused by a bump — apply a–d below to that failure ONLY. A gate that is red on origin/main is never a reason to skip the weekly bump.\n a. Isolate which harness\'s bump caused it. The error usually names the package; if not, revert bumps one at a time until the step-8 gate passes.\n b. Revert ONLY that harness — its `Dockerfile.worker` ARG **and** its `package.json` pins (respect the family/sync requirements in the table above) — then re-run `bun install` and the FULL step-8 gate.\n c. Gate green ⇒ open the PR with the remaining harnesses and add a `## Held back` section naming the excluded harness, current → attempted version, and the VERBATIM error. Name it in your `store-progress` output too.\n d. Gate still red with that harness reverted, OR the failure cannot be isolated to one harness ⇒ do NOT open a PR; report via `store-progress` with `failureReason`.\n Migrating an upstream API break (a removed option, a renamed export, a moved type) is still OUT OF SCOPE for this routine — hold that harness back per (c) rather than changing code here.\n10. Push the branch and open a PR:\n - Title: `chore(docker): bump harnesses (weekly YYYY-MM-DD)` — or list the bumps, e.g. `chore(docker): bump claude-code, pi, opencode (weekly YYYY-MM-DD)`.\n - Body: include a table of current → new versions for every harness bumped, link to each upstream changelog (e.g. https://github.com/anthropics/claude-code/releases/tag/v<X.Y.Z>), and the local verification output (or "all green").\n - Add `{{PR_REVIEWER}}` as a reviewer.\n - DO NOT merge — {{PR_REVIEWER}} reviews and merges.\n11. Verify CI on the PR — wait for the merge-gate workflow to start, confirm at least the `docker-worker-build` job is queued/passing. If CI fails, comment on the PR with the failure log and leave the branch for human review.\n\n## Constraints\n\n- **ONE bundled PR per run.** Bump every outdated harness in the same PR — do not stagger one-per-run. The ONLY permitted exclusion is a harness held back by the step-9 partial-bundle fallback, which must be declared in the PR body.\n- **No `--no-verify`, no force pushes.**\n- If a harness has a major-version bump (e.g. 2.x → 3.x), still bundle it but flag clearly in the PR description that this is a major bump and may need extra review.\n- Pi family-pin: all three pi packages MUST be the same version. If they drift in the lockfile, fix the drift in the same PR.\n\n## Sibling-schedule coordination\nThis schedule has a sibling — `weekly-harness-upgrade-check-wed` (Wednesday 05:00 BCN). If a sibling-opened PR is OPEN and `< 48h` old, step 4 skips. This is the dedup gate. Don\'t change branch-naming heuristics in a way that breaks the dedup.\n\n## Output\n\n`store-progress` with `status: "completed"` and `output` containing:\n- The PR URL (if one was opened) + the table of harnesses bumped, OR\n- "No-op: all harnesses up to date as of YYYY-MM-DD" with the version table, OR\n- "Skipped: sibling harness upgrade PR already open" with the existing PR URL.\n';
26860
+ var content_default68 = '# Weekly Harness Upgrade Check\n\nThis is a topology-preserving, anonymized port of the live Sunday schedule. It keeps its bundle, deduplication, baseline, partial-fallback, and CI acceptance behavior.\n\n```json\n{"cron":"0 16 * * 0","timezone":"UTC","agentRole":"lead","enabled":true}\n```\n\n**Weekly Harness Upgrade — self-hosted repository Dockerfile.worker**\n\nRepo: `{{REPO_URL}}` (working dir: `/workspace/repo`)\nFile: `Dockerfile.worker`\n\nThe worker image pins these harnesses via `ARG`. Each week, check upstream for new versions and open ONE PR bundling ALL outdated harness bumps together ({{PR_REVIEWER}}\'s preference — bump ALL in one PR per run, do NOT stagger one-per-run).\n\n| ARG | Source | Sync requirement |\n|---|---|---|\n| `CLAUDE_CODE_VERSION` | npm `@anthropic-ai/claude-code` | none |\n| `PI_CODING_AGENT_VERSION` | npm `@earendil-works/pi-coding-agent` | MUST match `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-coding-agent` in `package.json` (family-pin, all same version) — bump all together |\n| `CODEX_VERSION` | npm `@openai/codex` | MUST match direct `@openai/codex` in `package.json` (enforced by `scripts/check-codex-default-model.sh`) |\n| `OPENCODE_VERSION` | npm `@opencode/sdk` | Installs both `@opencode/cli` and `@opencode/sdk`. MUST match `@opencode/sdk` and `@opencode/plugin` in `package.json` devDependencies. OpenCode 2 ships under the `@opencode/*` scope; never take a version from `opencode-ai`, `@opencode-ai/sdk`, or the `sst/opencode` GitHub releases (still the 1.x line, which would be a downgrade) |\n\n## Steps\n\n1. `cd /workspace/repo && git fetch origin && git checkout main && git pull --ff-only`\n2. Read current pinned versions from `Dockerfile.worker` (the `ARG` lines) and from `package.json` (for the pi family + `@openai/codex` + `@opencode/sdk`).\n3. For each harness, fetch the latest version:\n - npm claude-code: `npm view @anthropic-ai/claude-code version`\n - npm pi: `npm view @earendil-works/pi-coding-agent version` (use the SAME version for `@earendil-works/pi-agent-core` and `@earendil-works/pi-ai` — they\'re a family pin)\n - npm codex: `npm view @openai/codex version`\n - npm opencode: `npm view @opencode/sdk version` (one version for `@opencode/cli`, `@opencode/sdk`, `@opencode/plugin`)\n4. Check for an existing open bundled PR — `gh pr list --search "harness upgrade in:title" --state open --repo {{REPO_URL}}`. Look at the branch prefix `harness-upgrade/`. If one is already open AND was created within the last 48h (sibling schedule may have just opened it), skip and complete with `"Skipped: sibling harness upgrade PR already open"` + the existing PR URL.\n5. Collect ALL outdated harnesses. If none are outdated, complete with output `"All harnesses up to date as of YYYY-MM-DD"` (no PR).\n6. Branch: `harness-upgrade/weekly-YYYY-MM-DD` (e.g. `harness-upgrade/weekly-2026-06-03`).\n7. Edit `Dockerfile.worker` — bump every outdated ARG. Also update `package.json`:\n - Codex: bump direct `@openai/codex` to match `CODEX_VERSION`.\n - Pi family: bump `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-coding-agent` to the same new version as `PI_CODING_AGENT_VERSION`.\n - Opencode: bump `@opencode/sdk` and `@opencode/plugin` (devDependencies) to match `OPENCODE_VERSION`.\n Then re-run `bun install` so `bun.lock` updates.\n8. Local verification (all must pass before pushing):\n ```bash\n bun install --frozen-lockfile\n bun run lint\n bun run tsc:check\n bun test\n bash scripts/check-db-boundary.sh\n ```\n For Codex bumps: also run `bash scripts/check-codex-default-model.sh` (CI runs it too). It fails when `ARG CODEX_VERSION` differs from the direct `@openai/codex` pin in `package.json`, or when the Dockerfile\'s baseline `model = "..."` differs from `CODEX_DEFAULT_MODEL` in `src/providers/codex-models.ts`.\n Note: do NOT run `docker build -f Dockerfile.worker .` locally — the runner lacks docker. CI\'s `docker-worker-build` job is the acceptance gate.\n9. If any local check fails, apply the **partial-bundle fallback** before giving up — one harness must never block the others:\n **BASELINE FIRST — do this before ANY isolation work.** A red gate does NOT mean the bumps broke anything. Re-run the EXACT failing command on a pristine `origin/main` worktree with zero bumps applied (`git worktree add /tmp/hb-baseline origin/main && cd /tmp/hb-baseline && bun install --frozen-lockfile`) and compare. If the SAME checks fail with the SAME assertions and the same pass/skip/fail totals, the failure is **PRE-EXISTING and unrelated to the bumps** ⇒ it does NOT block this PR, and you must NOT attempt isolation for it. Proceed to step 10, open the PR, and add a `## Pre-existing failures (also fail on origin/main)` section quoting the verbatim error plus both totals (baseline vs branch) so the reviewer can see they match. Only a failure that is RED on your branch and GREEN on baseline was caused by a bump — apply a–d below to that failure ONLY. A gate that is red on origin/main is never a reason to skip the weekly bump.\n a. Isolate which harness\'s bump caused it. The error usually names the package; if not, revert bumps one at a time until the step-8 gate passes.\n b. Revert ONLY that harness — its `Dockerfile.worker` ARG **and** its `package.json` pins (respect the family/sync requirements in the table above) — then re-run `bun install` and the FULL step-8 gate.\n c. Gate green ⇒ open the PR with the remaining harnesses and add a `## Held back` section naming the excluded harness, current → attempted version, and the VERBATIM error. Name it in your `store-progress` output too.\n d. Gate still red with that harness reverted, OR the failure cannot be isolated to one harness ⇒ do NOT open a PR; report via `store-progress` with `failureReason`.\n Migrating an upstream API break (a removed option, a renamed export, a moved type) is still OUT OF SCOPE for this routine — hold that harness back per (c) rather than changing code here.\n10. Push the branch and open a PR:\n - Title: `chore(docker): bump harnesses (weekly YYYY-MM-DD)` — or list the bumps, e.g. `chore(docker): bump claude-code, pi, opencode (weekly YYYY-MM-DD)`.\n - Body: include a table of current → new versions for every harness bumped, link to each upstream changelog (e.g. https://github.com/anthropics/claude-code/releases/tag/v<X.Y.Z>), and the local verification output (or "all green").\n - Add `{{PR_REVIEWER}}` as a reviewer.\n - DO NOT merge — {{PR_REVIEWER}} reviews and merges.\n11. Verify CI on the PR — wait for the merge-gate workflow to start, confirm at least the `docker-worker-build` job is queued/passing. If CI fails, comment on the PR with the failure log and leave the branch for human review.\n\n## Constraints\n\n- **ONE bundled PR per run.** Bump every outdated harness in the same PR — do not stagger one-per-run. The ONLY permitted exclusion is a harness held back by the step-9 partial-bundle fallback, which must be declared in the PR body.\n- **No `--no-verify`, no force pushes.**\n- If a harness has a major-version bump (e.g. 2.x → 3.x), still bundle it but flag clearly in the PR description that this is a major bump and may need extra review.\n- Pi family-pin: all three pi packages MUST be the same version. If they drift in the lockfile, fix the drift in the same PR.\n\n## Sibling-schedule coordination\nThis schedule has a sibling — `weekly-harness-upgrade-check-wed` (Wednesday 05:00 BCN). If a sibling-opened PR is OPEN and `< 48h` old, step 4 skips. This is the dedup gate. Don\'t change branch-naming heuristics in a way that breaks the dedup.\n\n## Output\n\n`store-progress` with `status: "completed"` and `output` containing:\n- The PR URL (if one was opened) + the table of harnesses bumped, OR\n- "No-op: all harnesses up to date as of YYYY-MM-DD" with the version table, OR\n- "Skipped: sibling harness upgrade PR already open" with the existing PR URL.\n';
26533
26861
 
26534
26862
  // src/be/seed/schedules-seeder.ts
26535
26863
  init_db4();
@@ -26556,31 +26884,31 @@ init_workflows_seeder();
26556
26884
  var TARGET_TYPES = ["agent-task", "workflow", "script"];
26557
26885
  var asText2 = (value) => value;
26558
26886
  var BUILT_IN_SCHEDULE_SOURCES = [
26559
- { config: asText2(config_default57), content: asText2(content_default57) },
26887
+ { config: asText2(config_default58), content: asText2(content_default58) },
26560
26888
  {
26561
- config: asText2(config_default58),
26562
- content: asText2(content_default58)
26889
+ config: asText2(config_default59),
26890
+ content: asText2(content_default59)
26563
26891
  },
26564
- { config: asText2(config_default59), content: asText2(content_default59) },
26565
26892
  { config: asText2(config_default60), content: asText2(content_default60) },
26893
+ { config: asText2(config_default61), content: asText2(content_default61) },
26566
26894
  {
26567
- config: asText2(config_default61),
26568
- content: asText2(content_default61)
26895
+ config: asText2(config_default62),
26896
+ content: asText2(content_default62)
26569
26897
  },
26570
- { config: asText2(config_default62), content: asText2(content_default62) },
26571
26898
  { config: asText2(config_default63), content: asText2(content_default63) },
26572
- {
26573
- config: asText2(config_default64),
26574
- content: asText2(content_default64)
26575
- },
26899
+ { config: asText2(config_default64), content: asText2(content_default64) },
26576
26900
  {
26577
26901
  config: asText2(config_default65),
26578
26902
  content: asText2(content_default65)
26579
26903
  },
26580
- { config: asText2(config_default66), content: asText2(content_default66) },
26581
26904
  {
26582
- config: asText2(config_default67),
26583
- content: asText2(content_default67)
26905
+ config: asText2(config_default66),
26906
+ content: asText2(content_default66)
26907
+ },
26908
+ { config: asText2(config_default67), content: asText2(content_default67) },
26909
+ {
26910
+ config: asText2(config_default68),
26911
+ content: asText2(content_default68)
26584
26912
  }
26585
26913
  ];
26586
26914
  function parseScheduleSource(source) {