@openchamber/web 1.21.0 → 1.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/bin/cli.test.js +35 -0
  2. package/bin/lib/DOCUMENTATION.md +12 -0
  3. package/bin/lib/cli-settings-accessors.js +111 -0
  4. package/bin/lib/cli-settings-accessors.test.js +189 -0
  5. package/bin/lib/cli-startup.js +29 -9
  6. package/bin/lib/commands-connect-url.js +12 -14
  7. package/dist/assets/{CodeMirrorCommentWidgets-C2BopIs3.js → CodeMirrorCommentWidgets-CPvfxh0N.js} +1 -1
  8. package/dist/assets/CommitSection-CC5mFzO2.js +1 -0
  9. package/dist/assets/DiffView-6xGdyI0n.js +4 -0
  10. package/dist/assets/FilesView-Bm3vT63N.js +17 -0
  11. package/dist/assets/GitView-B6y1Y69c.js +6 -0
  12. package/dist/assets/{JsonTreeView-osju7J70.js → JsonTreeView-rwHz84MX.js} +1 -1
  13. package/dist/assets/LinearIssuesView-B0UM_Rkx.js +1 -0
  14. package/dist/assets/MarkdownImageGallery-sGilV9Hs.js +1 -0
  15. package/dist/assets/MarkdownRendererImpl--4sRsKBn.js +12 -0
  16. package/dist/assets/OnboardingScreen-CECL_Cms.js +1 -0
  17. package/dist/assets/{PatchDiff-Dan3mADn.js → PatchDiff-BGPl1s-U.js} +1 -1
  18. package/dist/assets/{PierreDiffViewer-CGoI2v0q.js → PierreDiffViewer-Cvz9Z-io.js} +2 -2
  19. package/dist/assets/PlanView-BFMsnHk3.js +5 -0
  20. package/dist/assets/SettingsView-_Gtn5SdT.js +28 -0
  21. package/dist/assets/{SettingsWindow-DXF-MTHG.js → SettingsWindow-C1Qa09YO.js} +1 -1
  22. package/dist/assets/{ToolOutputDialog-DrCa1JRk.js → ToolOutputDialog-DzQlzMF4.js} +6 -6
  23. package/dist/assets/{ToolPartDiffPreview-B_tfvlNF.js → ToolPartDiffPreview-DfVOfwHy.js} +2 -2
  24. package/dist/assets/{VirtualizedFileDiff-CN_BctrR.js → VirtualizedFileDiff-DT5MDv-u.js} +1 -1
  25. package/dist/assets/WalkthroughView-D8sLH_M8.js +4 -0
  26. package/dist/assets/{computeVirtualFileMetrics-Gi1d5eU1.js → computeVirtualFileMetrics-DmpLWhll.js} +1 -1
  27. package/dist/assets/{contextPanelEmbeddedChat-CpzVNWAv.js → contextPanelEmbeddedChat-BK78t3M_.js} +1 -1
  28. package/dist/assets/de-C3luvSd_.js +9 -0
  29. package/dist/assets/es-CmU4HLv9.js +15 -0
  30. package/dist/assets/fr-Bgyni40l.js +13 -0
  31. package/dist/assets/index-C57jT0Sa.css +1 -0
  32. package/dist/assets/{index-Brm3X9rs.js → index-CWYs7sMK.js} +1 -1
  33. package/dist/assets/index-b0zDkWyg.js +7 -0
  34. package/dist/assets/{isDiffPlainText-pH9kAJQH.js → isDiffPlainText-BO_q5ezD.js} +1 -1
  35. package/dist/assets/{isFilePlainText-CVKy_dgB.js → isFilePlainText-D8qPqUAf.js} +1 -1
  36. package/dist/assets/ja-C1ImKinT.js +15 -0
  37. package/dist/assets/ko-CP7OdxYH.js +15 -0
  38. package/dist/assets/main-D4rd8Hy5.js +928 -0
  39. package/dist/assets/{main-vUCh0VB0.js → main-D7fwjW2z.js} +2 -2
  40. package/dist/assets/{markdown-shiki.worker-CKGJ1J33.js → markdown-shiki.worker-D5fBU-lw.js} +5 -5
  41. package/dist/assets/markdownCore-BcmkWZPO.js +3 -0
  42. package/dist/assets/{miniChat-BlzGEYgE.js → miniChat-D5rraz-g.js} +2 -2
  43. package/dist/assets/{mobile-CkX6H-IT.js → mobile-Cg_DE3KL.js} +2 -2
  44. package/dist/assets/{patchFileDiff-BCTsE43U.js → patchFileDiff-Bpql0QGw.js} +3 -3
  45. package/dist/assets/pl-DQYSiGYX.js +15 -0
  46. package/dist/assets/pt-BR-DytpsW4M.js +15 -0
  47. package/dist/assets/{renderElectronMiniChatApp-CJYe_KOL.js → renderElectronMiniChatApp-B_Bn7BbN.js} +2 -2
  48. package/dist/assets/renderMobileApp-DLfxMzGJ.js +25 -0
  49. package/dist/assets/runtimeEndpointReset-HlRmXFGW.js +16 -0
  50. package/dist/assets/scheduledTasksApi-BPvxrynl.js +1 -0
  51. package/dist/assets/{shikiHighlight-BgTPSITe.js → shikiHighlight-CFAVs_lu.js} +1 -1
  52. package/dist/assets/tr-aizaUvft.js +6 -0
  53. package/dist/assets/uk-DwnRxJZd.js +15 -0
  54. package/dist/assets/useAppFontEffects-DWXGRUPZ.js +7310 -0
  55. package/dist/assets/{useInlineCommentController-DFFv0hae.js → useInlineCommentController-Cc0OCXr0.js} +2 -2
  56. package/dist/assets/useRootScrollLock-BFZtfciC.js +1 -0
  57. package/dist/assets/{vendor-base-ui-_6j2xOWl.js → vendor-base-ui-BeMD8X_w.js} +1 -1
  58. package/dist/assets/{vendor-codemirror-language-data-DkQX2EBa.js → vendor-codemirror-language-data-BGFszm8n.js} +2 -2
  59. package/dist/assets/{vendor-floating-ui-core-CXmKXOXc.js → vendor-floating-ui-core-PuGzNPnN.js} +1 -1
  60. package/dist/assets/{vendor-floating-ui-dom-WyXykhNi.js → vendor-floating-ui-dom-BTvzWks8.js} +1 -1
  61. package/dist/assets/{vendor-floating-ui-react-dom-DKpLs02S.js → vendor-floating-ui-react-dom-DxYCWdHj.js} +1 -1
  62. package/dist/assets/{vendor-floating-ui-utils-BzXdqYpP.js → vendor-floating-ui-utils-D6FqdtJt.js} +1 -1
  63. package/dist/assets/vendor-linkify-it-DZCzzDkK.js +1 -0
  64. package/dist/assets/vendor-marked-linkify-it-CXI_LHIE.js +1 -0
  65. package/dist/assets/vendor-uc.micro-BAd0H0z4.js +1 -0
  66. package/dist/assets/{web-components-DLnGY4fs.js → web-components-CD-GFayc.js} +4 -4
  67. package/dist/assets/zh-CN-UDNMxm7r.js +15 -0
  68. package/dist/assets/zh-TW-BsswdYL-.js +15 -0
  69. package/dist/index.html +5 -5
  70. package/dist/mini-chat.html +3 -3
  71. package/dist/mobile.html +3 -3
  72. package/dist/site.webmanifest +1 -1
  73. package/dist/sw.js +1 -1
  74. package/package.json +2 -2
  75. package/public/site.webmanifest +1 -1
  76. package/server/index.js +6 -2
  77. package/server/lib/cloudflare-tunnel.js +1 -1
  78. package/server/lib/dictation/DOCUMENTATION.md +19 -6
  79. package/server/lib/dictation/local/model-catalog.js +220 -0
  80. package/server/lib/dictation/local/model-catalog.test.js +42 -0
  81. package/server/lib/dictation/local/sherpa-tts.js +41 -20
  82. package/server/lib/dictation/local/worker-process.js +2 -0
  83. package/server/lib/dictation/runtime.js +4 -0
  84. package/server/lib/dictation/service.js +27 -4
  85. package/server/lib/fs/DOCUMENTATION.md +5 -0
  86. package/server/lib/fs/routes.js +150 -0
  87. package/server/lib/fs/routes.test.js +308 -3
  88. package/server/lib/git/DOCUMENTATION.md +4 -3
  89. package/server/lib/git/service.js +128 -6
  90. package/server/lib/git/service.test.js +191 -1
  91. package/server/lib/linear/DOCUMENTATION.md +97 -0
  92. package/server/lib/linear/OAUTH-BROKER-HANDOFF.md +91 -0
  93. package/server/lib/linear/auth.js +436 -0
  94. package/server/lib/linear/auth.test.js +242 -0
  95. package/server/lib/linear/client.js +191 -0
  96. package/server/lib/linear/index.js +61 -0
  97. package/server/lib/linear/issues.js +499 -0
  98. package/server/lib/linear/issues.test.js +512 -0
  99. package/server/lib/linear/mapping.js +188 -0
  100. package/server/lib/linear/mapping.test.js +147 -0
  101. package/server/lib/linear/oauth.js +345 -0
  102. package/server/lib/linear/oauth.test.js +166 -0
  103. package/server/lib/linear/parse.js +23 -0
  104. package/server/lib/linear/routes.js +432 -0
  105. package/server/lib/linear/routes.test.js +661 -0
  106. package/server/lib/linear/status-runtime.js +64 -0
  107. package/server/lib/linear/status-runtime.test.js +167 -0
  108. package/server/lib/linear/status.js +280 -0
  109. package/server/lib/linear/status.test.js +271 -0
  110. package/server/lib/linear/teams.js +72 -0
  111. package/server/lib/linear/teams.test.js +94 -0
  112. package/server/lib/markdown-image-grants/DOCUMENTATION.md +4 -0
  113. package/server/lib/markdown-image-grants/routes.js +3 -1
  114. package/server/lib/markdown-image-grants/routes.test.js +14 -0
  115. package/server/lib/openchamber-sessions/routes.js +4 -1
  116. package/server/lib/openchamber-sessions/routes.test.js +23 -0
  117. package/server/lib/opencode/env-runtime.js +17 -1
  118. package/server/lib/opencode/env-runtime.test.js +56 -0
  119. package/server/lib/opencode/feature-routes-runtime.js +2 -0
  120. package/server/lib/opencode/lifecycle.js +48 -9
  121. package/server/lib/opencode/lifecycle.test.js +125 -1
  122. package/server/lib/opencode/managed-process-registry.d.ts +13 -0
  123. package/server/lib/opencode/managed-process-registry.js +213 -163
  124. package/server/lib/opencode/managed-process-registry.test.mjs +285 -0
  125. package/server/lib/opencode/project-directory-runtime.js +16 -11
  126. package/server/lib/opencode/project-directory-runtime.test.js +32 -12
  127. package/server/lib/opencode/pwa-manifest-routes.js +1 -1
  128. package/server/lib/opencode/routes-upgrade.test.js +96 -12
  129. package/server/lib/opencode/routes.js +53 -5
  130. package/server/lib/opencode/settings-helpers.js +3 -0
  131. package/server/lib/opencode/settings-helpers.test.js +10 -0
  132. package/server/lib/opencode/static-routes-runtime.js +3 -3
  133. package/server/lib/opencode/theme-runtime.js +1 -1
  134. package/server/lib/opencode/theme-runtime.test.js +129 -0
  135. package/server/lib/projects/project-config.js +33 -5
  136. package/server/lib/projects/project-config.test.js +85 -0
  137. package/server/lib/quota/DOCUMENTATION.md +19 -0
  138. package/server/lib/quota/providers/copilot.js +26 -10
  139. package/server/lib/quota/providers/copilot.test.js +78 -0
  140. package/server/lib/scheduled-tasks/DOCUMENTATION.md +7 -0
  141. package/server/lib/small-model/DOCUMENTATION.md +11 -5
  142. package/server/lib/small-model/call.js +64 -20
  143. package/server/lib/small-model/call.test.js +184 -2
  144. package/server/lib/tts/DOCUMENTATION.md +1 -0
  145. package/server/lib/tts/language-detect.js +210 -0
  146. package/server/lib/tts/language-detect.test.js +76 -0
  147. package/server/lib/tts/routes.js +23 -1
  148. package/server/lib/tts/routes.test.js +26 -0
  149. package/server/lib/tunnels/install-help.js +2 -2
  150. package/server/lib/tunnels/install-help.test.js +9 -0
  151. package/server/lib/walkthrough/languages.js +1 -0
  152. package/dist/assets/CommitSection-HJeMUAWb.js +0 -1
  153. package/dist/assets/DiffView-D5cvbEPb.js +0 -4
  154. package/dist/assets/FilesView-DPU8aNPL.js +0 -17
  155. package/dist/assets/GitView-Ct6xWrVH.js +0 -6
  156. package/dist/assets/MarkdownImageGallery-EujHSZ2M.js +0 -1
  157. package/dist/assets/MarkdownRendererImpl-CPzu4kIr.js +0 -12
  158. package/dist/assets/OnboardingScreen-w2VG4fWY.js +0 -1
  159. package/dist/assets/PlanView-Dgg-WTEc.js +0 -4
  160. package/dist/assets/SessionSwitcherDropdown-CJTrc8K7.js +0 -1
  161. package/dist/assets/SettingsView-D9yRuFZw.js +0 -28
  162. package/dist/assets/WalkthroughView-D9Q4lr5x.js +0 -4
  163. package/dist/assets/de-B_LdJwEM.js +0 -9
  164. package/dist/assets/es-CubfsAYV.js +0 -15
  165. package/dist/assets/fr-5qJM0nFS.js +0 -13
  166. package/dist/assets/index-BW82eK5v.css +0 -1
  167. package/dist/assets/index-rlLjZUM5.js +0 -7
  168. package/dist/assets/ja-DJYIBUlH.js +0 -15
  169. package/dist/assets/ko-DcUBkB7y.js +0 -15
  170. package/dist/assets/main-DLBxKIoX.js +0 -926
  171. package/dist/assets/markdownCore-DG6GHLF4.js +0 -3
  172. package/dist/assets/pl-rB6BLcio.js +0 -15
  173. package/dist/assets/pt-BR-DcwtlO-o.js +0 -15
  174. package/dist/assets/renderMobileApp-hQJTnr8B.js +0 -25
  175. package/dist/assets/runtimeEndpointReset-BDh7r8BL.js +0 -15
  176. package/dist/assets/scheduledTasksApi-CAGPh_gZ.js +0 -1
  177. package/dist/assets/uk-INZlFD9A.js +0 -15
  178. package/dist/assets/useAppFontEffects-Cll4gnsh.js +0 -7268
  179. package/dist/assets/zh-CN-Dzda8xa1.js +0 -15
  180. package/dist/assets/zh-TW-Cwn3rNYZ.js +0 -15
