@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.3

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 (319) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +141 -2
  3. package/bin/codeflow.mjs +8 -0
  4. package/bin/launcher.mjs +127 -0
  5. package/dist/remote-host.json +1 -0
  6. package/licenses/inter.txt +92 -0
  7. package/licenses/preact.txt +21 -0
  8. package/licenses/signals-core.txt +21 -0
  9. package/licenses/signals.txt +21 -0
  10. package/licenses/typescript-notices.txt +193 -0
  11. package/licenses/typescript.txt +55 -0
  12. package/licenses/uqr.txt +22 -0
  13. package/licenses/xterm-fit.txt +19 -0
  14. package/licenses/xterm.txt +21 -0
  15. package/package.json +34 -4
  16. package/public/assets/changes-62ZIEQSN.js +1 -0
  17. package/public/assets/chunk-2PZVOKID.js +1 -0
  18. package/public/assets/chunk-4D5IENEB.js +1 -0
  19. package/public/assets/chunk-5SARP5MU.js +1 -0
  20. package/public/assets/chunk-63YLZ3PR.js +1 -0
  21. package/public/assets/chunk-7FUHKF2M.js +1 -0
  22. package/public/assets/chunk-APQEVJ2K.js +1 -0
  23. package/public/assets/chunk-CGOZQMEZ.js +2 -0
  24. package/public/assets/chunk-J4VYS3KV.js +2 -0
  25. package/public/assets/chunk-L7TUCIYF.js +1 -0
  26. package/public/assets/chunk-SIHDWM2Y.js +154 -0
  27. package/public/assets/chunk-TEJVYIKC.js +1 -0
  28. package/public/assets/code-browser-VB2HGZSG.js +4 -0
  29. package/public/assets/filtered-tasks-ES5CP4KV.js +1 -0
  30. package/public/assets/interactive-browser-7F5ZXRUV.js +7 -0
  31. package/public/assets/join-project-6RTFHNCA.js +1 -0
  32. package/public/assets/main-65EW73SB.js +1 -0
  33. package/public/assets/project-invitations-view-GMPWGWYM.js +1 -0
  34. package/public/assets/settings-UB5Q4AQM.js +9 -0
  35. package/public/assets/styles-18792BB4.css +32 -0
  36. package/public/assets/team-server-wizard-2GLDWS6D.js +8 -0
  37. package/public/assets/terminal-IWAIM4DE.js +62 -0
  38. package/public/assets.json +1 -0
  39. package/public/bundle-meta.json +1 -0
  40. package/public/docs/.nojekyll +0 -0
  41. package/public/docs/accessibility.html +19 -0
  42. package/public/docs/acp-agents.html +117 -0
  43. package/public/docs/agent-containers.html +79 -0
  44. package/public/docs/api.html +1130 -0
  45. package/public/docs/app.js +342 -0
  46. package/public/docs/application-improvements.html +275 -0
  47. package/public/docs/architecture-explorer.html +19 -0
  48. package/public/docs/architecture.html +149 -0
  49. package/public/docs/auto-team.html +148 -0
  50. package/public/docs/automations.html +109 -0
  51. package/public/docs/checkpoint-review.html +37 -0
  52. package/public/docs/code-hosts.html +35 -0
  53. package/public/docs/code-intelligence.html +35 -0
  54. package/public/docs/configuration.html +346 -0
  55. package/public/docs/context-inspection.html +23 -0
  56. package/public/docs/coordinated-changes.html +28 -0
  57. package/public/docs/deferred-runs.html +25 -0
  58. package/public/docs/dependency-discovery.html +19 -0
  59. package/public/docs/documentation.html +84 -0
  60. package/public/docs/dynamic-teams-evaluation.html +174 -0
  61. package/public/docs/dynamic-teams-implementation-plan.html +882 -0
  62. package/public/docs/dynamic-teams-implementation-review-1.html +141 -0
  63. package/public/docs/dynamic-teams-plan-review-0.html +204 -0
  64. package/public/docs/extensions.html +42 -0
  65. package/public/docs/external-sources.html +96 -0
  66. package/public/docs/filesystem-policy.html +26 -0
  67. package/public/docs/filtered-tasks.html +44 -0
  68. package/public/docs/font-license.txt +92 -0
  69. package/public/docs/getting-started.html +143 -0
  70. package/public/docs/github-review-threads.html +26 -0
  71. package/public/docs/github.html +157 -0
  72. package/public/docs/help.html +69 -0
  73. package/public/docs/index.html +88 -0
  74. package/public/docs/installation.html +80 -0
  75. package/public/docs/launch-profiles.html +48 -0
  76. package/public/docs/maintenance.html +60 -0
  77. package/public/docs/memory-claims.html +31 -0
  78. package/public/docs/memory-storage.html +58 -0
  79. package/public/docs/notifications.html +39 -0
  80. package/public/docs/patterns.html +195 -0
  81. package/public/docs/performance-results.html +210 -0
  82. package/public/docs/performance.html +166 -0
  83. package/public/docs/project-conventions.html +22 -0
  84. package/public/docs/project-first-navigation-plan.html +587 -0
  85. package/public/docs/project-teams-implementation-plan.html +772 -0
  86. package/public/docs/project-teams.html +129 -0
  87. package/public/docs/provider-compatibility.html +20 -0
  88. package/public/docs/releasing.html +65 -0
  89. package/public/docs/remote-workers.html +64 -0
  90. package/public/docs/review-inbox.html +26 -0
  91. package/public/docs/run-storage.html +23 -0
  92. package/public/docs/runs.html +141 -0
  93. package/public/docs/search.json +1 -0
  94. package/public/docs/security.html +133 -0
  95. package/public/docs/shared-projects.html +31 -0
  96. package/public/docs/ssh-projects.html +60 -0
  97. package/public/docs/style.css +768 -0
  98. package/public/docs/task-reruns.html +30 -0
  99. package/public/docs/team-collaboration.html +412 -0
  100. package/public/docs/verification.html +22 -0
  101. package/public/docs/vscode.html +53 -0
  102. package/public/docs/worker-permission-verification.html +131 -0
  103. package/public/index.html +17 -0
  104. package/scripts/check-node.mjs +7 -0
  105. package/scripts/codeflow.mjs +55 -0
  106. package/scripts/computer-use.swift +64 -0
  107. package/scripts/pty.py +273 -0
  108. package/src/acp-connections.js +110 -0
  109. package/src/adapters/acp-presets.js +37 -0
  110. package/src/adapters/acp-types.js +0 -0
  111. package/src/adapters/acp.js +328 -0
  112. package/src/adapters/agent-tools.js +28 -0
  113. package/src/adapters/agy-auth.js +67 -0
  114. package/src/adapters/agy-isolation.js +242 -0
  115. package/src/adapters/agy-tools.js +45 -0
  116. package/src/adapters/agy.js +326 -0
  117. package/src/adapters/claude-stream.js +58 -0
  118. package/src/adapters/claude.js +282 -0
  119. package/src/adapters/codex-app-server.js +555 -0
  120. package/src/adapters/codex.js +311 -0
  121. package/src/adapters/errors.js +57 -0
  122. package/src/adapters/index.js +91 -0
  123. package/src/adapters/managed-permissions.js +37 -0
  124. package/src/adapters/model-discovery.js +100 -0
  125. package/src/adapters/process.js +433 -0
  126. package/src/adapters/team-tools.js +103 -0
  127. package/src/adapters/types.js +0 -0
  128. package/src/agent-browser.js +688 -0
  129. package/src/agent-computer.js +88 -0
  130. package/src/agent-container.js +155 -0
  131. package/src/agent-team-definitions.js +131 -0
  132. package/src/agent-tool-client.mjs +79 -0
  133. package/src/agent-tools.js +296 -0
  134. package/src/approvals.js +134 -0
  135. package/src/architecture.js +456 -0
  136. package/src/assets.js +44 -0
  137. package/src/automation.js +901 -0
  138. package/src/browser-files.js +293 -0
  139. package/src/browser-ownership.js +150 -0
  140. package/src/certificate-renewal.js +75 -0
  141. package/src/chat-family.js +25 -0
  142. package/src/chat-handoff.js +87 -0
  143. package/src/checkpoint-review.js +72 -0
  144. package/src/checks.js +303 -0
  145. package/src/code-host-git.js +102 -0
  146. package/src/code-hosts-api.js +99 -0
  147. package/src/code-hosts.js +482 -0
  148. package/src/code-intelligence-worker.mjs +452 -0
  149. package/src/code-intelligence.js +141 -0
  150. package/src/collab/api.js +365 -0
  151. package/src/collab/checkpoints.js +198 -0
  152. package/src/collab/connections.js +139 -0
  153. package/src/collab/host-execution.js +347 -0
  154. package/src/collab/hub-client.js +210 -0
  155. package/src/collab/link-api.js +229 -0
  156. package/src/collab/link.js +595 -0
  157. package/src/collab/model.js +496 -0
  158. package/src/collab/runner.js +1014 -0
  159. package/src/collab/store.js +1452 -0
  160. package/src/collab/terminals.js +361 -0
  161. package/src/collaboration-reviews.js +116 -0
  162. package/src/config.js +48 -0
  163. package/src/context-budget.js +14 -0
  164. package/src/context-inspection.js +204 -0
  165. package/src/context.js +154 -0
  166. package/src/conventions.js +283 -0
  167. package/src/coordinated-api.js +247 -0
  168. package/src/deferred-launch.js +82 -0
  169. package/src/deferred-runs.js +515 -0
  170. package/src/dependency-health.js +35 -0
  171. package/src/diff.js +43 -0
  172. package/src/docs-help.js +316 -0
  173. package/src/doctor.js +232 -0
  174. package/src/documentation-changes.js +20 -0
  175. package/src/engine.js +5258 -0
  176. package/src/env.js +44 -0
  177. package/src/execution-budget.js +8 -0
  178. package/src/experience.js +50 -0
  179. package/src/extensions.js +144 -0
  180. package/src/filesystem-access.js +107 -0
  181. package/src/filesystem-policy.js +238 -0
  182. package/src/filtered-task-limits.js +93 -0
  183. package/src/filtered-tasks-api.js +53 -0
  184. package/src/filtered-tasks.js +576 -0
  185. package/src/frame-policy.js +66 -0
  186. package/src/fs.js +57 -0
  187. package/src/git.js +626 -0
  188. package/src/github-review-threads.js +181 -0
  189. package/src/github.js +538 -0
  190. package/src/http.js +69 -0
  191. package/src/improve-settings.js +38 -0
  192. package/src/improve.js +187 -0
  193. package/src/integrations.js +373 -0
  194. package/src/integrity.js +259 -0
  195. package/src/journey-api.js +77 -0
  196. package/src/journey-replay.js +65 -0
  197. package/src/journey-store.js +97 -0
  198. package/src/journeys.js +60 -0
  199. package/src/json.js +81 -0
  200. package/src/launch-profiles.js +292 -0
  201. package/src/learnings.js +80 -0
  202. package/src/local-app-url.js +19 -0
  203. package/src/log.js +39 -0
  204. package/src/maintenance.js +335 -0
  205. package/src/memory-analysis.js +182 -0
  206. package/src/memory-claims.js +153 -0
  207. package/src/memory-sqlite.js +236 -0
  208. package/src/memory.js +552 -0
  209. package/src/merge-validation.js +58 -0
  210. package/src/model-catalog.js +239 -0
  211. package/src/model-research.js +91 -0
  212. package/src/notes.js +176 -0
  213. package/src/notifications.js +413 -0
  214. package/src/patterns/auto-team-model.js +230 -0
  215. package/src/patterns/auto-team.js +816 -0
  216. package/src/patterns/council.js +199 -0
  217. package/src/patterns/debate.js +188 -0
  218. package/src/patterns/findings.js +141 -0
  219. package/src/patterns/index.js +21 -0
  220. package/src/patterns/loop.js +158 -0
  221. package/src/patterns/pipeline.js +125 -0
  222. package/src/patterns/prompts.js +181 -0
  223. package/src/patterns/race.js +147 -0
  224. package/src/patterns/schemas.js +40 -0
  225. package/src/patterns/solo.js +46 -0
  226. package/src/patterns/supervisor.js +235 -0
  227. package/src/patterns/task-draft.js +29 -0
  228. package/src/patterns/task-review.js +45 -0
  229. package/src/patterns/tdd.js +231 -0
  230. package/src/patterns/team-strategies.js +67 -0
  231. package/src/performance.js +43 -0
  232. package/src/persistence-status.js +35 -0
  233. package/src/phone-sessions.js +96 -0
  234. package/src/preview-overlay.js +392 -0
  235. package/src/preview.js +230 -0
  236. package/src/privacy.js +23 -0
  237. package/src/project-report.js +22 -0
  238. package/src/project-team-budget.js +22 -0
  239. package/src/project-team-model.js +225 -0
  240. package/src/project-team-policy.js +42 -0
  241. package/src/project-team-store.js +234 -0
  242. package/src/project-team-usage.js +24 -0
  243. package/src/project-teams-api.js +43 -0
  244. package/src/project-teams.js +644 -0
  245. package/src/projects.js +290 -0
  246. package/src/provider-eligibility.js +9 -0
  247. package/src/readiness.js +98 -0
  248. package/src/remote-tls.js +66 -0
  249. package/src/remote-workers/bundles.js +198 -0
  250. package/src/remote-workers/client.js +332 -0
  251. package/src/remote-workers/durability.js +37 -0
  252. package/src/remote-workers/protocol.js +68 -0
  253. package/src/remote-workers/stdio.js +138 -0
  254. package/src/remote-workers/worker.js +304 -0
  255. package/src/remote.js +204 -0
  256. package/src/repo-config.js +201 -0
  257. package/src/repo-coordination.js +725 -0
  258. package/src/repo-tree.js +106 -0
  259. package/src/repository-identity.js +13 -0
  260. package/src/retention-policy.js +466 -0
  261. package/src/review-inbox.js +38 -0
  262. package/src/routing.js +49 -0
  263. package/src/run-analysis.js +111 -0
  264. package/src/run-cold-store.js +231 -0
  265. package/src/run-environment.js +15 -0
  266. package/src/run-history.js +91 -0
  267. package/src/run-log.js +160 -0
  268. package/src/run-permissions.js +111 -0
  269. package/src/run-projection.js +77 -0
  270. package/src/run-recovery.js +53 -0
  271. package/src/run-status.js +56 -0
  272. package/src/serve.js +138 -0
  273. package/src/server.js +2871 -0
  274. package/src/shared-access.js +103 -0
  275. package/src/shared-accounts.js +381 -0
  276. package/src/shared-api.js +239 -0
  277. package/src/shell.js +346 -0
  278. package/src/ship.js +344 -0
  279. package/src/slots.js +74 -0
  280. package/src/snapshot.js +388 -0
  281. package/src/source-context.js +17 -0
  282. package/src/sse-writer.js +70 -0
  283. package/src/ssh-projects/bootstrap.mjs +95 -0
  284. package/src/ssh-projects/config.js +45 -0
  285. package/src/ssh-projects/gateway.js +143 -0
  286. package/src/ssh-projects/manager.js +320 -0
  287. package/src/ssh-projects/team-autostart.mjs +93 -0
  288. package/src/ssh-projects/team-remove.mjs +69 -0
  289. package/src/ssh-projects/team-status.mjs +39 -0
  290. package/src/ssh-projects/transport.js +133 -0
  291. package/src/stats.js +139 -0
  292. package/src/store.js +544 -0
  293. package/src/stream.js +91 -0
  294. package/src/sweeps.js +241 -0
  295. package/src/tailscale.js +101 -0
  296. package/src/task-draft.js +23 -0
  297. package/src/task-team.js +164 -0
  298. package/src/team-evaluation.js +243 -0
  299. package/src/team-mailbox.js +160 -0
  300. package/src/team-memory.js +84 -0
  301. package/src/team-rerun-graph.js +15 -0
  302. package/src/team-reruns.js +130 -0
  303. package/src/team-scheduler.js +121 -0
  304. package/src/team-steering.js +21 -0
  305. package/src/team-template-store.js +98 -0
  306. package/src/team-templates.js +117 -0
  307. package/src/team-tool-client.mjs +79 -0
  308. package/src/team-tools.js +235 -0
  309. package/src/teams.js +0 -0
  310. package/src/templates.js +62 -0
  311. package/src/transcript.js +134 -0
  312. package/src/verification-integrity.js +27 -0
  313. package/src/verification.js +183 -0
  314. package/src/watch.js +195 -0
  315. package/src/work-queue.js +47 -0
  316. package/src/workflow-control.js +83 -0
  317. package/src/workspace-api.js +207 -0
  318. package/src/workspace-changes.js +61 -0
  319. package/src/workspace.js +146 -0