@@ -2599,6 +2599,25 @@ export async function getUntrackedDiffs(directory, filePaths = [], { concurrency
2599
2599
  return results;
2600
2600
  }
2601
2601
 
2602
+ const refResolvesToCommit = async (git, ref) => git
2603
+ .raw(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
2604
+ .then((value) => Boolean(String(value || '').trim()))
2605
+ .catch(() => false);
2606
+
2607
+ /**
2608
+ * The branch list includes remote-only branches that `ls-remote` reported but
2609
+ * the repository never fetched (#2098), so a comparison can name a ref that does
2610
+ * not exist locally. Say that plainly instead of letting git's "ambiguous
2611
+ * argument" surface as an opaque failure.
2612
+ */
2613
+ async function assertRangeRefsResolve(git, refs) {
2614
+ for (const ref of refs) {
2615
+ if (!(await refResolvesToCommit(git, ref))) {
2616
+ throw new Error(`Ref "${ref}" is not available locally. Fetch it before comparing.`);
2617
+ }
2618
+ }
2619
+ }
2620
+
2602
2621
  export async function getRangeDiff(directory, { base, head, path: filePath, contextLines = 3 } = {}) {
2603
2622
  const { directoryPath, directoryGit, repoRoot, git } = await createRepositoryGitContext(directory);
2604
2623
  const baseRef = typeof base === 'string' ? base.trim() : '';
@@ -2641,6 +2660,8 @@ export async function getRangeDiff(directory, { base, head, path: filePath, cont
2641
2660
  }
2642
2661
  }
2643
2662
 
2663
+ await assertRangeRefsResolve(git, [resolvedBase, headRef]);
2664
+
2644
2665
  const args = ['diff', '--no-color'];
2645
2666
  if (typeof contextLines === 'number' && !Number.isNaN(contextLines)) {
2646
2667
  args.push(`-U${Math.max(0, contextLines)}`);
@@ -2660,7 +2681,8 @@ const BRANCH_CREATION_SOURCE_RE = /^branch: Created from (.+)$/;
2660
2681
  * Parse a branch reflog (`git reflog show --format=%gs <branch>`) and return the
2661
2682
  * ref the branch was created from, when that source is itself a named ref.
2662
2683
  *
2663
- * Returns null when the branch was created from `HEAD@{...}` or a raw commit
2684
+ * Returns null when the branch was created from `HEAD` (bare, as `git switch -c`
2685
+ * / `git checkout -b` without an explicit start point record) or a raw commit
2664
2686
  * (detached start): the original branch name is not recorded anywhere in that
2665
2687
  * case, and guessing a base from commit topology would be a heuristic, not an
2666
2688
  * answer. Callers should ask the user to pick a base instead.
@@ -2675,7 +2697,9 @@ export function parseBranchCreationSource(reflogText) {
2675
2697
  const match = lines[index].match(BRANCH_CREATION_SOURCE_RE);
2676
2698
  if (!match) continue;
2677
2699
  const source = match[1].trim();
2678
- if (!source || /^HEAD@/.test(source) || /^[0-9a-f]{7,40}$/i.test(source)) {
2700
+ // Bare `HEAD` (`git switch -c` from the current branch) and `HEAD@{...}`
2701
+ // (detached start) both lack a named source; a raw commit hash does too.
2702
+ if (!source || /^HEAD(@|$)/.test(source) || /^[0-9a-f]{7,40}$/i.test(source)) {
2679
2703
  return null;
2680
2704
  }
2681
2705
  return source;
@@ -2738,6 +2762,8 @@ export async function getRangeFiles(directory, { base, head } = {}) {
2738
2762
  // ignore
2739
2763
  }
2740
2764
 
2765
+ await assertRangeRefsResolve(git, [resolvedBase, headRef]);
2766
+
2741
2767
  // `-C` (copy detection among changed files only, so cheap) makes copies
2742
2768
  // surface as C entries instead of plain additions; rename detection is on
2743
2769
  // by default.
@@ -3744,7 +3770,7 @@ async function filterActiveRemoteBranches(git, remoteBranches) {
3744
3770
  }
3745
3771
  }));
3746
3772
 
3747
- return remoteBranches.filter(remoteBranch => {
3773
+ const activeBranches = remoteBranches.filter(remoteBranch => {
3748
3774
  const match = remoteBranch.match(/^remotes\/[^\/]+\/(.+)$/);
3749
3775
  if (!match) return false;
3750
3776
  const remoteName = remoteBranch.split('/')[1];
@@ -3752,6 +3778,25 @@ async function filterActiveRemoteBranches(git, remoteBranches) {
3752
3778
  if (unreachableRemotes.has(remoteName)) return true;
3753
3779
  return branchesByRemote.get(remoteName)?.has(branchName) ?? false;
3754
3780
  });
3781
+
3782
+ // A branch pushed to the remote that was never fetched locally has no
3783
+ // remote-tracking ref, so `git branch` never reports it — but ls-remote
3784
+ // just told us it exists. Add those so a freshly pushed branch shows up
3785
+ // without requiring a fetch first (#2098). Unreachable remotes have no
3786
+ // ls-remote data and therefore add nothing here; their local view above
3787
+ // is preserved unchanged.
3788
+ const seenBranches = new Set(activeBranches);
3789
+ for (const [remoteName, actualRemoteBranches] of branchesByRemote) {
3790
+ for (const branchName of actualRemoteBranches) {
3791
+ const qualifiedBranch = `remotes/${remoteName}/${branchName}`;
3792
+ if (!seenBranches.has(qualifiedBranch)) {
3793
+ seenBranches.add(qualifiedBranch);
3794
+ activeBranches.push(qualifiedBranch);
3795
+ }
3796
+ }
3797
+ }
3798
+
3799
+ return activeBranches;
3755
3800
  } catch (error) {
3756
3801
  console.warn('Failed to filter active remote branches, returning all:', error.message);
3757
3802
  return remoteBranches;
@@ -3770,12 +3815,81 @@ export async function createBranch(directory, branchName, options = {}) {
3770
3815
  }
3771
3816
  }
3772
3817
 
3818
+ // Deliberately not `--quiet`: simple-git resolves a quiet non-zero exit as
3819
+ // success, so the ref itself has to be echoed for the answer to mean anything.
3820
+ const gitRefExists = async (git, ref) => {
3821
+ try {
3822
+ const output = await git.raw(['show-ref', '--verify', ref]);
3823
+ return String(output).trim().length > 0;
3824
+ } catch {
3825
+ return false;
3826
+ }
3827
+ };
3828
+
3829
+ /**
3830
+ * The branch selector lists remote-tracking branches beside local ones, so
3831
+ * picking `origin/main` means "work on main", not "detach HEAD at the remote's
3832
+ * commit" — which is what a literal checkout of a remote-tracking ref does.
3833
+ * Resolve such a pick to the local branch, creating it with tracking when it
3834
+ * does not exist yet. Anything we cannot resolve is checked out as requested,
3835
+ * leaving git's own DWIM behavior intact.
3836
+ */
3837
+ const resolveBranchCheckoutTarget = async (git, branchName) => {
3838
+ const requested = String(branchName || '').trim();
3839
+ if (!requested) {
3840
+ throw new Error('Branch name is required');
3841
+ }
3842
+
3843
+ const asRequested = { branch: requested, remoteRef: null };
3844
+
3845
+ if (await gitRefExists(git, `refs/heads/${requested}`)) {
3846
+ return asRequested;
3847
+ }
3848
+
3849
+ const remoteRef = requested.replace(/^remotes\//, '');
3850
+ const remotes = await git.getRemotes();
3851
+ const remote = remotes.find((entry) => entry?.name && remoteRef.startsWith(`${entry.name}/`));
3852
+ if (!remote) {
3853
+ return asRequested;
3854
+ }
3855
+
3856
+ const localBranch = remoteRef.slice(remote.name.length + 1);
3857
+ // `origin/HEAD` names no branch of its own; it is a pointer to one.
3858
+ if (!localBranch || localBranch === 'HEAD') {
3859
+ return asRequested;
3860
+ }
3861
+
3862
+ // The branch list also carries branches that only `ls-remote` knows about
3863
+ // (#2098): they exist on the remote but were never fetched, so there is no
3864
+ // remote-tracking ref and a literal checkout fails with a pathspec error.
3865
+ // Fetch the single branch first so the tracking ref exists, then fall through
3866
+ // to the normal create-with-tracking path.
3867
+ if (!(await gitRefExists(git, `refs/remotes/${remoteRef}`))) {
3868
+ try {
3869
+ await git.fetch(remote.name, localBranch);
3870
+ } catch (error) {
3871
+ throw new Error(`Failed to fetch ${localBranch} from ${remote.name}: ${error?.message || error}`);
3872
+ }
3873
+ if (!(await gitRefExists(git, `refs/remotes/${remoteRef}`))) {
3874
+ throw new Error(`Branch ${localBranch} no longer exists on remote ${remote.name}`);
3875
+ }
3876
+ }
3877
+
3878
+ const localExists = await gitRefExists(git, `refs/heads/${localBranch}`);
3879
+ return { branch: localBranch, remoteRef: localExists ? null : remoteRef };
3880
+ };
3881
+
3773
3882
  export async function checkoutBranch(directory, branchName) {
3774
3883
  const { git } = await createRepositoryGitContext(directory);
3775
3884
 
3776
3885
  try {
3777
- await git.checkout(branchName);
3778
- return { success: true, branch: branchName };
3886
+ const target = await resolveBranchCheckoutTarget(git, branchName);
3887
+ if (target.remoteRef) {
3888
+ await git.raw(['checkout', '-b', target.branch, '--track', target.remoteRef]);
3889
+ } else {
3890
+ await git.checkout(target.branch);
3891
+ }
3892
+ return { success: true, branch: target.branch };
3779
3893
  } catch (error) {
3780
3894
  console.error('Failed to checkout branch:', error);
3781
3895
  throw error;
@@ -3895,7 +4009,15 @@ export async function getWorktrees(directory) {
3895
4009
  path: entry.worktree,
3896
4010
  }));
3897
4011
  } catch (error) {
3898
- console.warn('Failed to list worktrees, returning empty list:', error?.message || error);
4012
+ // Worktrees are an optional feature. When the caller passes a directory
4013
+ // that is not inside any git repository (for example, the managed
4014
+ // OpenCode's working directory or an unconfigured project path), git
4015
+ // exits with "fatal: not a git repository ...". Treat that as an
4016
+ // authoritative empty result so the route handler can still respond
4017
+ // 200 [] and the desktop main.log stays free of noise.
4018
+ if (!isNotGitRepositoryError(error)) {
4019
+ console.warn('Failed to list worktrees, returning empty list:', error?.message || error);
4020
+ }
3899
4021
  return [];
3900
4022
  }
3901
4023
  }
@@ -2,10 +2,11 @@ import { execFileSync } from 'node:child_process';
2
2
  import fs from 'node:fs';
3
3
  import os from 'node:os';
4
4
  import path from 'node:path';
5
- import { afterEach, describe, expect, it } from 'vitest';
5
+ import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';
6
6
  import simpleGit from 'simple-git';
7
7
 
8
8
  import {
9
+ checkoutBranch,
9
10
  checkoutCommit,
10
11
  cherryPick,
11
12
  createWorktree,
@@ -13,6 +14,7 @@ import {
13
14
  getBranches,
14
15
  getRangeDiff,
15
16
  getStatus,
17
+ getWorktrees,
16
18
  isGitRepository,
17
19
  populateWorktreeWithLockRecovery,
18
20
  removeWorktree,
@@ -463,6 +465,51 @@ describe('worktree root resolution', () => {
463
465
  });
464
466
  });
465
467
 
468
+ // ---------------------------------------------------------------------------
469
+ // getWorktrees
470
+ // ---------------------------------------------------------------------------
471
+
472
+ describe('getWorktrees', () => {
473
+ if (!canRunGit()) {
474
+ it.skip('git binary not available', () => {});
475
+ return;
476
+ }
477
+
478
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
479
+
480
+ afterEach(() => {
481
+ warnSpy.mockClear();
482
+ });
483
+
484
+ afterAll(() => {
485
+ warnSpy.mockRestore();
486
+ });
487
+
488
+ it('returns an empty list for a non-git directory without warning', async () => {
489
+ const nonGit = createTempDir();
490
+
491
+ const result = await getWorktrees(nonGit);
492
+
493
+ expect(result).toEqual([]);
494
+ expect(warnSpy).not.toHaveBeenCalled();
495
+ });
496
+
497
+ it('returns the worktrees for a real git repository', async () => {
498
+ const repo = createTempDir();
499
+ runGit(repo, ['init', '-b', 'main']);
500
+ runGit(repo, ['config', 'user.email', 'test@example.com']);
501
+ runGit(repo, ['config', 'user.name', 'Test User']);
502
+ fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
503
+ runGit(repo, ['add', 'README.md']);
504
+ runGit(repo, ['commit', '-m', 'init']);
505
+
506
+ const result = await getWorktrees(repo);
507
+
508
+ expect(Array.isArray(result)).toBe(true);
509
+ expect(warnSpy).not.toHaveBeenCalled();
510
+ });
511
+ });
512
+
466
513
  // ---------------------------------------------------------------------------
467
514
  // createWorktree
468
515
  // ---------------------------------------------------------------------------
@@ -1006,6 +1053,92 @@ describe('checkoutCommit', () => {
1006
1053
  });
1007
1054
  });
1008
1055
 
1056
+ // ---------------------------------------------------------------------------
1057
+ // checkoutBranch
1058
+ // ---------------------------------------------------------------------------
1059
+
1060
+ describe('checkoutBranch', () => {
1061
+ it('checks out a local branch by name', async () => {
1062
+ const { repository } = createRepositoryWithRemote();
1063
+ runGit(repository, ['branch', 'feature']);
1064
+
1065
+ const result = await checkoutBranch(repository, 'feature');
1066
+
1067
+ expect(result).toEqual({ success: true, branch: 'feature' });
1068
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'HEAD']).trim()).toBe('feature');
1069
+ });
1070
+
1071
+ it('creates a tracking local branch instead of detaching HEAD on a remote branch', async () => {
1072
+ const { repository } = createRepositoryWithRemote({ defaultBranch: 'react' });
1073
+
1074
+ const result = await checkoutBranch(repository, 'origin/react');
1075
+
1076
+ expect(result).toEqual({ success: true, branch: 'react' });
1077
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'HEAD']).trim()).toBe('react');
1078
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'react@{upstream}']).trim()).toBe('origin/react');
1079
+ });
1080
+
1081
+ it('checks out the existing local branch when a remote branch is picked', async () => {
1082
+ const { repository } = createRepositoryWithRemote({ defaultBranch: 'react' });
1083
+ runGit(repository, ['branch', 'react', 'origin/react']);
1084
+
1085
+ const result = await checkoutBranch(repository, 'origin/react');
1086
+
1087
+ expect(result).toEqual({ success: true, branch: 'react' });
1088
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'HEAD']).trim()).toBe('react');
1089
+ });
1090
+
1091
+ it('accepts the remotes/ prefixed form of a remote branch', async () => {
1092
+ const { repository } = createRepositoryWithRemote({ defaultBranch: 'react' });
1093
+
1094
+ const result = await checkoutBranch(repository, 'remotes/origin/react');
1095
+
1096
+ expect(result).toEqual({ success: true, branch: 'react' });
1097
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'HEAD']).trim()).toBe('react');
1098
+ });
1099
+
1100
+ it('prefers a local branch whose name looks like a remote ref', async () => {
1101
+ const { repository } = createRepositoryWithRemote({ defaultBranch: 'react' });
1102
+ runGit(repository, ['branch', 'origin/react']);
1103
+
1104
+ const result = await checkoutBranch(repository, 'origin/react');
1105
+
1106
+ expect(result).toEqual({ success: true, branch: 'origin/react' });
1107
+ expect(runGit(repository, ['symbolic-ref', 'HEAD']).trim()).toBe('refs/heads/origin/react');
1108
+ });
1109
+
1110
+ it('rejects an unknown branch', async () => {
1111
+ const { repository } = createRepositoryWithRemote();
1112
+ await expect(checkoutBranch(repository, 'does-not-exist')).rejects.toThrow();
1113
+ });
1114
+
1115
+ it('fetches a remote-only branch that was never fetched locally (#2735)', async () => {
1116
+ const { repository, remote } = createRepositoryWithRemote({ defaultBranch: 'react' });
1117
+ // A collaborator pushes straight to the remote; this repository never
1118
+ // fetches, so `remotes/origin/collab` is listed (#2098) with no local ref.
1119
+ const collaborator = createTempDir();
1120
+ runGit(collaborator, ['clone', remote, '.']);
1121
+ runGit(collaborator, ['config', 'user.email', 'test@example.com']);
1122
+ runGit(collaborator, ['config', 'user.name', 'Test']);
1123
+ runGit(collaborator, ['checkout', '-b', 'collab']);
1124
+ runGit(collaborator, ['push', 'origin', 'collab']);
1125
+
1126
+ const result = await checkoutBranch(repository, 'remotes/origin/collab');
1127
+
1128
+ expect(result).toEqual({ success: true, branch: 'collab' });
1129
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'HEAD']).trim()).toBe('collab');
1130
+ expect(runGit(repository, ['rev-parse', '--abbrev-ref', 'collab@{upstream}']).trim()).toBe('origin/collab');
1131
+ });
1132
+
1133
+ it('reports a clear failure when the remote branch no longer exists', async () => {
1134
+ const { repository } = createRepositoryWithRemote({ defaultBranch: 'react' });
1135
+
1136
+ await expect(checkoutBranch(repository, 'remotes/origin/never-pushed')).rejects.toThrow(
1137
+ /Failed to fetch never-pushed from origin/
1138
+ );
1139
+ });
1140
+ });
1141
+
1009
1142
  // ---------------------------------------------------------------------------
1010
1143
  // cherryPick
1011
1144
  // ---------------------------------------------------------------------------
@@ -1322,6 +1455,47 @@ describe.runIf(canRunGit())('getBranches', () => {
1322
1455
  // decide whether a base branch exists at all.
1323
1456
  expect(branches.all).toContain('remotes/origin/react');
1324
1457
  });
1458
+
1459
+ it('includes remote branches with no local tracking ref and prunes refs deleted on the remote (#2098)', async () => {
1460
+ const remote = createTempDir();
1461
+ runGit(remote, ['init', '--bare', '--initial-branch=main']);
1462
+
1463
+ const repository = createTempDir();
1464
+ runGit(repository, ['init', '-b', 'main']);
1465
+ runGit(repository, ['config', 'user.email', 'test@example.com']);
1466
+ runGit(repository, ['config', 'user.name', 'Test']);
1467
+ fs.writeFileSync(path.join(repository, 'README.md'), '# Test\n');
1468
+ runGit(repository, ['add', 'README.md']);
1469
+ runGit(repository, ['commit', '-m', 'init']);
1470
+ runGit(repository, ['remote', 'add', 'origin', remote]);
1471
+ runGit(repository, ['push', '-u', 'origin', 'main']);
1472
+ runGit(repository, ['checkout', '-b', 'feature-known']);
1473
+ runGit(repository, ['push', '-u', 'origin', 'feature-known']);
1474
+ // This tracking ref will go stale: the collaborator deletes the branch on
1475
+ // the remote below, and the list must prune it.
1476
+ runGit(repository, ['checkout', '-b', 'feature-stale']);
1477
+ runGit(repository, ['push', '-u', 'origin', 'feature-stale']);
1478
+ runGit(repository, ['checkout', 'main']);
1479
+ runGit(repository, ['branch', '-D', 'feature-stale']);
1480
+
1481
+ // A collaborator pushes a branch straight to the remote and deletes
1482
+ // another; this repository never fetches, so it has no local
1483
+ // remote-tracking ref for feature-remote-only.
1484
+ const collaborator = createTempDir();
1485
+ runGit(collaborator, ['clone', remote, '.']);
1486
+ runGit(collaborator, ['config', 'user.email', 'test@example.com']);
1487
+ runGit(collaborator, ['config', 'user.name', 'Test']);
1488
+ runGit(collaborator, ['checkout', '-b', 'feature-remote-only']);
1489
+ runGit(collaborator, ['push', 'origin', 'feature-remote-only']);
1490
+ runGit(collaborator, ['push', 'origin', ':feature-stale']);
1491
+
1492
+ const branches = await getBranches(repository);
1493
+
1494
+ expect(branches.all).toContain('remotes/origin/feature-remote-only');
1495
+ expect(branches.all).toContain('remotes/origin/feature-known');
1496
+ expect(branches.all).toContain('feature-known');
1497
+ expect(branches.all).not.toContain('remotes/origin/feature-stale');
1498
+ });
1325
1499
  });