package/public/docs/project-teams.html ADDED
@@ -0,0 +1,129 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Project missions (preview) — code-flow guides and reference"><title>Project missions (preview) · code-flow</title><link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K"><link rel="stylesheet" href="style.css"><script src="app.js" defer></script></head>
3
+ <body data-page="project-teams"><a class="skip-link" href="#content">Skip to content</a>
4
+ <header class="topbar"><a class="brand" href="index.html"><img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K" width="30" height="30" alt=""><strong>Code Flow</strong><span>Docs</span></a><button class="search-trigger" id="open-search">Search documentation <kbd>⌘ K</kbd></button><div class="top-actions"><a href="https://github.com/midhunxavier/code-flow">GitHub ↗</a><button id="theme" aria-label="Change color theme">Theme</button><button id="open-help" class="primary" hidden aria-expanded="false" aria-controls="help-panel">Ask code-flow</button><button id="menu" aria-label="Toggle documentation navigation" aria-expanded="false" aria-controls="sidebar">☰</button></div></header>
5
+ <div class="layout"><nav class="sidebar" id="sidebar" aria-label="Documentation"><section><h2>Get started</h2><a href="index.html" >Overview</a><a href="installation.html" >Install Code Flow preview</a><a href="getting-started.html" >Getting started</a><a href="patterns.html" >Team patterns</a><a href="acp-agents.html" >ACP coding agents</a><a href="help.html" >Ask code-flow</a></section><section><h2>Work with agents</h2><a href="runs.html" >Runs and workspace</a><a href="auto-team.html" >Team</a><a href="project-teams.html" aria-current="page">Project missions (preview)</a><a href="review-inbox.html" >Review inbox</a><a href="verification.html" >Verification and review</a><a href="github.html" >GitHub, review and shipping</a><a href="github-review-threads.html" >GitHub review threads</a><a href="task-reruns.html" >Selective task reruns</a><a href="deferred-runs.html" >Deferred runs</a></section><section><h2>Your workspace</h2><a href="configuration.html" >Configuration</a><a href="context-inspection.html" >Context and budgets</a><a href="project-conventions.html" >Versioned project conventions</a><a href="checkpoint-review.html" >Checkpoints and reversions</a><a href="launch-profiles.html" >Service launch profiles</a><a href="code-intelligence.html" >Code intelligence</a><a href="architecture-explorer.html" >Architecture explorer</a><a href="memory-storage.html" >Project memory</a><a href="memory-claims.html" >Semantic claim review</a><a href="coordinated-changes.html" >Coordinated changes</a></section><section><h2>Connect and collaborate</h2><a href="team-collaboration.html" >Team collaboration</a><a href="shared-projects.html" >Shared project accounts</a><a href="ssh-projects.html" >SSH projects</a><a href="remote-workers.html" >Remote agent workers</a><a href="code-hosts.html" >GitLab and Bitbucket code workflows</a><a href="external-sources.html" >Read-only external sources</a><a href="automations.html" >Automations and away mode</a><a href="notifications.html" >Outbound notifications</a></section><section><h2>Operate safely</h2><a href="security.html" >Security, subscriptions and caveats</a><a href="filesystem-policy.html" >Project filesystem policy</a><a href="agent-containers.html" >Agent containers</a><a href="filtered-tasks.html" >Filtered Docker tasks</a><a href="dependency-discovery.html" >Dependency discovery</a><a href="maintenance.html" >Backup and maintenance</a></section><section><h2>Build and extend</h2><a href="architecture.html" >Architecture and development</a><a href="api.html" >Local API and command-line client</a><a href="extensions.html" >Provider and workflow extensions</a><a href="provider-compatibility.html" >Provider compatibility</a><a href="accessibility.html" >Accessibility acceptance</a><a href="performance.html" >Performance</a><a href="run-storage.html" >Run storage</a><a href="documentation.html" >Documentation and GitHub Pages</a><a href="releasing.html" >Preparing a preview release</a><a href="vscode.html" >Code Flow for VS Code</a></section><section><h2>Engineering records</h2><a href="application-improvements.html" >Application improvement program</a><a href="project-first-navigation-plan.html" >Project navigation review and implementation plan</a><a href="dynamic-teams-evaluation.html" >Dynamic teams: implementation evidence and rollout decision</a><a href="dynamic-teams-implementation-plan.html" >Dynamic teams, workflows, messaging, and memory</a><a href="dynamic-teams-implementation-review-1.html" >Review 1: the dynamic teams implementation</a><a href="worker-permission-verification.html" >Live worker permission verification</a><a href="dynamic-teams-plan-review-0.html" >Review 0: Dynamic teams implementation plan</a><a href="project-teams-implementation-plan.html" >Standing project teams implementation plan</a><a href="performance-results.html" >Measured performance: 19 October 2026</a></section><a class="app-link" id="back-app" hidden href="/">← Back to app</a></nav>
6
+ <main id="content" tabindex="-1"><div class="breadcrumb">Documentation <span>/</span> Work with agents</div><article><h1 id="project-missions-preview">Project missions (preview)</h1>
7
+ <p>Enable the project-mission preview, create a mission, and review its first proposal before accepting an implementation cycle. Keep budgets and publication decisions explicit.</p>
8
+ <h2 id="start-with-a-bounded-preview">Start with a bounded preview</h2>
9
+ <p>A project assignment connects an agent team and owner mission to one repository. Give it tasks directly or enable recurring discovery. Existing Automations supplies the clock, and existing Auto team runs do the investigation, implementation, checks and independent review. The team brings opportunities and verified drafts back to the owner. It never merges or publishes automatically.</p>
10
+ <h2 id="reusable-agent-teams-and-project-assignments">Reusable agent teams and project assignments</h2>
11
+ <p>Open <strong>Project → Project missions → Reusable agent teams</strong> and choose <strong>Create agent team</strong>. Give it a name, choose its coordinator and worker/reviewer providers, and set model preferences. Optional role settings let the coordinator and workers use different models or effort for the same provider. Saving creates a versioned definition without starting agents or granting access to a repository.</p>
12
+ <p>Choose <strong>Assign to this project</strong>, select a repository and configure the mission, base branch, allowed paths, checks and budgets. Reusable-team assignments initially have <strong>Run recurring discovery</strong> turned off. Save the draft and activate it when ready. The same reusable team can be assigned to other projects with separate authority, memory and allowances. One non-archived assignment owns each underlying Git repository, including all its linked worktrees.</p>
13
+ <p>Existing missions are already assignments. <strong>Edit mission → Agent team</strong> can attach a reusable definition to one without replacing its ID, cycles, decisions, results, launch receipts or budget ledger. <strong>Save as reusable team</strong> copies only provider/model preferences from an existing assignment; it does not copy mission instructions, private checkpoints, sessions, project memory or permissions.</p>
14
+ <p>Editing a reusable team creates a new version. Assignments keep their pinned configuration until you choose a version in <strong>Edit mission</strong> or <strong>Use team version …</strong>. Each cycle and child run records its own snapshot; updates never silently change other assignments or running work. Adopting changed execution settings requires fresh verification for existing ready/accepted results and retains all prior history and charged usage.</p>
15
+ <h2 id="give-an-assigned-team-a-task">Give an assigned team a task</h2>
16
+ <p>Activate the assignment, select <strong>Give team a task</strong>, and enter a title, instructions, acceptance criteria and an allowed category. A required verification check must be configured. The task starts an implementation Auto team immediately, skipping discovery. It uses the assignment&#39;s existing scope, permissions, implementation allocation and rolling weekly allowance. It works even with recurring discovery disabled, or when discovery is set to proposals only.</p>
17
+ <p>Tasks appear alongside opportunities with <strong>Owner-assigned task</strong> attribution. They do not claim independently discovered code evidence. Checks, independent review, exact-commit approval and publication controls are the same as for discovered opportunities. A task never resets usage or inherits a previous run&#39;s sessions. Finish or stop the active cycle before assigning another task. The task form retains the exact request after an ambiguous connection failure, so retrying cannot admit the same task twice.</p>
18
+ <p>Workers submit completed artifacts; Code Flow commits and integrates them, runs the configured checks and obtains independent review. Pending engine gates belong in the worker handover, not in unresolved implementation requirements. The final check can reuse passing evidence only for the same unchanged commit, checkout and verification profile. Plain documentation changes are identified from the actual diff: checks and independent review remain required, while executable fail-to-pass proof is marked not applicable. Code, configuration, executable files, binary changes and mixed diffs retain the proof requirement.</p>
19
+ <h2 id="create-a-mission">Create a mission</h2>
20
+ <ol>
21
+ <li>Open <strong>Project → More → Automation → Pursue a mission</strong> and click <strong>Enable project missions</strong>. The choice applies immediately to every project on this host and is saved across restarts; no startup flag is required. Auto team must also be permitted by the host (<code>CODEFLOW_AUTO_TEAM_ENABLED</code> defaults to enabled).</li>
22
+ <li>Open a project that explicitly contains the repository. Select <strong>Create a mission</strong>.</li>
23
+ <li>Enter its mission, intended users, priorities, exclusions and named local base branch. Select a coordinator and worker/reviewer providers. Claude, Codex and Antigravity are eligible when installed; ACP and extension providers are currently excluded from unattended project missions.</li>
24
+ <li>Choose <strong>Build within scope</strong> and supply a required check command, or choose proposals only. Set allowed paths, categories and change limits. Models and reasoning use the existing provider catalog.</li>
25
+ <li>Review the schedule and budgets, save the draft, then <strong>Activate</strong>. Use <strong>Preview next cycle</strong> before <strong>Run cycle now</strong>.</li>
26
+ </ol>
27
+ <p><strong>Disable project missions</strong> prevents new cycles on this host. Stop active or unresolved cycles first. Individual teams keep their activation state; enabling the feature again resumes schedules for teams already active. <code>CODEFLOW_PROJECT_TEAMS_ENABLED</code> remains an optional initial default until a UI choice is saved in <code>CODEFLOW_HOME/project-teams/settings.json</code>. Separate local and SSH hosts keep their own settings.</p>
28
+ <p>The default schedule is Monday at 09:00 in the browser&#39;s time zone. Daily, selected weekdays and intervals use the existing Automations schedule editor and DST behavior. Code Flow must be running for its local scheduler to work. Cycles pin the current local branch commit; they do not fetch remote changes.</p>
29
+ <p>The default scope permits the repository except <code>.codeflow</code> and <code>.github/workflows</code>, with eight changed files and 400 added/deleted lines. Credential paths and binary changes are excluded. File bounds enforce mechanical scope; a model&#39;s risk and benefit estimates remain judgments to review.</p>
30
+ <p>Discovery reserves eight calls and 15 minutes. Implementation reserves 16 calls and 45 minutes. The rolling seven-day allowance is 48 calls and 120 minutes. Each launch reserves its full limit before starting. An exact, durable terminal-run receipt replaces that reservation with observed calls and elapsed time rounded up to whole minutes, including cancelled, failed and stopped runs. Original allocation fields and historical mission budgets remain saved. Unknown or interrupted launches remain fully reserved even after seven days; missing evidence never becomes zero usage. Legacy runs can gain additive usage receipts without resetting their history. Increase budgets deliberately in the mission editor when the defaults do not fit your cadence.</p>
31
+ <h2 id="what-a-cycle-does">What a cycle does</h2>
32
+ <p>Discovery uses read-only Auto team workers, a separate structured report turn, then an independent reviewer. It returns at most three opportunities with source quotes, affected users, a proposed change, expected benefit, risk and acceptance criteria. Empty findings are a valid result. Discovery does not run setup, checks, proof writers or code repairs.</p>
33
+ <p>The host verifies quotes at the pinned Git commit, suppresses previously reported problems, and ranks eligible proposals deterministically. Automatic implementation requires allowed category/paths, low risk, sufficient confidence/alignment, and a required verification profile. Hypotheses require the explicit experiment category. A cycle can build only one proposal; reports with uncertain evidence remain proposals.</p>
34
+ <p>Implementation uses a fresh ordinary Auto team within its reserved budget. File, path and line limits are checked before commits and publication. A result becomes <strong>ready</strong> only when required checks and the independent review refer to the final branch commit. Existing fail-to-pass proof settings still apply. Failures and stale results remain visible with a reason.</p>
35
+ <p>There is one active cycle per repository, at most two unresolved implementation results, and at most 12 open opportunities. Unchanged inputs skip agent work until the rescan interval (28 days by default). Relevant owner decisions, local activity, configuration or base changes permit new discovery. An unchanged failed automatic cycle needs an explicit owner retry or changed inputs.</p>
36
+ <h2 id="review-and-feedback">Review and feedback</h2>
37
+ <p>Project → Automation → Pursue a mission contains the full opportunity cards, cycle history, selection reasons, budgets and links to existing run diffs/checks. Project Overview and the global Inbox contain compact links to actionable mission opportunities. Their approval and evidence requirements stay the same.</p>
38
+ <ul>
39
+ <li><strong>Build proposal</strong> allocates a bounded whole Auto team. High-risk, unsupported or stale work requires a revised mission or an ordinary owner-directed task.</li>
40
+ <li><strong>Request revision</strong> records feedback and launches a fresh bounded whole team from the pinned base, with the previous result referenced as evidence. It does not silently continue a single writer or refresh the old run&#39;s allowance.</li>
41
+ <li><strong>Approve this commit</strong> accepts the exact reviewed result. Open that run to use the existing PR or merge controls. Approval alone does not ship anything. A successful local merge is recorded as shipped; opening a PR is not counted as shipped.</li>
42
+ <li><strong>Defer one week</strong> retains the idea and feedback; once due it may be rediscovered. <strong>Reject</strong> suppresses the problem in later discovery. Owners may explicitly reconsider a saved proposal.</li>
43
+ <li><strong>Pause</strong> prevents new cycles and the next implementation stage. An already running discovery may finish into proposals. <strong>Stop cycle</strong> cancels owned work, retaining unresolved reservations. <strong>Archive team</strong> stops scheduling and retains its history.</li>
44
+ </ul>
45
+ <p>Changing execution policy makes previously ready/accepted results require new verification. Changing only the schedule, recurring-discovery toggle or assignment name preserves those results and can be done during a cycle. The current schedule is stored separately; historical mission and cycle snapshots retain their original timing. Full-mission schedule updates from older clients receive the same behavior. Moving a result branch after review invalidates readiness. Generic run resumes, selective reruns, writer follow-ups, automatic PR-fix watchers and triage revision shortcuts are blocked for managed runs; use the project mission&#39;s revision controls.</p>
46
+ <p>Project mission runs can be archived individually or in a sidebar selection. They cannot be deleted: cycle recovery, budgets and exact-result approvals retain their run history. Ordinary runs still support individual and bulk deletion. The mission editor&#39;s searchable model picker includes the same free-model filter and badges as the composer; its selections update only that team&#39;s mission.</p>
47
+ <p>Existing notification destinations receive actionable cycle outcomes using their saved event/project scope. Child completions and no-op cycles do not produce duplicate alerts. Destinations remain opt-in.</p>
48
+ <h2 id="recovery-and-storage">Recovery and storage</h2>
49
+ <p>Team aggregates are private files under <code>$CODEFLOW_HOME/project-teams/</code>. Each mutation validates and fsyncs its snapshot before acknowledgment. A cycle claim and its full budget allocation are saved before starting a run; the initial run identity is fsynced and attached to the claim before any agent dispatch.</p>
50
+ <p>Recovery adopts only a matching team/cycle/claim/input/attempt receipt. An ambiguous launch is marked <strong>unknown</strong> and is never automatically replayed. Inspect its run and host process state, then stop the cycle if abandoning it; stopping does not pretend unknown usage is zero. A storage error remains visible, and corrupt team files are preserved for repair. Duplicate repository ownership blocks both records.</p>
51
+ <p>On first load, legacy assignments gain a shared Git metadata identity. This additive upgrade preserves their IDs, immutable mission/cycle history, operation receipts and usage. Linked worktree aliases cannot acquire separate ownership. Replacing a repository&#39;s Git metadata blocks dispatch rather than silently adopting the replacement. Reusable definitions are separate <code>at-*.json</code> files in the same directory, with at most 100 definitions, 100 versions per definition and a 2 MiB per-definition ceiling; damaged definitions are preserved and reported without preventing unrelated existing missions from loading.</p>
52
+ <p>Automations stores only a managed target and a display projection. Mission settings remain authoritative in the team aggregate. Managed schedules cannot be edited through generic automation controls. Schedule occurrences use stable operation IDs, so replaying a due occurrence cannot launch a second cycle. The existing one-hour missed-run grace and DST rules apply.</p>
53
+ <p>History is bounded to 100 cycles, 200 opportunities, 2,000 decisions and 2,000 operation receipts, with a 16 MiB aggregate ceiling. At the limit, archive the team and retain its file before creating a replacement. History is not silently pruned; rejection feedback is never silently forgotten within a team.</p>
54
+ <p>Backups include team evidence and missions. Restore pauses teams, cancels active cycle admission while retaining unknown reservations, and invalidates ready/accepted results. Inspect repository membership, providers and retained receipts before reactivation. ACP executable settings and other existing credential exclusions remain excluded from portable backups.</p>
55
+ <p>Owner APIs, managed child runs and the project-scoped event topic are unavailable to shared accounts, because the child tasks include private owner mission and decision context. Custom filesystem restrictions block the feature alongside other host execution/private-data surfaces. Removing project membership stops owned work. There is no cloud scheduler or new agent runtime.</p>
56
+ <h2 id="api">API</h2>
57
+ <p>All mutations use a client-generated <code>operationId</code>. Team edits and opportunity decisions require the current <code>revision</code>; opportunity decisions also require <code>opportunityRevision</code>. A replay with the same operation and content is idempotent; changing its content or acting on a stale revision returns a conflict.</p>
58
+ <div class="table-scroll" tabindex="0"><table>
59
+ <thead>
60
+ <tr>
61
+ <th>Method and path</th>
62
+ <th>Purpose</th>
63
+ </tr>
64
+ </thead>
65
+ <tbody><tr>
66
+ <td><code>GET /api/project-teams?project=ID</code></td>
67
+ <td>Scoped assignments, reusable team summaries, storage faults and provider eligibility</td>
68
+ </tr>
69
+ <tr>
70
+ <td><code>GET /api/project-teams/definitions</code></td>
71
+ <td>Reusable team summaries and definition storage faults</td>
72
+ </tr>
73
+ <tr>
74
+ <td><code>GET /api/project-teams/definitions/:id</code></td>
75
+ <td>One definition and its retained versions</td>
76
+ </tr>
77
+ <tr>
78
+ <td><code>POST /api/project-teams/definitions</code></td>
79
+ <td>Create from name/configuration, or name/sourceTeamId</td>
80
+ </tr>
81
+ <tr>
82
+ <td><code>POST /api/project-teams/definitions/:id</code></td>
83
+ <td>Save a new version with revision, name and configuration</td>
84
+ </tr>
85
+ <tr>
86
+ <td><code>POST /api/project-teams</code></td>
87
+ <td>Create a draft with projectId, repo, name, mission, optional definition <code>{id, revision}</code> and scheduleEnabled</td>
88
+ </tr>
89
+ <tr>
90
+ <td><code>GET /api/project-teams/:id</code></td>
91
+ <td>Aggregate and remaining allowance</td>
92
+ </tr>
93
+ <tr>
94
+ <td><code>POST /api/project-teams/:id</code></td>
95
+ <td>Update mission/name/status, schedule/scheduleEnabled or adopt a definition with revision; definition <code>null</code> detaches the reusable reference while keeping configuration</td>
96
+ </tr>
97
+ <tr>
98
+ <td><code>POST /api/project-teams/:id/tasks</code></td>
99
+ <td>Admit an owner task with revision, title, instructions, acceptance array and optional category</td>
100
+ </tr>
101
+ <tr>
102
+ <td><code>GET /api/project-teams/:id/preview</code></td>
103
+ <td>Readiness and schedule preview without model calls</td>
104
+ </tr>
105
+ <tr>
106
+ <td><code>POST /api/project-teams/:id/cycle</code></td>
107
+ <td>Explicit cycle admission</td>
108
+ </tr>
109
+ <tr>
110
+ <td><code>POST /api/project-teams/:id/stop</code></td>
111
+ <td>Stop owned cycle with revision</td>
112
+ </tr>
113
+ <tr>
114
+ <td><code>POST /api/project-teams/:id/opportunities/:opportunityId</code></td>
115
+ <td>approve, build, revise, reject or defer</td>
116
+ </tr>
117
+ </tbody></table>
118
+ </div><p>The existing stream broker multiplexes <code>project-teams:&lt;projectId&gt;</code>. Generic run bodies cannot supply managed metadata or launch callbacks.</p>
119
+ <h2 id="validation-and-rollout">Validation and rollout</h2>
120
+ <p><code>npm run evaluate:project-teams -- --fake --cycles 10 --out /tmp/my-standing-pilot</code> exercises two isolated fixture repositories and saves a report plus private run evidence. The default is synthetic. <code>--real --confirm</code> explicitly opts into signed-in CLI use, capped at 24 invocations and 60 allocated minutes per cycle. Use <code>--help</code> first. Neither mode merges or pushes.</p>
121
+ <p>Tests cover the full cycle, exact-commit approval, scope violations, failed checks, provider exclusions, budget limits, duplicate admission, durable receipt failure, restart adoption/ambiguity, cancellation, membership removal, feedback retention, storage corruption, restored authority, notifications, owner-only APIs, filesystem restrictions and shared browser transport.</p>
122
+ <p>The initial synthetic ten-cycle pilot produced two ready drafts and eight no-ops across two fixture repositories. It establishes mechanics only. Real-provider quality, novelty, usefulness and owner acceptance have not been measured; keep the flag opt-in until that separate pilot is assessed.</p>
123
+ <hr>
124
+ <p><a href="index.html">Documentation library</a> · <a href="getting-started.html">Getting started</a> · <a href="help.html">Ask code-flow</a></p>
125
+ </article><footer><a href="https://github.com/midhunxavier/code-flow/blob/main/docs/project-teams.md">Edit this page on GitHub ↗</a><span>code-flow · 0.1.0-preview.3 · <a href="font-license.txt">Font license</a></span></footer><nav class="pagination" aria-label="Adjacent guides"><a href="auto-team.html"><small>← Previous</small>Team</a><a href="review-inbox.html"><small>Next →</small>Review inbox</a></nav></main>
126
+ <aside class="on-page" aria-label="On this page"><strong>On this page</strong><a class="depth-2" href="#start-with-a-bounded-preview">Start with a bounded preview</a><a class="depth-2" href="#reusable-agent-teams-and-project-assignments">Reusable agent teams and project assignments</a><a class="depth-2" href="#give-an-assigned-team-a-task">Give an assigned team a task</a><a class="depth-2" href="#create-a-mission">Create a mission</a><a class="depth-2" href="#what-a-cycle-does">What a cycle does</a><a class="depth-2" href="#review-and-feedback">Review and feedback</a><a class="depth-2" href="#recovery-and-storage">Recovery and storage</a><a class="depth-2" href="#api">API</a><a class="depth-2" href="#validation-and-rollout">Validation and rollout</a></aside>
127
+ <aside id="help-panel" hidden aria-labelledby="help-title"><div class="chat-heading"><div><span class="eyebrow">Your AI companion</span><h2 id="help-title">Ask code-flow</h2></div><button id="close-help" aria-label="Close AI companion">✕</button></div><div class="chat-toolbar"><span>Grounded in your docs</span><button id="new-chat">New chat</button></div><div id="help-messages" role="log" aria-label="Help conversation" aria-live="polite"><div id="chat-welcome"><span class="chat-mark" aria-hidden="true">✦</span><h3>What would you like to do?</h3><p>Let’s find your next step. Ask about setup, workflows or something that’s unclear.</p><div class="suggestions"><button type="button" data-question="How do I start my first run?">Start my first run ↗</button><button type="button" data-question="What should I do when a check fails?">Understand a failed check ↗</button></div></div></div><p id="help-status" role="status">Checking your installed CLIs…</p><button id="retry-help" hidden>Retry connection</button><form id="help-form" hidden><label class="sr-only" for="question">Your question</label><textarea id="question" rows="3" maxlength="4000" placeholder="Ask a question…" required></textarea><div class="composer-controls"><label class="sr-only" for="help-agent">Use your CLI</label><select id="help-agent"></select><button type="button" id="stop-help" hidden>Stop</button><button class="primary" id="send-help" aria-label="Send message">Send ↗</button></div><small>Uses your CLI login and quota. Shift + Enter for a new line.</small></form><a id="help-guide" href="help.html">About your local companion →</a></aside></div>
128
+ <dialog id="search-dialog" aria-labelledby="search-title"><div class="dialog-title"><h2 id="search-title">Search documentation</h2><button data-close="search-dialog" aria-label="Close search">✕</button></div><label class="sr-only" for="search">Search all guides</label><input id="search" type="search" placeholder="Search workflows, settings, troubleshooting…" autocomplete="off"><div id="search-results" aria-live="polite"></div></dialog>
129
+ </body></html>
package/public/docs/provider-compatibility.html ADDED
@@ -0,0 +1,20 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Provider compatibility — code-flow guides and reference"><title>Provider compatibility · code-flow</title><link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K"><link rel="stylesheet" href="style.css"><script src="app.js" defer></script></head>
3
+ <body data-page="provider-compatibility"><a class="skip-link" href="#content">Skip to content</a>
4
+ <header class="topbar"><a class="brand" href="index.html"><img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K" width="30" height="30" alt=""><strong>Code Flow</strong><span>Docs</span></a><button class="search-trigger" id="open-search">Search documentation <kbd>⌘ K</kbd></button><div class="top-actions"><a href="https://github.com/midhunxavier/code-flow">GitHub ↗</a><button id="theme" aria-label="Change color theme">Theme</button><button id="open-help" class="primary" hidden aria-expanded="false" aria-controls="help-panel">Ask code-flow</button><button id="menu" aria-label="Toggle documentation navigation" aria-expanded="false" aria-controls="sidebar">☰</button></div></header>
5
+ <div class="layout"><nav class="sidebar" id="sidebar" aria-label="Documentation"><section><h2>Get started</h2><a href="index.html" >Overview</a><a href="installation.html" >Install Code Flow preview</a><a href="getting-started.html" >Getting started</a><a href="patterns.html" >Team patterns</a><a href="acp-agents.html" >ACP coding agents</a><a href="help.html" >Ask code-flow</a></section><section><h2>Work with agents</h2><a href="runs.html" >Runs and workspace</a><a href="auto-team.html" >Team</a><a href="project-teams.html" >Project missions (preview)</a><a href="review-inbox.html" >Review inbox</a><a href="verification.html" >Verification and review</a><a href="github.html" >GitHub, review and shipping</a><a href="github-review-threads.html" >GitHub review threads</a><a href="task-reruns.html" >Selective task reruns</a><a href="deferred-runs.html" >Deferred runs</a></section><section><h2>Your workspace</h2><a href="configuration.html" >Configuration</a><a href="context-inspection.html" >Context and budgets</a><a href="project-conventions.html" >Versioned project conventions</a><a href="checkpoint-review.html" >Checkpoints and reversions</a><a href="launch-profiles.html" >Service launch profiles</a><a href="code-intelligence.html" >Code intelligence</a><a href="architecture-explorer.html" >Architecture explorer</a><a href="memory-storage.html" >Project memory</a><a href="memory-claims.html" >Semantic claim review</a><a href="coordinated-changes.html" >Coordinated changes</a></section><section><h2>Connect and collaborate</h2><a href="team-collaboration.html" >Team collaboration</a><a href="shared-projects.html" >Shared project accounts</a><a href="ssh-projects.html" >SSH projects</a><a href="remote-workers.html" >Remote agent workers</a><a href="code-hosts.html" >GitLab and Bitbucket code workflows</a><a href="external-sources.html" >Read-only external sources</a><a href="automations.html" >Automations and away mode</a><a href="notifications.html" >Outbound notifications</a></section><section><h2>Operate safely</h2><a href="security.html" >Security, subscriptions and caveats</a><a href="filesystem-policy.html" >Project filesystem policy</a><a href="agent-containers.html" >Agent containers</a><a href="filtered-tasks.html" >Filtered Docker tasks</a><a href="dependency-discovery.html" >Dependency discovery</a><a href="maintenance.html" >Backup and maintenance</a></section><section><h2>Build and extend</h2><a href="architecture.html" >Architecture and development</a><a href="api.html" >Local API and command-line client</a><a href="extensions.html" >Provider and workflow extensions</a><a href="provider-compatibility.html" aria-current="page">Provider compatibility</a><a href="accessibility.html" >Accessibility acceptance</a><a href="performance.html" >Performance</a><a href="run-storage.html" >Run storage</a><a href="documentation.html" >Documentation and GitHub Pages</a><a href="releasing.html" >Preparing a preview release</a><a href="vscode.html" >Code Flow for VS Code</a></section><section><h2>Engineering records</h2><a href="application-improvements.html" >Application improvement program</a><a href="project-first-navigation-plan.html" >Project navigation review and implementation plan</a><a href="dynamic-teams-evaluation.html" >Dynamic teams: implementation evidence and rollout decision</a><a href="dynamic-teams-implementation-plan.html" >Dynamic teams, workflows, messaging, and memory</a><a href="dynamic-teams-implementation-review-1.html" >Review 1: the dynamic teams implementation</a><a href="worker-permission-verification.html" >Live worker permission verification</a><a href="dynamic-teams-plan-review-0.html" >Review 0: Dynamic teams implementation plan</a><a href="project-teams-implementation-plan.html" >Standing project teams implementation plan</a><a href="performance-results.html" >Measured performance: 19 October 2026</a></section><a class="app-link" id="back-app" hidden href="/">← Back to app</a></nav>
6
+ <main id="content" tabindex="-1"><div class="breadcrumb">Documentation <span>/</span> Build and extend</div><article><h1 id="provider-compatibility">Provider compatibility</h1>
7
+ <p>Run the provider diagnostics when an installed CLI stops accepting an invocation. Protocol fixtures and live version/help probes provide different evidence; a fixture passing does not verify a real provider login.</p>
8
+ <h2 id="check-the-installed-cli">Check the installed CLI</h2>
9
+ <p>The Provider compatibility workflow runs on adapter changes, pushes to main, manual dispatch and weekly. It installs official Claude Code 2.1.300/2.1.302 and Codex 0.162.0/0.162.1 in isolated directories, plus the current official Linux x64 Antigravity build. Antigravity downloads are verified against the SHA-512 checksum in the official updater manifest. The exact observed version, platform, Node version, timestamp, required flags and missing capabilities are retained in a 30-day JSON artifact per matrix entry. A missing required flag, unknown probe or unexpected pinned version fails its job.</p>
10
+ <p>These real binary probes run <code>--version</code> and <code>--help</code> only with a new empty home and no account credentials. npm installs use the explicit public registry and empty user/global configuration, and probes execute the installed absolute binary path rather than falling back to a host CLI. Pinned versions compare complete semantic versions. They never sign in, list account models, ask an agent to perform work or spend inference quota. Installing an official package may run its vendor installer. Maintained process fixtures separately exercise stream normalization, error typing, structured results, sessions, cancellation and Codex app-server behavior. Help compatibility and fixture success do not prove live account/inference behavior.</p>
11
+ <p>Run a pinned probe locally with <code>node --import tsx scripts/check-provider-compatibility.ts codex 0.162.1 /tmp/codex-compatibility.json</code>. The current Antigravity channel probe runs on Linux x64/arm64 (glibc or musl). Successful probes define evidence for those exact versions; versions outside the matrix remain untested and installed health checks still apply. Update pins explicitly after reviewing release notes and the reports. CI must run on GitHub before its scheduled evidence is available.</p>
12
+ <p>Vendor references: <a href="https://github.com/anthropics/claude-code/releases">Claude Code releases</a>, <a href="https://github.com/openai/codex/releases">Codex releases</a>, <a href="https://antigravity.google/docs/cli/install/">Antigravity installation</a>.</p>
13
+ <p>Local acceptance on October 18, 2026 passed official Claude Code 2.1.300/2.1.302 and Codex 0.162.0/0.162.1 probes on macOS arm64, plus the official current Antigravity 1.4.2 binary in an isolated Linux arm64 musl Docker container. Exact receipts are in <a href="https://github.com/midhunxavier/code-flow/blob/main/docs/provider-compatibility-evidence.json">provider-compatibility-evidence.json</a>. Linux x64 CI execution remains a separate platform check.</p>
14
+ <hr>
15
+ <p><a href="index.html">Documentation library</a> · <a href="getting-started.html">Getting started</a> · <a href="help.html">Ask code-flow</a></p>
16
+ </article><footer><a href="https://github.com/midhunxavier/code-flow/blob/main/docs/provider-compatibility.md">Edit this page on GitHub ↗</a><span>code-flow · 0.1.0-preview.3 · <a href="font-license.txt">Font license</a></span></footer><nav class="pagination" aria-label="Adjacent guides"><a href="extensions.html"><small>← Previous</small>Provider and workflow extensions</a><a href="accessibility.html"><small>Next →</small>Accessibility acceptance</a></nav></main>
17
+ <aside class="on-page" aria-label="On this page"><strong>On this page</strong><a class="depth-2" href="#check-the-installed-cli">Check the installed CLI</a></aside>
18
+ <aside id="help-panel" hidden aria-labelledby="help-title"><div class="chat-heading"><div><span class="eyebrow">Your AI companion</span><h2 id="help-title">Ask code-flow</h2></div><button id="close-help" aria-label="Close AI companion">✕</button></div><div class="chat-toolbar"><span>Grounded in your docs</span><button id="new-chat">New chat</button></div><div id="help-messages" role="log" aria-label="Help conversation" aria-live="polite"><div id="chat-welcome"><span class="chat-mark" aria-hidden="true">✦</span><h3>What would you like to do?</h3><p>Let’s find your next step. Ask about setup, workflows or something that’s unclear.</p><div class="suggestions"><button type="button" data-question="How do I start my first run?">Start my first run ↗</button><button type="button" data-question="What should I do when a check fails?">Understand a failed check ↗</button></div></div></div><p id="help-status" role="status">Checking your installed CLIs…</p><button id="retry-help" hidden>Retry connection</button><form id="help-form" hidden><label class="sr-only" for="question">Your question</label><textarea id="question" rows="3" maxlength="4000" placeholder="Ask a question…" required></textarea><div class="composer-controls"><label class="sr-only" for="help-agent">Use your CLI</label><select id="help-agent"></select><button type="button" id="stop-help" hidden>Stop</button><button class="primary" id="send-help" aria-label="Send message">Send ↗</button></div><small>Uses your CLI login and quota. Shift + Enter for a new line.</small></form><a id="help-guide" href="help.html">About your local companion →</a></aside></div>
19
+ <dialog id="search-dialog" aria-labelledby="search-title"><div class="dialog-title"><h2 id="search-title">Search documentation</h2><button data-close="search-dialog" aria-label="Close search">✕</button></div><label class="sr-only" for="search">Search all guides</label><input id="search" type="search" placeholder="Search workflows, settings, troubleshooting…" autocomplete="off"><div id="search-results" aria-live="polite"></div></dialog>
20
+ </body></html>
package/public/docs/releasing.html ADDED
@@ -0,0 +1,65 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Preparing a preview release — code-flow guides and reference"><title>Preparing a preview release · code-flow</title><link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K"><link rel="stylesheet" href="style.css"><script src="app.js" defer></script></head>
3
+ <body data-page="releasing"><a class="skip-link" href="#content">Skip to content</a>
4
+ <header class="topbar"><a class="brand" href="index.html"><img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K" width="30" height="30" alt=""><strong>Code Flow</strong><span>Docs</span></a><button class="search-trigger" id="open-search">Search documentation <kbd>⌘ K</kbd></button><div class="top-actions"><a href="https://github.com/midhunxavier/code-flow">GitHub ↗</a><button id="theme" aria-label="Change color theme">Theme</button><button id="open-help" class="primary" hidden aria-expanded="false" aria-controls="help-panel">Ask code-flow</button><button id="menu" aria-label="Toggle documentation navigation" aria-expanded="false" aria-controls="sidebar">☰</button></div></header>
5
+ <div class="layout"><nav class="sidebar" id="sidebar" aria-label="Documentation"><section><h2>Get started</h2><a href="index.html" >Overview</a><a href="installation.html" >Install Code Flow preview</a><a href="getting-started.html" >Getting started</a><a href="patterns.html" >Team patterns</a><a href="acp-agents.html" >ACP coding agents</a><a href="help.html" >Ask code-flow</a></section><section><h2>Work with agents</h2><a href="runs.html" >Runs and workspace</a><a href="auto-team.html" >Team</a><a href="project-teams.html" >Project missions (preview)</a><a href="review-inbox.html" >Review inbox</a><a href="verification.html" >Verification and review</a><a href="github.html" >GitHub, review and shipping</a><a href="github-review-threads.html" >GitHub review threads</a><a href="task-reruns.html" >Selective task reruns</a><a href="deferred-runs.html" >Deferred runs</a></section><section><h2>Your workspace</h2><a href="configuration.html" >Configuration</a><a href="context-inspection.html" >Context and budgets</a><a href="project-conventions.html" >Versioned project conventions</a><a href="checkpoint-review.html" >Checkpoints and reversions</a><a href="launch-profiles.html" >Service launch profiles</a><a href="code-intelligence.html" >Code intelligence</a><a href="architecture-explorer.html" >Architecture explorer</a><a href="memory-storage.html" >Project memory</a><a href="memory-claims.html" >Semantic claim review</a><a href="coordinated-changes.html" >Coordinated changes</a></section><section><h2>Connect and collaborate</h2><a href="team-collaboration.html" >Team collaboration</a><a href="shared-projects.html" >Shared project accounts</a><a href="ssh-projects.html" >SSH projects</a><a href="remote-workers.html" >Remote agent workers</a><a href="code-hosts.html" >GitLab and Bitbucket code workflows</a><a href="external-sources.html" >Read-only external sources</a><a href="automations.html" >Automations and away mode</a><a href="notifications.html" >Outbound notifications</a></section><section><h2>Operate safely</h2><a href="security.html" >Security, subscriptions and caveats</a><a href="filesystem-policy.html" >Project filesystem policy</a><a href="agent-containers.html" >Agent containers</a><a href="filtered-tasks.html" >Filtered Docker tasks</a><a href="dependency-discovery.html" >Dependency discovery</a><a href="maintenance.html" >Backup and maintenance</a></section><section><h2>Build and extend</h2><a href="architecture.html" >Architecture and development</a><a href="api.html" >Local API and command-line client</a><a href="extensions.html" >Provider and workflow extensions</a><a href="provider-compatibility.html" >Provider compatibility</a><a href="accessibility.html" >Accessibility acceptance</a><a href="performance.html" >Performance</a><a href="run-storage.html" >Run storage</a><a href="documentation.html" >Documentation and GitHub Pages</a><a href="releasing.html" aria-current="page">Preparing a preview release</a><a href="vscode.html" >Code Flow for VS Code</a></section><section><h2>Engineering records</h2><a href="application-improvements.html" >Application improvement program</a><a href="project-first-navigation-plan.html" >Project navigation review and implementation plan</a><a href="dynamic-teams-evaluation.html" >Dynamic teams: implementation evidence and rollout decision</a><a href="dynamic-teams-implementation-plan.html" >Dynamic teams, workflows, messaging, and memory</a><a href="dynamic-teams-implementation-review-1.html" >Review 1: the dynamic teams implementation</a><a href="worker-permission-verification.html" >Live worker permission verification</a><a href="dynamic-teams-plan-review-0.html" >Review 0: Dynamic teams implementation plan</a><a href="project-teams-implementation-plan.html" >Standing project teams implementation plan</a><a href="performance-results.html" >Measured performance: 19 October 2026</a></section><a class="app-link" id="back-app" hidden href="/">← Back to app</a></nav>
6
+ <main id="content" tabindex="-1"><div class="breadcrumb">Documentation <span>/</span> Build and extend</div><article><h1 id="preparing-a-preview-release">Preparing a preview release</h1>
7
+ <p>The source repository stays private to npm publishing (<code>private: true</code>). The release builder creates a separate, publishable package in <code>dist/npm</code> with compiled JavaScript, UI, local docs, workers, SSH helpers and licenses. It has no install scripts or runtime npm dependencies. The npm package and macOS app use that same runtime.</p>
8
+ <h2 id="build-and-validate">Build and validate</h2>
9
+ <p>Update the root package version and lockfile to a new <code>x.y.z-preview.N</code> value, then run:</p>
10
+ <pre><code class="language-sh">npm ci
11
+ npm run typecheck
12
+ npm test
13
+ npm run release:prepare
14
+ npm run test:package
15
+ </code></pre>
16
+ <p><code>release:prepare</code> writes the npm tarball, SHA-256 checksum, generated Homebrew formula and draft release notes to <code>output/releases</code>. The packaging acceptance test installs that actual tarball in a temporary directory outside the checkout, starts the server, checks the browser opener and bundled docs/assets, exercises the semantic worker, then verifies graceful shutdown and headless startup. It uses fake agent CLIs and never spends provider quota.</p>
17
+ <p>Inspect the package before publishing:</p>
18
+ <pre><code class="language-sh">npm pack ./dist/npm --dry-run
19
+ node dist/npm/bin/codeflow.mjs --help
20
+ </code></pre>
21
+ <p>The <strong>Preview release</strong> GitHub workflow builds and tests the tarball on macOS and Linux, builds both macOS architectures, and creates a <strong>draft prerelease</strong> with the exact artifacts. It accepts an existing Git ref and checks that its version matches the requested tag. It does not publish npm or create a Homebrew tap. Run it against a committed, reviewed release ref.</p>
22
+ <h2 id="npm-preview-channel">npm preview channel</h2>
23
+ <p>The published package is scoped as <code>@midhunxavier/code-flow</code> because npm rejected the unscoped name as too similar to the existing <code>codeflow</code> package. The installed commands remain <code>codeflow</code> and <code>code-flow</code>.</p>
24
+ <p>Authenticate to the npm account that owns <code>@midhunxavier/code-flow</code>. On first publication, confirm the package name is available and that you are publishing from the intended account. Then publish the tested tarball:</p>
25
+ <pre><code class="language-sh">npm whoami
26
+ npm publish output/releases/midhunxavier-code-flow-0.1.0-preview.3.tgz --tag preview --access public
27
+ npm view @midhunxavier/code-flow@preview version
28
+ </code></pre>
29
+ <p>Use the actual version&#39;s filename when publishing subsequent previews. Never publish this preview with the <code>latest</code> tag. The staged package also sets <code>publishConfig.tag</code> to <code>preview</code>. Test <code>npx @midhunxavier/code-flow@preview</code> from a clean directory after registry publication.</p>
30
+ <h2 id="macos-dmg">macOS DMG</h2>
31
+ <p>Build on macOS with Xcode Command Line Tools installed:</p>
32
+ <pre><code class="language-sh">npm run package:macos -- arm64
33
+ npm run package:macos -- x64
34
+ npm run test:macos
35
+ </code></pre>
36
+ <p>The builder downloads an official Node runtime with a pinned SHA-256, packages a pinned Electron runtime with the prepared backend and Node license, compiles the native computer-use helper, and creates a drag-to-Applications DMG. The app requires macOS 13+. Its sandboxed renderer has no Node access, and the separate local backend survives window reloads and closing. Lifecycle tests launch the actual packaged app, verify renderer isolation and backend continuity, and check normal quit and crash cleanup. Both architectures are tested on matching GitHub runners. Git and the agent CLIs remain user-installed. The launcher reads the login shell&#39;s PATH to find common CLI and version-manager installations.</p>
37
+ <p>Without signing credentials the output is explicitly named <code>-unnotarized.dmg</code>. These builds are for developer testing; do not describe them as signed, notarized or Gatekeeper approved.</p>
38
+ <p>For distributable DMGs, install a <strong>Developer ID Application</strong> identity in the build keychain and save notarization credentials with <code>xcrun notarytool store-credentials</code>. Set:</p>
39
+ <pre><code class="language-sh">export CODEFLOW_SIGN_IDENTITY=&#39;Developer ID Application: Your Name (TEAMID)&#39;
40
+ export CODEFLOW_NOTARY_PROFILE=&#39;code-flow-notary&#39;
41
+ npm run package:macos -- arm64
42
+ npm run package:macos -- x64
43
+ </code></pre>
44
+ <p>The builder signs Node with its JIT entitlements, signs the app and DMG, submits to Apple&#39;s notarization service, staples the ticket, and verifies the result. Never commit certificates, credentials or keychain files.</p>
45
+ <h3 id="desktop-updates">Desktop updates</h3>
46
+ <p>Signed and notarized builds also produce <code>code-flow-VERSION-macos-ARCH.zip</code>, its SHA-256 file, and <code>releases-ARCH.json</code>. The ZIP contains the notarized, stapled app; the feed uses Electron&#39;s <a href="https://www.electronjs.org/docs/latest/tutorial/updates">Squirrel JSON format</a> with a version, exact asset URL, checksum and size. The release workflow attaches these automatically. Publish the DMG, ZIP and feed together under the matching <code>vVERSION</code> GitHub release, and keep the same Developer ID signing identity across updates. Unnotarized builds never produce a native update feed.</p>
47
+ <p>The desktop main process checks public GitHub releases on launch, every six hours, and on demand. It compares stable/preview versions numerically, skips drafts and missing architecture assets, and never selects an older version. It downloads through Electron&#39;s native updater only after the user chooses <strong>Download update</strong>. Restarting uses the normal active-agent confirmation and backend shutdown. Unnotarized installations offer the matching DMG instead. No GitHub token is needed, and browser/npm clients have no desktop update controls.</p>
48
+ <p>Before publishing the first signed updater release, install it in Applications and test updating to a second signed version on both architectures. Unit and lifecycle tests cover release selection, failure/retry states, bridge isolation and restart cancellation; only this two-version acceptance check validates Apple&#39;s signing/notarization and Squirrel&#39;s actual app replacement. Existing desktop previews without the updater need a manual upgrade to acquire it.</p>
49
+ <p>The GitHub workflow can import the following repository secrets into a temporary build keychain: <code>MACOS_CERTIFICATE_BASE64</code>, <code>MACOS_CERTIFICATE_PASSWORD</code>, <code>MACOS_SIGN_IDENTITY</code>, <code>APPLE_ID</code>, <code>APPLE_TEAM_ID</code> and <code>APPLE_APP_PASSWORD</code>. Supply all six for signed and notarized builds; with none set, it produces clearly labeled unnotarized developer builds. Partial credential configuration fails instead of silently dropping signing.</p>
50
+ <h2 id="homebrew">Homebrew</h2>
51
+ <p><code>release:prepare</code> generates <code>output/releases/Formula/code-flow.rb</code> from the actual npm tarball&#39;s SHA-256. After the GitHub prerelease assets are published, copy this formula into <code>Formula/code-flow.rb</code> in the <code>midhunxavier/homebrew-code-flow</code> repository, then test:</p>
52
+ <pre><code class="language-sh">brew install --build-from-source midhunxavier/code-flow/code-flow
53
+ brew test midhunxavier/code-flow/code-flow
54
+ codeflow --version
55
+ </code></pre>
56
+ <p>The tap must exist and contain the generated formula before advertising the Homebrew command as available. Regenerate the formula whenever the tarball changes; it references the GitHub release asset, so npm registry availability is independent.</p>
57
+ <h2 id="publish-the-github-prerelease">Publish the GitHub prerelease</h2>
58
+ <p>Review the draft notes and attached checksums. Verify each DMG&#39;s signing status and label it accurately. Publish the draft as a <strong>prerelease</strong>, leaving the stable latest release unchanged. The draft notes include an exact GitHub tarball command so the preview can be tried even before the npm channel is available.</p>
59
+ <p>Keep platform claims precise: macOS and Linux are supported; Windows users use WSL2. Native Windows execution is not supported. On a real Windows machine, confirm WSL networking and the Windows browser opener before claiming end-to-end Windows validation.</p>
60
+ <p><a href="index.html">Documentation library</a> · <a href="installation.html">Installation</a></p>
61
+ </article><footer><a href="https://github.com/midhunxavier/code-flow/blob/main/docs/releasing.md">Edit this page on GitHub ↗</a><span>code-flow · 0.1.0-preview.3 · <a href="font-license.txt">Font license</a></span></footer><nav class="pagination" aria-label="Adjacent guides"><a href="documentation.html"><small>← Previous</small>Documentation and GitHub Pages</a><a href="application-improvements.html"><small>Next →</small>Application improvement program</a></nav></main>
62
+ <aside class="on-page" aria-label="On this page"><strong>On this page</strong><a class="depth-2" href="#build-and-validate">Build and validate</a><a class="depth-2" href="#npm-preview-channel">npm preview channel</a><a class="depth-2" href="#macos-dmg">macOS DMG</a><a class="depth-3" href="#desktop-updates">Desktop updates</a><a class="depth-2" href="#homebrew">Homebrew</a><a class="depth-2" href="#publish-the-github-prerelease">Publish the GitHub prerelease</a></aside>
63
+ <aside id="help-panel" hidden aria-labelledby="help-title"><div class="chat-heading"><div><span class="eyebrow">Your AI companion</span><h2 id="help-title">Ask code-flow</h2></div><button id="close-help" aria-label="Close AI companion">✕</button></div><div class="chat-toolbar"><span>Grounded in your docs</span><button id="new-chat">New chat</button></div><div id="help-messages" role="log" aria-label="Help conversation" aria-live="polite"><div id="chat-welcome"><span class="chat-mark" aria-hidden="true">✦</span><h3>What would you like to do?</h3><p>Let’s find your next step. Ask about setup, workflows or something that’s unclear.</p><div class="suggestions"><button type="button" data-question="How do I start my first run?">Start my first run ↗</button><button type="button" data-question="What should I do when a check fails?">Understand a failed check ↗</button></div></div></div><p id="help-status" role="status">Checking your installed CLIs…</p><button id="retry-help" hidden>Retry connection</button><form id="help-form" hidden><label class="sr-only" for="question">Your question</label><textarea id="question" rows="3" maxlength="4000" placeholder="Ask a question…" required></textarea><div class="composer-controls"><label class="sr-only" for="help-agent">Use your CLI</label><select id="help-agent"></select><button type="button" id="stop-help" hidden>Stop</button><button class="primary" id="send-help" aria-label="Send message">Send ↗</button></div><small>Uses your CLI login and quota. Shift + Enter for a new line.</small></form><a id="help-guide" href="help.html">About your local companion →</a></aside></div>
64
+ <dialog id="search-dialog" aria-labelledby="search-title"><div class="dialog-title"><h2 id="search-title">Search documentation</h2><button data-close="search-dialog" aria-label="Close search">✕</button></div><label class="sr-only" for="search">Search all guides</label><input id="search" type="search" placeholder="Search workflows, settings, troubleshooting…" autocomplete="off"><div id="search-results" aria-live="polite"></div></dialog>
65
+ </body></html>
package/public/docs/remote-workers.html ADDED
@@ -0,0 +1,64 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Remote agent workers — code-flow guides and reference"><title>Remote agent workers · code-flow</title><link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K"><link rel="stylesheet" href="style.css"><script src="app.js" defer></script></head>
3
+ <body data-page="remote-workers"><a class="skip-link" href="#content">Skip to content</a>
4
+ <header class="topbar"><a class="brand" href="index.html"><img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K" width="30" height="30" alt=""><strong>Code Flow</strong><span>Docs</span></a><button class="search-trigger" id="open-search">Search documentation <kbd>⌘ K</kbd></button><div class="top-actions"><a href="https://github.com/midhunxavier/code-flow">GitHub ↗</a><button id="theme" aria-label="Change color theme">Theme</button><button id="open-help" class="primary" hidden aria-expanded="false" aria-controls="help-panel">Ask code-flow</button><button id="menu" aria-label="Toggle documentation navigation" aria-expanded="false" aria-controls="sidebar">☰</button></div></header>
5
+ <div class="layout"><nav class="sidebar" id="sidebar" aria-label="Documentation"><section><h2>Get started</h2><a href="index.html" >Overview</a><a href="installation.html" >Install Code Flow preview</a><a href="getting-started.html" >Getting started</a><a href="patterns.html" >Team patterns</a><a href="acp-agents.html" >ACP coding agents</a><a href="help.html" >Ask code-flow</a></section><section><h2>Work with agents</h2><a href="runs.html" >Runs and workspace</a><a href="auto-team.html" >Team</a><a href="project-teams.html" >Project missions (preview)</a><a href="review-inbox.html" >Review inbox</a><a href="verification.html" >Verification and review</a><a href="github.html" >GitHub, review and shipping</a><a href="github-review-threads.html" >GitHub review threads</a><a href="task-reruns.html" >Selective task reruns</a><a href="deferred-runs.html" >Deferred runs</a></section><section><h2>Your workspace</h2><a href="configuration.html" >Configuration</a><a href="context-inspection.html" >Context and budgets</a><a href="project-conventions.html" >Versioned project conventions</a><a href="checkpoint-review.html" >Checkpoints and reversions</a><a href="launch-profiles.html" >Service launch profiles</a><a href="code-intelligence.html" >Code intelligence</a><a href="architecture-explorer.html" >Architecture explorer</a><a href="memory-storage.html" >Project memory</a><a href="memory-claims.html" >Semantic claim review</a><a href="coordinated-changes.html" >Coordinated changes</a></section><section><h2>Connect and collaborate</h2><a href="team-collaboration.html" >Team collaboration</a><a href="shared-projects.html" >Shared project accounts</a><a href="ssh-projects.html" >SSH projects</a><a href="remote-workers.html" aria-current="page">Remote agent workers</a><a href="code-hosts.html" >GitLab and Bitbucket code workflows</a><a href="external-sources.html" >Read-only external sources</a><a href="automations.html" >Automations and away mode</a><a href="notifications.html" >Outbound notifications</a></section><section><h2>Operate safely</h2><a href="security.html" >Security, subscriptions and caveats</a><a href="filesystem-policy.html" >Project filesystem policy</a><a href="agent-containers.html" >Agent containers</a><a href="filtered-tasks.html" >Filtered Docker tasks</a><a href="dependency-discovery.html" >Dependency discovery</a><a href="maintenance.html" >Backup and maintenance</a></section><section><h2>Build and extend</h2><a href="architecture.html" >Architecture and development</a><a href="api.html" >Local API and command-line client</a><a href="extensions.html" >Provider and workflow extensions</a><a href="provider-compatibility.html" >Provider compatibility</a><a href="accessibility.html" >Accessibility acceptance</a><a href="performance.html" >Performance</a><a href="run-storage.html" >Run storage</a><a href="documentation.html" >Documentation and GitHub Pages</a><a href="releasing.html" >Preparing a preview release</a><a href="vscode.html" >Code Flow for VS Code</a></section><section><h2>Engineering records</h2><a href="application-improvements.html" >Application improvement program</a><a href="project-first-navigation-plan.html" >Project navigation review and implementation plan</a><a href="dynamic-teams-evaluation.html" >Dynamic teams: implementation evidence and rollout decision</a><a href="dynamic-teams-implementation-plan.html" >Dynamic teams, workflows, messaging, and memory</a><a href="dynamic-teams-implementation-review-1.html" >Review 1: the dynamic teams implementation</a><a href="worker-permission-verification.html" >Live worker permission verification</a><a href="dynamic-teams-plan-review-0.html" >Review 0: Dynamic teams implementation plan</a><a href="project-teams-implementation-plan.html" >Standing project teams implementation plan</a><a href="performance-results.html" >Measured performance: 19 October 2026</a></section><a class="app-link" id="back-app" hidden href="/">← Back to app</a></nav>
6
+ <main id="content" tabindex="-1"><div class="breadcrumb">Documentation <span>/</span> Connect and collaborate</div><article><h1 id="remote-agent-workers">Remote agent workers</h1>
7
+ <p>Provision and verify a worker before assigning it work. Keep source and result receipts available so interrupted connections can be reconciled without launching duplicate work.</p>
8
+ <h2 id="choose-an-execution-target">Choose an execution target</h2>
9
+ <p>An explicitly registered SSH worker runs agent turns in disposable Git worktrees on another machine. The application transfers an exact commit, the turn prompt and regular files from the run’s <code>.codeflow-context</code> folder. Official agent CLIs use the worker’s own login. SSH agent forwarding, environment forwarding, port forwarding and automatic host-key acceptance are disabled.</p>
10
+ <p>This is an operator provisioned service: it does not discover hosts, install remote dependencies, copy local provider credentials or automatically fetch repositories from the network. Commands and checks outside agent turns still run where the application server runs. Choose the remote worker in the composer’s advanced controls.</p>
11
+ <h2 id="provision-a-worker">Provision a worker</h2>
12
+ <p>Use Node 22.13 or newer, Git and the official CLI for each selected provider. Sign in on the worker itself. A dedicated OS account and disk/process limits are recommended for executable repository content. The worker account needs write access to its own state directory and provisioned repository mappings. A mapping can be a clone or a bare Git repository with an existing commit; it is not an arbitrary path supplied by a run.</p>
13
+ <p>Build the standalone entry point in this checkout:</p>
14
+ <pre><code class="language-sh">npm run build:worker
15
+ </code></pre>
16
+ <p>Copy <code>dist/remote-worker.mjs</code> to the worker through your normal administration process. Configure an existing SSH host alias with its known host key and noninteractive authentication. Code-flow runs <code>ssh</code> with strict host-key checking and never accepts a new fingerprint for you. <a href="https://man.openbsd.org/ssh">OpenSSH’s manual</a> describes identity selection and forwarding options.</p>
17
+ <p>Create a private worker configuration, for example <code>/srv/codeflow/worker.json</code>:</p>
18
+ <pre><code class="language-json">{
19
+ &quot;version&quot;: 1,
20
+ &quot;root&quot;: &quot;/srv/codeflow/state&quot;,
21
+ &quot;repos&quot;: { &quot;application&quot;: &quot;/srv/codeflow/repos/application.git&quot; },
22
+ &quot;providers&quot;: [&quot;claude&quot;, &quot;codex&quot;],
23
+ &quot;allowedTrust&quot;: [&quot;safe&quot;, &quot;standard&quot;]
24
+ }
25
+ </code></pre>
26
+ <p>Register it on the application server with <code>CODEFLOW_REMOTE_WORKERS_FILE=/absolute/remote-workers.json</code> (or the same JSON in <code>CODEFLOW_REMOTE_WORKERS_JSON</code>):</p>
27
+ <pre><code class="language-json">{
28
+ &quot;version&quot;: 1,
29
+ &quot;workers&quot;: [{
30
+ &quot;id&quot;: &quot;build-linux&quot;,
31
+ &quot;name&quot;: &quot;Linux build worker&quot;,
32
+ &quot;sshHost&quot;: &quot;codeflow-linux&quot;,
33
+ &quot;command&quot;: &quot;node /srv/codeflow/remote-worker.mjs --config /srv/codeflow/worker.json&quot;,
34
+ &quot;repoMappings&quot;: [&quot;application&quot;]
35
+ }]
36
+ }
37
+ </code></pre>
38
+ <p>The command is an explicit operator configuration; task content never becomes part of the SSH command. Keep these files outside agent workspaces. Public worker metadata contains names, IDs, mapping names and optional container profile names, without SSH commands, host details, credentials or recovery capabilities.</p>
39
+ <p>The worker view probes the registered channel and installed CLIs. A successful probe does not claim a provider login is valid; the official CLI reports authentication failures when a turn runs. Missing mappings, providers or container profiles fail explicitly. Remote selection never falls back to this computer.</p>
40
+ <h2 id="exact-source-and-returned-changes">Exact source and returned changes</h2>
41
+ <p>The client pins the clean tracked checkout commit. If the worker already has it, no source upload is needed. Otherwise code-flow creates a Git bundle using an exclusive temporary <code>refs/codeflow/transfers/&lt;requestId&gt;</code> reference, deletes that reference with compare-and-swap, and uploads the bounded bundle over SSH. When the worker confirms the repository’s original base is present, the bundle excludes that history. If the bundle is too large, sync the provisioned mapping through your administration process and retry explicitly. No remote URL from task content is fetched.</p>
42
+ <p>The worker verifies the bundle’s sole advertised reference, enables Git object validation on import and creates a detached request worktree. It never checks out or changes the mapping’s main branch. Read turns must preserve <code>HEAD</code>, the staged tree and tracked files; changed files are discarded and the turn fails. Write turns return a worker-created commit descended from the exact accepted base. Agent attempts to rewrite checkout history fail.</p>
43
+ <p>Returned result bundles have an exact request-owned reference and SHA-256 digest. Before importing, the client verifies the digest, advertised commit, Git object integrity and ancestry, then requires the local worktree’s original commit and clean tracked state. It fast-forwards that owned checkout only; concurrent local changes cause a visible failure. Disposable worktrees and imported temporary references are cleaned after execution. See Git’s <a href="https://git-scm.com/docs/git-bundle">bundle</a> and <a href="https://git-scm.com/docs/git-worktree">worktree</a> documentation for those primitives.</p>
44
+ <p>Gitlinks/submodules and repositories declaring checkout filters such as Git LFS are rejected: a parent Git bundle does not contain their materialized contents. Configured clean, smudge and process filters are suppressed during scoped checkout, staging and result import, so these steps do not secretly execute filters or fetch LFS content. Use local execution for those repositories.</p>
45
+ <p>Only staged reference files are copied as context. Symlinks, special files, <code>.env</code> files, private key extensions, traversal and arbitrary host paths are rejected. There are at most 100 regular files, 8 MiB per file and 16 MiB total. Host home directories, agent sessions and host environment variables are not part of the transfer.</p>
46
+ <h2 id="receipts-cancellation-and-ambiguous-outcomes">Receipts, cancellation and ambiguous outcomes</h2>
47
+ <p>Each invocation has a random request ID, a distinct private capability and a run/step/thread scope. Before invoking a provider, the worker exclusively claims the ID, fsyncs its receipt and directories, and reports acceptance. It records heartbeats and terminal results. The private capability is stored in the server’s <code>remote-worker-private</code> directory with owner-only file permissions and pinned to the exact configured SSH host, command and container profile. Replacing a worker alias cannot send an old recovery capability to its new target. Run records contain only worker ID, request ID, fingerprint and outcome metadata.</p>
48
+ <p>A reconnect inspects the same durable receipt. Reusing an ID never launches another provider process. A broken connection, missing receipt or expired heartbeat becomes <strong>unknown</strong>, even when the provider might already have performed work. There is no automatic execution retry or local fallback for that outcome. Inspect or cancel the request, and deliberately create a new invocation only after assessing its prior effects. Terminal receipts can re-download the validated result bundle without repeating execution. Open the agent step’s transcript and choose <strong>Inspect remote receipt</strong>. <strong>Cancel remote execution</strong> requires an explicit confirmation. These controls never launch a new turn; Resume is a separate owner action after reconciliation.</p>
49
+ <p>Cancellation uses the stored capability and a separate SSH control channel. The active worker checks the cancellation marker, stops the official CLI and records cancellation. A disconnected channel also aborts the scoped worker process. During a worker crash or lost host, termination cannot be confirmed until the host is inspected; an unknown receipt must not be interpreted as proof that execution stopped.</p>
50
+ <p>Four worker execution slots and 100 request directories are retained at most. A crashed worker can leave its slot unresolved. Inspect its recorded PID, request receipt and host processes before manually archiving the terminal request directory and clearing a stale slot file. Code-flow deliberately does not reclaim an ambiguous slot and launch duplicate work. The client keeps at most 2,000 private receipts and 32 downloaded result spools pending import or discard. Metadata-only inspection does not download a result bundle. Encrypted application backups exclude private worker capabilities, so a restored server cannot cancel or recover old remote authority automatically.</p>
51
+ <h2 id="worker-local-containers-and-boundaries">Worker-local containers and boundaries</h2>
52
+ <p>Optional named <code>containers</code> profiles use the same explicit agent-container configuration as local runs. Register a <code>containerProfile</code> on the server target to select a worker-local profile. Its image and authentication volume must exist and be provisioned on the worker. Local container images, host credential volumes and home folders are never inferred or copied to the worker. Availability probes run the provider’s version command inside that exact prebuilt image with no network or credential volumes; a host CLI installation is unnecessary for a container profile. The image is never pulled automatically.</p>
53
+ <p>Remote turns currently start fresh CLI sessions and use structured question/reply outcomes across turns. Live team tools, mid-turn steering and native interactive approval prompts are unsupported. Every result omits resumable session IDs. Final verification and independent reviews still apply to imported results. The server must enforce run/project access before exposing receipt or cancellation operations.</p>
54
+ <p>Source and result transfers are each limited to 64 MiB, with binary Git output capped before a transfer file is written. A source tree has at most 20,000 entries and 256 MiB of file data. Protocol frames are capped at 2 MiB, streamed events at 16 MiB and provider turns at 30 minutes. Uploads have a 30-second deadline. These transfer and application bounds do not replace OS disk quotas or a container sandbox: executable repository commands and Git object decompression can consume additional worker resources. Do not give mutually untrusted users a shared worker OS account or broader SSH credentials than their work requires.</p>
55
+ <h2 id="validation-status">Validation status</h2>
56
+ <p>The automated acceptance fixture launches the standalone worker in a separate process through an injected SSH transport. It exercises the official adapter against a fake CLI, source/context transfer, bundle import, read-only rejection, private capability ownership, restart recovery, dropped transport, cancellation, tampered bundles and changed local heads. No provider quota or external messages are used.</p>
57
+ <p>An additional opt-in acceptance test passed over real encrypted loopback OpenSSH: a temporary unprivileged daemon bound to 127.0.0.1, temporary host/client keys and isolated ssh -F configuration, the bundled worker process, a fake CLI, exact source transfer, result import and receipt recovery. Run it with <code>CODEFLOW_TEST_LOOPBACK_SSH=1 npx tsx --test test/remote-workers-ssh.test.ts</code>. It never modifies user SSH configuration or system settings, and reports a skip if unprivileged sshd is unavailable. No external SSH host or live provider login was tested. Validate those on an explicitly configured host before relying on unattended work. Container inventory uses an injected Docker fixture; an actual Docker worker image was not exercised in this acceptance run.</p>
58
+ <hr>
59
+ <p><a href="index.html">Documentation library</a> · <a href="getting-started.html">Getting started</a> · <a href="help.html">Ask code-flow</a></p>
60
+ </article><footer><a href="https://github.com/midhunxavier/code-flow/blob/main/docs/remote-workers.md">Edit this page on GitHub ↗</a><span>code-flow · 0.1.0-preview.3 · <a href="font-license.txt">Font license</a></span></footer><nav class="pagination" aria-label="Adjacent guides"><a href="ssh-projects.html"><small>← Previous</small>SSH projects</a><a href="code-hosts.html"><small>Next →</small>GitLab and Bitbucket code workflows</a></nav></main>
61
+ <aside class="on-page" aria-label="On this page"><strong>On this page</strong><a class="depth-2" href="#choose-an-execution-target">Choose an execution target</a><a class="depth-2" href="#provision-a-worker">Provision a worker</a><a class="depth-2" href="#exact-source-and-returned-changes">Exact source and returned changes</a><a class="depth-2" href="#receipts-cancellation-and-ambiguous-outcomes">Receipts, cancellation and ambiguous outcomes</a><a class="depth-2" href="#worker-local-containers-and-boundaries">Worker-local containers and boundaries</a><a class="depth-2" href="#validation-status">Validation status</a></aside>
62
+ <aside id="help-panel" hidden aria-labelledby="help-title"><div class="chat-heading"><div><span class="eyebrow">Your AI companion</span><h2 id="help-title">Ask code-flow</h2></div><button id="close-help" aria-label="Close AI companion">✕</button></div><div class="chat-toolbar"><span>Grounded in your docs</span><button id="new-chat">New chat</button></div><div id="help-messages" role="log" aria-label="Help conversation" aria-live="polite"><div id="chat-welcome"><span class="chat-mark" aria-hidden="true">✦</span><h3>What would you like to do?</h3><p>Let’s find your next step. Ask about setup, workflows or something that’s unclear.</p><div class="suggestions"><button type="button" data-question="How do I start my first run?">Start my first run ↗</button><button type="button" data-question="What should I do when a check fails?">Understand a failed check ↗</button></div></div></div><p id="help-status" role="status">Checking your installed CLIs…</p><button id="retry-help" hidden>Retry connection</button><form id="help-form" hidden><label class="sr-only" for="question">Your question</label><textarea id="question" rows="3" maxlength="4000" placeholder="Ask a question…" required></textarea><div class="composer-controls"><label class="sr-only" for="help-agent">Use your CLI</label><select id="help-agent"></select><button type="button" id="stop-help" hidden>Stop</button><button class="primary" id="send-help" aria-label="Send message">Send ↗</button></div><small>Uses your CLI login and quota. Shift + Enter for a new line.</small></form><a id="help-guide" href="help.html">About your local companion →</a></aside></div>
63
+ <dialog id="search-dialog" aria-labelledby="search-title"><div class="dialog-title"><h2 id="search-title">Search documentation</h2><button data-close="search-dialog" aria-label="Close search">✕</button></div><label class="sr-only" for="search">Search all guides</label><input id="search" type="search" placeholder="Search workflows, settings, troubleshooting…" autocomplete="off"><div id="search-results" aria-live="polite"></div></dialog>
64
+ </body></html>
package/public/docs/review-inbox.html ADDED
@@ -0,0 +1,26 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Review inbox — code-flow guides and reference"><title>Review inbox · code-flow</title><link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K"><link rel="stylesheet" href="style.css"><script src="app.js" defer></script></head>
3
+ <body data-page="review-inbox"><a class="skip-link" href="#content">Skip to content</a>
4
+ <header class="topbar"><a class="brand" href="index.html"><img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K" width="30" height="30" alt=""><strong>Code Flow</strong><span>Docs</span></a><button class="search-trigger" id="open-search">Search documentation <kbd>⌘ K</kbd></button><div class="top-actions"><a href="https://github.com/midhunxavier/code-flow">GitHub ↗</a><button id="theme" aria-label="Change color theme">Theme</button><button id="open-help" class="primary" hidden aria-expanded="false" aria-controls="help-panel">Ask code-flow</button><button id="menu" aria-label="Toggle documentation navigation" aria-expanded="false" aria-controls="sidebar">☰</button></div></header>
5
+ <div class="layout"><nav class="sidebar" id="sidebar" aria-label="Documentation"><section><h2>Get started</h2><a href="index.html" >Overview</a><a href="installation.html" >Install Code Flow preview</a><a href="getting-started.html" >Getting started</a><a href="patterns.html" >Team patterns</a><a href="acp-agents.html" >ACP coding agents</a><a href="help.html" >Ask code-flow</a></section><section><h2>Work with agents</h2><a href="runs.html" >Runs and workspace</a><a href="auto-team.html" >Team</a><a href="project-teams.html" >Project missions (preview)</a><a href="review-inbox.html" aria-current="page">Review inbox</a><a href="verification.html" >Verification and review</a><a href="github.html" >GitHub, review and shipping</a><a href="github-review-threads.html" >GitHub review threads</a><a href="task-reruns.html" >Selective task reruns</a><a href="deferred-runs.html" >Deferred runs</a></section><section><h2>Your workspace</h2><a href="configuration.html" >Configuration</a><a href="context-inspection.html" >Context and budgets</a><a href="project-conventions.html" >Versioned project conventions</a><a href="checkpoint-review.html" >Checkpoints and reversions</a><a href="launch-profiles.html" >Service launch profiles</a><a href="code-intelligence.html" >Code intelligence</a><a href="architecture-explorer.html" >Architecture explorer</a><a href="memory-storage.html" >Project memory</a><a href="memory-claims.html" >Semantic claim review</a><a href="coordinated-changes.html" >Coordinated changes</a></section><section><h2>Connect and collaborate</h2><a href="team-collaboration.html" >Team collaboration</a><a href="shared-projects.html" >Shared project accounts</a><a href="ssh-projects.html" >SSH projects</a><a href="remote-workers.html" >Remote agent workers</a><a href="code-hosts.html" >GitLab and Bitbucket code workflows</a><a href="external-sources.html" >Read-only external sources</a><a href="automations.html" >Automations and away mode</a><a href="notifications.html" >Outbound notifications</a></section><section><h2>Operate safely</h2><a href="security.html" >Security, subscriptions and caveats</a><a href="filesystem-policy.html" >Project filesystem policy</a><a href="agent-containers.html" >Agent containers</a><a href="filtered-tasks.html" >Filtered Docker tasks</a><a href="dependency-discovery.html" >Dependency discovery</a><a href="maintenance.html" >Backup and maintenance</a></section><section><h2>Build and extend</h2><a href="architecture.html" >Architecture and development</a><a href="api.html" >Local API and command-line client</a><a href="extensions.html" >Provider and workflow extensions</a><a href="provider-compatibility.html" >Provider compatibility</a><a href="accessibility.html" >Accessibility acceptance</a><a href="performance.html" >Performance</a><a href="run-storage.html" >Run storage</a><a href="documentation.html" >Documentation and GitHub Pages</a><a href="releasing.html" >Preparing a preview release</a><a href="vscode.html" >Code Flow for VS Code</a></section><section><h2>Engineering records</h2><a href="application-improvements.html" >Application improvement program</a><a href="project-first-navigation-plan.html" >Project navigation review and implementation plan</a><a href="dynamic-teams-evaluation.html" >Dynamic teams: implementation evidence and rollout decision</a><a href="dynamic-teams-implementation-plan.html" >Dynamic teams, workflows, messaging, and memory</a><a href="dynamic-teams-implementation-review-1.html" >Review 1: the dynamic teams implementation</a><a href="worker-permission-verification.html" >Live worker permission verification</a><a href="dynamic-teams-plan-review-0.html" >Review 0: Dynamic teams implementation plan</a><a href="project-teams-implementation-plan.html" >Standing project teams implementation plan</a><a href="performance-results.html" >Measured performance: 19 October 2026</a></section><a class="app-link" id="back-app" hidden href="/">← Back to app</a></nav>
6
+ <main id="content" tabindex="-1"><div class="breadcrumb">Documentation <span>/</span> Work with agents</div><article><h1 id="review-inbox">Review inbox</h1>
7
+ <p>Open Inbox from the sidebar. Filter to a project or attention type, then open an item to answer its question or inspect its result. Sorting the inbox does not approve or publish work.</p>
8
+ <h2 id="work-through-attention-items">Work through attention items</h2>
9
+ <p>The <strong>Inbox</strong> sidebar destination groups attention for manual and unattended runs.
10
+ Questions and approvals, blocked teams, unread failed/interrupted runs and pending
11
+ automation results appear there. Archived and handled items are excluded.</p>
12
+ <p>Run priority comes first, followed by attention type and then the oldest waiting
13
+ item. Group by project, repository or attention type, or use one list. Search task
14
+ text, run IDs, repository paths, source titles and trigger names. Project scope
15
+ continues to apply; the page reports attention items outside the current scope.</p>
16
+ <p>Open the run to answer questions, inspect failures or review evidence. Tool
17
+ permissions remain in their scoped approval inbox. No result is merged or approved
18
+ by sorting, filtering or opening this page. Grouping is a presentation choice and
19
+ does not change dispatch order; the explicit run priority controls dispatch too.</p>
20
+ <hr>
21
+ <p><a href="index.html">Documentation library</a> · <a href="getting-started.html">Getting started</a> · <a href="help.html">Ask code-flow</a></p>
22
+ </article><footer><a href="https://github.com/midhunxavier/code-flow/blob/main/docs/review-inbox.md">Edit this page on GitHub ↗</a><span>code-flow · 0.1.0-preview.3 · <a href="font-license.txt">Font license</a></span></footer><nav class="pagination" aria-label="Adjacent guides"><a href="project-teams.html"><small>← Previous</small>Project missions (preview)</a><a href="verification.html"><small>Next →</small>Verification and review</a></nav></main>
23
+ <aside class="on-page" aria-label="On this page"><strong>On this page</strong><a class="depth-2" href="#work-through-attention-items">Work through attention items</a></aside>
24
+ <aside id="help-panel" hidden aria-labelledby="help-title"><div class="chat-heading"><div><span class="eyebrow">Your AI companion</span><h2 id="help-title">Ask code-flow</h2></div><button id="close-help" aria-label="Close AI companion">✕</button></div><div class="chat-toolbar"><span>Grounded in your docs</span><button id="new-chat">New chat</button></div><div id="help-messages" role="log" aria-label="Help conversation" aria-live="polite"><div id="chat-welcome"><span class="chat-mark" aria-hidden="true">✦</span><h3>What would you like to do?</h3><p>Let’s find your next step. Ask about setup, workflows or something that’s unclear.</p><div class="suggestions"><button type="button" data-question="How do I start my first run?">Start my first run ↗</button><button type="button" data-question="What should I do when a check fails?">Understand a failed check ↗</button></div></div></div><p id="help-status" role="status">Checking your installed CLIs…</p><button id="retry-help" hidden>Retry connection</button><form id="help-form" hidden><label class="sr-only" for="question">Your question</label><textarea id="question" rows="3" maxlength="4000" placeholder="Ask a question…" required></textarea><div class="composer-controls"><label class="sr-only" for="help-agent">Use your CLI</label><select id="help-agent"></select><button type="button" id="stop-help" hidden>Stop</button><button class="primary" id="send-help" aria-label="Send message">Send ↗</button></div><small>Uses your CLI login and quota. Shift + Enter for a new line.</small></form><a id="help-guide" href="help.html">About your local companion →</a></aside></div>
25
+ <dialog id="search-dialog" aria-labelledby="search-title"><div class="dialog-title"><h2 id="search-title">Search documentation</h2><button data-close="search-dialog" aria-label="Close search">✕</button></div><label class="sr-only" for="search">Search all guides</label><input id="search" type="search" placeholder="Search workflows, settings, troubleshooting…" autocomplete="off"><div id="search-results" aria-live="polite"></div></dialog>
26
+ </body></html>
package/public/docs/run-storage.html ADDED
@@ -0,0 +1,23 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Run storage — code-flow guides and reference"><title>Run storage · code-flow</title><link rel="icon" href="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K"><link rel="stylesheet" href="style.css"><script src="app.js" defer></script></head>
3
+ <body data-page="run-storage"><a class="skip-link" href="#content">Skip to content</a>
4
+ <header class="topbar"><a class="brand" href="index.html"><img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0Ij4KICA8Y2lyY2xlIGN4PSIzMiIgY3k9IjMyIiByPSIzMCIgZmlsbD0iIzFlMWYxYSIgc3Ryb2tlPSIjM2Q0MDM2IiBzdHJva2Utd2lkdGg9IjIiLz4KICA8c3ZnIHg9IjE1IiB5PSIxNSIgd2lkdGg9IjM0IiBoZWlnaHQ9IjM0IiB2aWV3Qm94PSIwIDAgMjQgMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2VjZWJlNCIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPgogICAgPHBhdGggZD0iTTEyIDNsOSA1LTkgNS05LTV6TTMgMTNsOSA1IDktNU0zIDE3LjVsOSA1IDktNSIvPgogIDwvc3ZnPgo8L3N2Zz4K" width="30" height="30" alt=""><strong>Code Flow</strong><span>Docs</span></a><button class="search-trigger" id="open-search">Search documentation <kbd>⌘ K</kbd></button><div class="top-actions"><a href="https://github.com/midhunxavier/code-flow">GitHub ↗</a><button id="theme" aria-label="Change color theme">Theme</button><button id="open-help" class="primary" hidden aria-expanded="false" aria-controls="help-panel">Ask code-flow</button><button id="menu" aria-label="Toggle documentation navigation" aria-expanded="false" aria-controls="sidebar">☰</button></div></header>
5
+ <div class="layout"><nav class="sidebar" id="sidebar" aria-label="Documentation"><section><h2>Get started</h2><a href="index.html" >Overview</a><a href="installation.html" >Install Code Flow preview</a><a href="getting-started.html" >Getting started</a><a href="patterns.html" >Team patterns</a><a href="acp-agents.html" >ACP coding agents</a><a href="help.html" >Ask code-flow</a></section><section><h2>Work with agents</h2><a href="runs.html" >Runs and workspace</a><a href="auto-team.html" >Team</a><a href="project-teams.html" >Project missions (preview)</a><a href="review-inbox.html" >Review inbox</a><a href="verification.html" >Verification and review</a><a href="github.html" >GitHub, review and shipping</a><a href="github-review-threads.html" >GitHub review threads</a><a href="task-reruns.html" >Selective task reruns</a><a href="deferred-runs.html" >Deferred runs</a></section><section><h2>Your workspace</h2><a href="configuration.html" >Configuration</a><a href="context-inspection.html" >Context and budgets</a><a href="project-conventions.html" >Versioned project conventions</a><a href="checkpoint-review.html" >Checkpoints and reversions</a><a href="launch-profiles.html" >Service launch profiles</a><a href="code-intelligence.html" >Code intelligence</a><a href="architecture-explorer.html" >Architecture explorer</a><a href="memory-storage.html" >Project memory</a><a href="memory-claims.html" >Semantic claim review</a><a href="coordinated-changes.html" >Coordinated changes</a></section><section><h2>Connect and collaborate</h2><a href="team-collaboration.html" >Team collaboration</a><a href="shared-projects.html" >Shared project accounts</a><a href="ssh-projects.html" >SSH projects</a><a href="remote-workers.html" >Remote agent workers</a><a href="code-hosts.html" >GitLab and Bitbucket code workflows</a><a href="external-sources.html" >Read-only external sources</a><a href="automations.html" >Automations and away mode</a><a href="notifications.html" >Outbound notifications</a></section><section><h2>Operate safely</h2><a href="security.html" >Security, subscriptions and caveats</a><a href="filesystem-policy.html" >Project filesystem policy</a><a href="agent-containers.html" >Agent containers</a><a href="filtered-tasks.html" >Filtered Docker tasks</a><a href="dependency-discovery.html" >Dependency discovery</a><a href="maintenance.html" >Backup and maintenance</a></section><section><h2>Build and extend</h2><a href="architecture.html" >Architecture and development</a><a href="api.html" >Local API and command-line client</a><a href="extensions.html" >Provider and workflow extensions</a><a href="provider-compatibility.html" >Provider compatibility</a><a href="accessibility.html" >Accessibility acceptance</a><a href="performance.html" >Performance</a><a href="run-storage.html" aria-current="page">Run storage</a><a href="documentation.html" >Documentation and GitHub Pages</a><a href="releasing.html" >Preparing a preview release</a><a href="vscode.html" >Code Flow for VS Code</a></section><section><h2>Engineering records</h2><a href="application-improvements.html" >Application improvement program</a><a href="project-first-navigation-plan.html" >Project navigation review and implementation plan</a><a href="dynamic-teams-evaluation.html" >Dynamic teams: implementation evidence and rollout decision</a><a href="dynamic-teams-implementation-plan.html" >Dynamic teams, workflows, messaging, and memory</a><a href="dynamic-teams-implementation-review-1.html" >Review 1: the dynamic teams implementation</a><a href="worker-permission-verification.html" >Live worker permission verification</a><a href="dynamic-teams-plan-review-0.html" >Review 0: Dynamic teams implementation plan</a><a href="project-teams-implementation-plan.html" >Standing project teams implementation plan</a><a href="performance-results.html" >Measured performance: 19 October 2026</a></section><a class="app-link" id="back-app" hidden href="/">← Back to app</a></nav>
6
+ <main id="content" tabindex="-1"><div class="breadcrumb">Documentation <span>/</span> Build and extend</div><article><h1 id="run-storage">Run storage</h1>
7
+ <p>Archive completed work to reduce retained detail in memory. Open an archived run to load its full evidence; archival caches do not replace the durable event log or delete worktrees by themselves.</p>
8
+ <h2 id="understand-archived-history">Understand archived history</h2>
9
+ <p>The append-only run event log and execution journal remain the source of truth. Startup recovers at most four runs concurrently, consuming fallback logs one record at a time. Recovery retains the latest run snapshot and latest state of each step; provider transcripts are read only when that run’s history is requested. It no longer builds an array containing every historical event log. A recovery record has a 64 MiB bound; exceeding it fails recovery visibly instead of silently dropping an ID.</p>
10
+ <p>Only archived, completed runs with no pending notes, follow-ups, approval, watch or unresolved remote execution can use cold storage. Running, interrupted, failed, stopped and unarchived runs remain in the normal live/resumable map. No worktrees or execution journals are removed by this optimization.</p>
11
+ <p>Each eligible run has optional <code>runs/&lt;id&gt;.cold-index.json</code> and <code>runs/&lt;id&gt;.cold-detail.json</code> projections. The compact index is at most 128 KiB; the full detail projection is at most 16 MiB. Oversized runs stay in the normal map. The projections carry checksums and exact source-file identities. A missing, damaged, changed or stale projection is rebuilt from the authoritative event log. They are caches, not a second source of truth.</p>
12
+ <p>Cold list/history entries explicitly return <code>cold: true</code> and <code>detailAvailable: true</code>. They preserve IDs, timestamps, repository/worktree ownership, parent/source/project provenance, source trust, pinned filesystem policies, permissions, usage, statistical counters and review attribution. Large task/summary previews are shortened, and heavy team graphs, context evidence, conventions and review prose are omitted. Open the run to read its complete metadata, transcript and evidence. Full-text history searches use indexed complete task and source/title text, including text beyond the preview. Legacy indexes obtain this text once during asynchronous startup; normal searches do not hydrate archived details.</p>
13
+ <p>Full metadata is read on demand through an eight-entry, 32 MiB least-recently-used cache. Individual reads are bounded to 16 MiB. A cold read returns a detached copy; mutation and Resume promote the complete run before changing it. Weak references preserve any still-held original live run handle during promotion without retaining archived full state. Updated data stays live until its queued event snapshot has been flushed and a matching cold projection has been saved. Source changes invalidate cached detail. Cold metadata is never used to reconstruct execution claims or substitute for journal replay.</p>
14
+ <p>History keeps every run ID and count. Cursor ordering uses creation time and run ID so runs created in the same millisecond are not skipped. Attention pagination includes every running run, plus at most 100 older attention items per page. Authorization filtering happens before totals and cursors. The response reports total attention, truncation and a continuation cursor; history remains available for older entries.</p>
15
+ <p>Reviewed retention manifests include both cold projection files when deleting their owner run. Their recent cache-generation time does not reset the original run’s retention age. Offline log compaction removes the derived cold projections so the next start rebuilds them. The normal backup and filesystem-policy boundaries continue to apply to these files.</p>
16
+ <p>This bounds retained full archived metadata and recovery batches. The compact index still grows with the number of recorded runs, and active/resumable runs remain in memory deliberately. The current UI reads bounded transcript pages directly by byte offset. Legacy stream clients and full exports can still request complete event history. Search uses an in-memory index, not a database. See <a href="performance.html">Performance and resource boundaries</a> for limits, diagnostics and benchmarks.</p>
17
+ <hr>
18
+ <p><a href="index.html">Documentation library</a> · <a href="getting-started.html">Getting started</a> · <a href="help.html">Ask code-flow</a></p>
19
+ </article><footer><a href="https://github.com/midhunxavier/code-flow/blob/main/docs/run-storage.md">Edit this page on GitHub ↗</a><span>code-flow · 0.1.0-preview.3 · <a href="font-license.txt">Font license</a></span></footer><nav class="pagination" aria-label="Adjacent guides"><a href="performance.html"><small>← Previous</small>Performance</a><a href="documentation.html"><small>Next →</small>Documentation and GitHub Pages</a></nav></main>
20
+ <aside class="on-page" aria-label="On this page"><strong>On this page</strong><a class="depth-2" href="#understand-archived-history">Understand archived history</a></aside>
21
+ <aside id="help-panel" hidden aria-labelledby="help-title"><div class="chat-heading"><div><span class="eyebrow">Your AI companion</span><h2 id="help-title">Ask code-flow</h2></div><button id="close-help" aria-label="Close AI companion">✕</button></div><div class="chat-toolbar"><span>Grounded in your docs</span><button id="new-chat">New chat</button></div><div id="help-messages" role="log" aria-label="Help conversation" aria-live="polite"><div id="chat-welcome"><span class="chat-mark" aria-hidden="true">✦</span><h3>What would you like to do?</h3><p>Let’s find your next step. Ask about setup, workflows or something that’s unclear.</p><div class="suggestions"><button type="button" data-question="How do I start my first run?">Start my first run ↗</button><button type="button" data-question="What should I do when a check fails?">Understand a failed check ↗</button></div></div></div><p id="help-status" role="status">Checking your installed CLIs…</p><button id="retry-help" hidden>Retry connection</button><form id="help-form" hidden><label class="sr-only" for="question">Your question</label><textarea id="question" rows="3" maxlength="4000" placeholder="Ask a question…" required></textarea><div class="composer-controls"><label class="sr-only" for="help-agent">Use your CLI</label><select id="help-agent"></select><button type="button" id="stop-help" hidden>Stop</button><button class="primary" id="send-help" aria-label="Send message">Send ↗</button></div><small>Uses your CLI login and quota. Shift + Enter for a new line.</small></form><a id="help-guide" href="help.html">About your local companion →</a></aside></div>
22
+ <dialog id="search-dialog" aria-labelledby="search-title"><div class="dialog-title"><h2 id="search-title">Search documentation</h2><button data-close="search-dialog" aria-label="Close search">✕</button></div><label class="sr-only" for="search">Search all guides</label><input id="search" type="search" placeholder="Search workflows, settings, troubleshooting…" autocomplete="off"><div id="search-results" aria-live="polite"></div></dialog>
23
+ </body></html>