1326
1500
 
1327
1501
  describe.runIf(canRunGit())('getRangeDiff', () => {
@@ -1337,6 +1511,14 @@ describe.runIf(canRunGit())('getRangeDiff', () => {
1337
1511
 
1338
1512
  expect(diff).toContain('feature.txt');
1339
1513
  });
1514
+
1515
+ it('names an unfetched remote-only ref instead of failing with git\'s ambiguous argument (#2735)', async () => {
1516
+ const { repository } = createRepositoryWithRemote({ defaultBranch: 'react' });
1517
+
1518
+ await expect(
1519
+ getRangeDiff(repository, { base: 'remotes/origin/never-fetched', head: 'next' })
1520
+ ).rejects.toThrow(/is not available locally/);
1521
+ });
1340
1522
  });
1341
1523
 
1342
1524
  describe('parseBranchCreationSource', () => {
@@ -1354,6 +1536,14 @@ describe('parseBranchCreationSource', () => {
1354
1536
  expect(parseBranchCreationSource(reflog)).toBeNull();
1355
1537
  });
1356
1538
 
1539
+ it('returns null when the branch was created from the current HEAD without a named source', () => {
1540
+ // `git switch -c <branch>` / `git checkout -b <branch>` from the current
1541
+ // branch record `branch: Created from HEAD` in the reflog (git 2.x). The
1542
+ // source branch name is not recorded, so no base can be derived from it.
1543
+ const reflog = 'branch: Created from HEAD';
1544
+ expect(parseBranchCreationSource(reflog)).toBeNull();
1545
+ });
1546
+
1357
1547
  it('returns null when the branch was created from a raw commit', () => {
1358
1548
  const reflog = 'branch: Created from 9a3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b';
1359
1549
  expect(parseBranchCreationSource(reflog)).toBeNull();
@@ -0,0 +1,97 @@
1
+ # Linear Module Documentation
2
+
3
+ ## Purpose
4
+
5
+ This module owns Linear OAuth, issue lookup, Linear-team-to-project mapping, issue status updates, and session status comments on Linear issues. Credentials live on the OpenChamber server, so web, desktop, and a phone paired to that host share them. You can store more than one Linear workspace; exactly one is current. Issue list, mapping, and new OAuth default to the current workspace. Session status comments use the workspace that started the session. The right-hand context panel lists issues for the current workspace, can switch workspace, filters the list, shows a read-only card, changes status or closes the issue, and starts a session or worktree. Start session stays visible in a footer while the issue card scrolls. The chat picker lists issues and attaches them to a message. New Worktree can also start from a Linear issue in the currently active project. A session started from a Linear issue can post started/completed/failure comments, each with an OpenChamber session link. Those comments are opt-in and only appear when this server has a publicly reachable address.
6
+
7
+ VS Code omits Linear (`RuntimeAPIs.linear` is optional). Hide Linear UI when the API is missing.
8
+
9
+ ## Entrypoints and structure
10
+
11
+ - `packages/web/server/lib/linear/index.js`: public server entrypoint. `routes.js` loads it lazily with `await import('./index.js')`.
12
+ - `packages/web/server/lib/linear/routes.js`: Express registration for the public callback, `/api/linear/auth/*`, `/api/linear/issues/*`, `/api/linear/mapping`, and `/api/linear/session-status`.
13
+ - `packages/web/server/lib/linear/auth.js`: auth file, client id, scopes, redirect URI.
14
+ - `packages/web/server/lib/linear/oauth.js`: authorization-code + PKCE S256, public callback broker handoff, refresh, revoke.
15
+ - `packages/web/server/lib/linear/client.js`: GraphQL helper, viewer/organization lookup, and access-token refresh. GraphQL errors prefer `extensions.userPresentableMessage` / validation constraints over the generic `Argument Validation Error` label. User-facing Linear errors set `LinearApiError.userError`. Requests send `public-file-urls-expire-in: 3600` so file URLs in issue descriptions and comments are temporarily readable in the panel.
16
+ - `packages/web/server/lib/linear/issues.js`: list/search/get issues, team workflow states, `issueUpdate`, and `commentCreate`. Parses identifiers and Linear URLs. `issueUpdate` resolves identifiers to UUIDs first because Linear's mutation does not accept `ENG-12`. List/get include `state.id`, `priority` (0–4), and labels (`id`, `name`, sanitized hex `color`) so the panel can show them and update status.
17
+ - `packages/web/server/lib/linear/teams.js`: list Linear teams for mapping UI.
18
+ - `packages/web/server/lib/linear/mapping.js`: persist default and per-team OpenChamber project paths. Separate from the auth file so disconnect does not wipe maps.
19
+ - `packages/web/server/lib/linear/status.js`: persist per-session started/completed/failure flags and post the matching Linear comment with an open-session URL. Posts nothing unless the user opted in and the session origin is public; `isPublicSessionOrigin` rejects loopback, private LAN, carrier-grade NAT, link-local and single-label hosts. The dedupe file keeps the newest 500 sessions.
20
+ - `packages/web/server/lib/linear/status-runtime.js`: on the OpenCode event hub, first `session.status` idle after started posts completed once; `session.error` (except abort) posts failure once.
21
+ - `packages/web/src/api/linear.ts`: web client wrapper. Electron and hosted/Capacitor mobile reuse it. VS Code omits `linear`.
22
+
23
+ ## Public routes
24
+
25
+ - `GET /linear/oauth/callback`: public fallback for an explicitly configured direct redirect URI. The built-in flow uses the stable callback broker instead, because desktop and self-hosted instances may have private or dynamic addresses.
26
+ - `GET /api/linear/auth/status`: connected flag, current user/organization/scope, and `workspaces` (id, name, current, user, authorizedAt). Never returns tokens. A 401 on the current workspace drops that workspace only; if another remains, status returns that one instead of disconnected. Identity refresh does not bump `authorizedAt`.
27
+ - `POST /api/linear/auth/start`: returns `{ authorizationUrl, expiresIn, scope }`. Body may include `origin: "desktop"` so the callback page can raise the desktop window. The authorize URL uses `prompt=consent` so Add workspace can pick a different Linear org. Completing OAuth stores or replaces that org and makes it current.
28
+ - `POST /api/linear/auth/activate`: body `{ organizationId }`. Makes that stored workspace current. 400 if the id is missing, 404 if it is not stored.
29
+ - `DELETE /api/linear/auth`: revokes the current workspace refresh token when present, then drops that workspace only. Other stored workspaces stay. Mapping is kept.
30
+ - `GET /api/linear/issues/list?query=&cursor=&status=&assignee=&teamId=&priority=`: issues from the current workspace. Omitted `status` is incomplete states (same as the chat picker). The panel sends `all`, `backlog`, `todo` (Linear `unstarted`), `started` (In Progress, excluding the In Review name), `inReview` (state name In Review), `completed` (Done), `canceled` (excluding the Duplicate name), or `duplicate` (state type or name Duplicate). `assignee` is `any` (default) or `me`. `teamId` limits the list to that Linear team. `priority` is `all` (default), `none`, `urgent`, `high`, `medium`, or `low`. An identifier or Linear URL returns that issue even if it is completed and ignores the other filters. Each issue includes `state.id` when Linear sends it, plus `priority` (0 none through 4 low) and `labels`. Never returns tokens.
31
+ - `GET /api/linear/issues/get?id=`: one issue by UUID or identifier, including description, comments, team, `state.id`, priority, and labels.
32
+ - `GET /api/linear/issues/states?teamId=`: workflow states for that Linear team (`id`, `name`, `type`, `position`), ordered like Linear's workflow: type (backlog, unstarted, started, completed, canceled) then position. Missing `teamId` is 400. Linear not-found or validation errors are 400 with Linear's presentable message. Disconnected is `{ connected: false }` with HTTP 200.
33
+ - `POST /api/linear/issues/update`: body `{ id, stateId }`. `id` may be a UUID, identifier, or Linear URL; identifiers are resolved before `issueUpdate` because Linear's mutation requires a UUID. Returns the updated issue. Closing an issue is this same call with the team's first `type: completed` state. Missing `id` or `stateId` is 400. Linear validation (for example a non-UUID `stateId`) is 400 with Linear's presentable message. A GraphQL 401 clears that workspace only. Disconnected is `{ connected: false }` with HTTP 200.
34
+ - `GET /api/linear/mapping`: stored default project plus live Linear teams with their mapped paths. Missing file is empty mapping. Malformed file is 500, not empty success. Disconnected is `{ connected: false }` with HTTP 200.
35
+ - `PUT /api/linear/mapping`: replace default project and per-team paths. Body `{ defaultProjectPath, teamProjectPaths }`. Failed write does not touch tokens. Disconnected is `{ connected: false }` and does not save.
36
+ - `GET /api/linear/preferences`: `{ sessionComments }`. `PUT /api/linear/preferences` with body `{ sessionComments: boolean }` replaces it and returns the stored value. A non-boolean body is 400. The preference is server-side because the event hub posts completed/failure without going through the interface.
37
+ - `POST /api/linear/session-status`: post a started/completed/failure comment on the linked Linear issue. Body `{ kind, sessionId, issueIdentifier?, sessionOrigin? }`. `started` requires `issueIdentifier`. `completed` and `failure` reuse the stored issue and open URL from `started`. Each kind posts at most once per session. Answers in this order: disconnected is `{ connected: false }` with HTTP 200; comments turned off is `skipped: 'disabled'`; a `sessionOrigin` nobody else can reach is `skipped: 'origin-not-public'`. `sessionOrigin` must be `http` or `https` with no path, and must resolve to a public host — loopback, private LAN and desktop deep links post no comment at all rather than a link only its author can open. Comment bodies are one markdown link: `[OpenChamber session started](url)` so Linear keeps the `?session=` query. The comment carries no issue or session title: it already sits on the issue, and titles routinely contain brackets that would break the link. Invalid body is 400.
38
+
39
+ `POST /api/linear/auth/start`, `PUT /api/linear/mapping`, `POST /api/linear/issues/update`, and `POST /api/linear/session-status` parse JSON on the route (`16kb`). They are not on the `/api` 50mb allowlist.
40
+
41
+ Disconnected list/get/states/update/mapping/session-status return `{ connected: false }` with HTTP 200 so the picker and panel can show an empty state. Missing `id` on get is 400. Missing `teamId` on states is 400.
42
+
43
+ ## Auth storage and config
44
+
45
+ - Auth storage: `~/.config/openchamber/linear-auth.json` (or `$OPENCHAMBER_DATA_DIR/linear-auth.json`). Shape is `{ workspaces: [ { accessToken, refreshToken, user, organization, workspaceId, current, authorizedAt, ... } ] }`. `workspaceId` is the Linear organization id, or `user:<id>` when there is no org, or `legacy` for a migrated token with neither. A legacy single-object file is rewritten to this list on read. Reconnecting the same org replaces that slot.
46
+ - Mapping storage: `~/.config/openchamber/linear-mapping.json` (same data dir). Shape is `{ workspaces: { [workspaceId]: { defaultProjectPath, teamProjectPaths } } }`. Reads and writes use the current workspace slice. A legacy flat file is wrapped under the current workspace id on read. Disconnect does not wipe maps. Writes are atomic and file mode is `0o600`.
47
+ - Session status storage: `~/.config/openchamber/linear-session-status.json` (same data dir). Writes are atomic and file mode is `0o600`. Dedupes started/completed/failure per OpenChamber session id.
48
+ - Writes are atomic and file mode is `0o600`.
49
+ - Client ID: `OPENCHAMBER_LINEAR_CLIENT_ID` -> `settings.json` `linearClientId` -> baked-in public default.
50
+ - Client secret: `OPENCHAMBER_LINEAR_CLIENT_SECRET` -> `settings.json` `linearClientSecret`. Optional with PKCE. Do not commit a secret.
51
+ - Scopes: `OPENCHAMBER_LINEAR_SCOPES` -> `settings.json` `linearScopes` -> `read,write,comments:create`.
52
+ - Session comments: `settings.json` `linearSessionComments`, boolean, absent means off. Written only through `PUT /api/linear/preferences`.
53
+ - Broker URL: `OPENCHAMBER_LINEAR_BROKER_URL` -> `settings.json` `linearBrokerUrl` -> `https://api.openchamber.dev/v1/oauth/linear`.
54
+ - Redirect URI: `OPENCHAMBER_LINEAR_REDIRECT_URI` -> `settings.json` `linearRedirectUri` -> `<broker-url>/callback`. Setting an explicit redirect URI bypasses the broker for custom/self-hosted OAuth applications.
55
+
56
+ Linear requires an exact callback match. The built-in application registers `https://api.openchamber.dev/v1/oauth/linear/callback`; the broker holds only the short-lived authorization code. The local OpenChamber server keeps the claim secret and PKCE verifier, exchanges the code for tokens locally, then acknowledges the handoff. Custom brokers must expose `/start`, `/callback`, `/poll`, and `/complete` with the same contract.
57
+
58
+ ## OAuth contract
59
+
60
+ - Authorization code + PKCE S256. Linear has no device flow.
61
+ - The broker stores hashes of OAuth state and a separate claim secret for ten minutes. It never receives the PKCE verifier or Linear tokens. The local status polling path claims a completed broker result and persists tokens on the OpenChamber server.
62
+ - Access tokens expire in 24 hours. Refresh tokens rotate; persist the new refresh token from every successful refresh. Concurrent refreshes share one in-flight promise per workspace.
63
+ - `invalid_grant` / 401 on refresh clears that workspace only so a dead token cannot loop. If it was the last workspace, status becomes disconnected.
64
+ - A GraphQL 401 after a valid-looking token also clears that workspace. A network failure while a token is stored does not: status stays connected with the last known user.
65
+
66
+ ## Project mapping
67
+
68
+ OpenChamber has projects (directories), not accounts or organizations. Mapping is how create-session (picker and the right-hand panel) picks a directory:
69
+
70
+ 1. If the issue's Linear team has a project path, use that.
71
+ 2. Otherwise use the default project path.
72
+ 3. If neither is set, the UI tells the user to map the team in Settings → Integrations. It does not fall back to the currently active project.
73
+
74
+ A worktree started from the panel or picker is created in that mapped project. New Worktree from Git is different: it stays in the currently active project.
75
+
76
+ ## Shared UI
77
+
78
+ - `RuntimeAPIs.linear` is optional. Hide Linear settings, the chat picker, and the panel when it is missing (VS Code).
79
+ - Store: `packages/ui/src/stores/useLinearAuthStore.ts`. App start refreshes it from `App.tsx` and `MobileApp.tsx`, not `VSCodeApp`.
80
+ - Settings: first-party section on the Integrations page. Connect opens the authorization URL and polls status until the workspace list or current `authorizedAt` changes, so Add workspace is not treated as done just because a workspace was already connected. When connected, map a default project and optional per-team projects for the current workspace. Other stored workspaces appear in a list with Switch to. Disconnect removes the current workspace only. The panel can also switch the current workspace when more than one is stored.
81
+ - Context panel: desktop/web right-hand rail surface `linear` (`packages/ui/src/components/views/LinearIssuesView.tsx`). Singleton like git/pr. The rail icon is hidden until a Linear workspace is connected; disconnecting while the panel is open closes it. List/search defaults to all issues; the status filter is All, Backlog, To Do, In Progress, In Review, Done, Canceled, and Duplicate, matching the card status order. Identifier/URL still finds completed. Status, assignee, team, and priority filters persist in `useUIStore` so they survive rail switches. Non-default list filters and search tint the filter icon `text-primary`, same as the context rail; one control clears them, not the workspace switch. Changing those filters keeps the previous list until the next page arrives and does not disable the filter row. On a narrow panel search and the filters other than status drop to icons; status keeps its label. The card shows priority and labels. Comments render as an avatar timeline matching the pull request panel, so both context surfaces read alike; comment authors carry `avatarUrl`. The card is read-only except status (`issueUpdate`) and Close (first completed workflow state). Start session stays in a footer while the description and comments scroll. Start session / worktree share `startLinearIssueSession` with the picker. No create-issue, no writing comments, no polling. VS Code and the mobile workspace drawer omit this rail.
82
+ - Chat: composer attach menu "Link Linear Issue" attaches body and comments as `linear-issue` context on the next send. Exclusive with a linked GitHub issue or PR. The attached issue is stored on session metadata (`kind: 'linear'`) so work status can show it. Clicking that work-status row opens the Linear rail when Linear is connected on desktop/web; otherwise the Linear URL. Managed Chats do not offer start-from-issue; those sessions have no project directory.
83
+ - Worktree: New Worktree can start from a Linear issue. It uses the currently active project and does not consult team-to-project mapping. GitHub issue/PR and Linear issue are exclusive on that form.
84
+ - Status comments: off until the user turns them on in Settings -> Integrations -> Linear (`LinearSessionComments.tsx`). When on, create-session and worktree-from-Linear post `started` after the session exists. The event hub posts `completed` on the first idle after that, and `failure` on `session.error` except `MessageAbortedError`. Failed comments must not fail session create. Comment bodies are English (they live on Linear) and are one markdown link named `OpenChamber session started` (or completed/failed). Web uses `/?session=<id>` on the current origin; desktop reports the loopback origin its own server listens on, not `openchamber-ui://`. A Linear comment is read by the whole team, so the server posts nothing when that origin is not publicly reachable rather than publishing a link only its author could open. Opening `/?session=` selects that session after the global session list can resolve its directory.
85
+ - Magic prompts: `linear.issue.review.visible` / `.instructions`. Do not reuse the GitHub issue-review templates for Linear.
86
+
87
+ ## Notes for contributors
88
+
89
+ The implementation and deployment hand-off for the stable callback broker is
90
+ in [`OAUTH-BROKER-HANDOFF.md`](./OAUTH-BROKER-HANDOFF.md). It records the exact
91
+ Linear redirect URI that must be registered and why the original loopback
92
+ callback could not support packaged desktop or arbitrary self-hosted servers.
93
+
94
+ - Do not log tokens, codes, verifiers, or the client secret.
95
+ - Do not add Linear under Git or as a third-party plugin row.
96
+ - Actor is `user`. Do not enable Linear client-credentials tokens for this flow.
97
+ - One OAuth grant is still one Linear organization. The server stores many grants and keeps one current. Webhooks and inbound Linear issue actions are out of scope until a later change.
@@ -0,0 +1,91 @@
1
+ # Linear OAuth broker hand-off
2
+
3
+ ## Required Linear application change
4
+
5
+ Register this exact redirect URI in the Linear OAuth application used by the
6
+ baked-in client ID:
7
+
8
+ `https://api.openchamber.dev/v1/oauth/linear/callback`
9
+
10
+ Linear compares the full redirect URI, including scheme, host, path, and port.
11
+ Deploy the API broker and apply its D1 migration before testing this branch.
12
+
13
+ ## Why the original callback failed
14
+
15
+ The first implementation redirected Linear back to the OpenChamber server:
16
+
17
+ `http://127.0.0.1:<listen-port>/linear/oauth/callback`
18
+
19
+ That address is not stable across OpenChamber runtimes:
20
+
21
+ - packaged desktop prefers its stored local port and can select another free
22
+ port when needed;
23
+ - local development and the CLI use different ports;
24
+ - self-hosted servers may sit behind a reverse proxy or have no public inbound
25
+ address at all.
26
+
27
+ Linear requires an exact pre-registered callback. Registering every possible
28
+ desktop or self-hosted address is impossible, and forcing desktop onto one port
29
+ would make startup fail whenever another process owns that port.
30
+
31
+ ## New flow
32
+
33
+ The built-in Linear client now uses the stable callback broker in
34
+ `openchamber-website/apps/api`:
35
+
36
+ 1. The OpenChamber server generates OAuth state, a PKCE verifier, and a separate
37
+ claim secret.
38
+ 2. The broker stores only hashes of state and the claim secret for ten minutes.
39
+ 3. Linear sends its authorization code to the stable public callback.
40
+ 4. The OpenChamber server polls the broker with state and the claim secret.
41
+ 5. The OpenChamber server exchanges the code using the PKCE verifier and stores
42
+ the Linear tokens locally.
43
+ 6. After persistence succeeds, OpenChamber acknowledges the hand-off and the
44
+ broker marks it consumed.
45
+
46
+ The broker never receives the PKCE verifier, access token, or refresh token.
47
+ Private Relay is not involved; the local server only needs outbound HTTPS.
48
+
49
+ ## Compatibility and configuration
50
+
51
+ - `OPENCHAMBER_LINEAR_BROKER_URL` or `settings.json` `linearBrokerUrl` selects a
52
+ self-hosted broker. The default is
53
+ `https://api.openchamber.dev/v1/oauth/linear`.
54
+ - `OPENCHAMBER_LINEAR_REDIRECT_URI` or `settings.json` `linearRedirectUri`
55
+ bypasses the broker and preserves the direct callback flow for a custom
56
+ Linear OAuth application.
57
+
58
+ ## Owning files
59
+
60
+ OpenChamber:
61
+
62
+ - `auth.js`: broker and redirect configuration.
63
+ - `oauth.js`: PKCE, broker registration/poll/acknowledgement, token exchange.
64
+ - `routes.js`: starts authorization and completes broker results during status
65
+ polling.
66
+
67
+ Hosted API, in the `openchamber-website` repository:
68
+
69
+ - `apps/api/src/routes/linear-oauth.ts`
70
+ - `apps/api/migrations/0010_linear_oauth_transactions.sql`
71
+ - `apps/api/LINEAR-OAUTH.md`
72
+
73
+ ## Validation
74
+
75
+ OpenChamber focused tests:
76
+
77
+ ```sh
78
+ bunx vitest run \
79
+ packages/web/server/lib/linear/oauth.test.js \
80
+ packages/web/server/lib/linear/auth.test.js \
81
+ packages/web/server/lib/linear/routes.test.js
82
+ ```
83
+
84
+ Hosted API checks:
85
+
86
+ ```sh
87
+ cd apps/api
88
+ bun test src/routes/linear-oauth.test.ts
89
+ bun run check
90
+ bun run build
91
+ ```