@aiworker/web 1.22.0 → 1.23.0

package/server/lib/git/DOCUMENTATION.md.bak

@@ -1,193 +0,0 @@
-# Git Module Documentation
-
-## Purpose
-This module provides Git repository operations for the web server runtime, including repository management, branch/worktree operations, status/diff queries, commit handling, and merge/rebase workflows.
-
-## Entrypoints and structure
-- `packages/web/server/lib/git/`: Git module directory containing all Git-related functionality.
-  - `index.js`: Public API entry point imported by `packages/web/server/index.js`.
-  - `routes.js`: Express route registration for `/api/git/*` endpoints.
-  - `service.js`: Core Git operations (repository, branch, worktree, commit, merge/rebase, status/diff, log).
-  - `credentials.js`: Git credentials management.
-  - `identity-storage.js`: Git identity (user.name, user.email) storage.
-
-## Public API
-
-The following functions are exported and used by the web server:
-
-### Repository Operations
-- `isGitRepository(directory)`: Check if a directory is a Git repository.
-- `getGlobalIdentity()`: Get global Git user.name, user.email, and core.sshCommand.
-- `getCurrentIdentity(directory)`: Get local Git identity (fallback to global if not set locally).
-- `hasLocalIdentity(directory)`: Check if local Git identity is configured.
-- `setLocalIdentity(directory, profile)`: Set local Git identity (userName, userEmail, authType, sshKey/host).
-- `getRemoteUrl(directory, remoteName)`: Get URL for a specific remote.
-
-### Status and Diff Operations
-- `getStatus(directory)`: Get comprehensive Git status including current branch, tracking, ahead/behind, file changes, diff stats, merge/rebase state.
-- `getDiff(directory, { path, staged, contextLines })`: Get diff output for files or entire working tree. Untracked symbolic links are represented as link entries without following their targets.
-- `getRangeDiff(directory, { base, head, path, contextLines })`: Get diff between two refs. Uses three-dot `base...head` semantics, so work merged into `head` from `base` is excluded and only the branch's own changes are returned. Prefers `origin/<base>` when that remote-tracking ref exists, so a stale local base branch does not resurface already-merged commits. Exposed as `GET /api/git/range-diff` (`path` optional; omit it for the whole range).
-- `getRangeFiles(directory, { base, head })`: Get list of changed files between two refs.
-- `getFileDiff(directory, { path, staged })`: Get original and modified file contents for a single file (handles images as data URLs and symbolic links as their link-target text).
-- `listUntrackedPaths(directory)`: List individual untracked file paths honoring ignore rules. Much cheaper than `getStatus` when that is all a caller needs. Deliberately not `--directory`: collapsed directory entries end in a slash and are rejected by the per-file diff helpers, so a caller would silently lose every file inside a new directory.
-- `getUntrackedDiffs(directory, filePaths, { concurrency, contextLines })`: Diffs for untracked files against an empty tree. Resolves the repository context once instead of per file (`getDiff` re-resolves every call, costing an extra `rev-parse` each time) and bounds how many diff processes run at once. Returns one entry per input path in order; unreadable paths yield `''` rather than failing the batch.
-- `collectDiffs(directory, files)`: Collect diff output for multiple files.
-- `revertFile(directory, filePath, options)`: Revert a file. Default scope `all` discards staged and working-tree changes; scope `working` discards only unstaged/working-tree changes.
-- `stageFile(directory, filePath)`: Add one file path to the index.
-- `unstageFile(directory, filePath)`: Remove one file path from the index while preserving working-tree content.
-- `applyHunk(directory, filePath, options)`: Apply a single-hunk patch via `git apply`. `options.action` is `stage` (`git apply --cached`), `unstage` (`git apply --cached --reverse`), or `discard` (`git apply --reverse` in the working tree). The patch is written to a temp file; a `--check` runs first so a stale hunk fails with a clear "refresh and try again" error instead of a partial mutation. The patch target path must match the requested file.
-
-### Branch Operations
-- `getBranches(directory)`: Get list of local and remote branches (filtered to active remote branches).
-- `createBranch(directory, branchName, options)`: Create and checkout a new branch.
-- `checkoutBranch(directory, branchName)`: Checkout an existing branch. A remote-tracking name (`origin/main`, or the `remotes/`-prefixed form) resolves to the local branch of that name, created with `--track` when it does not exist yet, because the branch selector offers remote branches as places to work rather than commits to inspect — a literal checkout of the remote ref would detach HEAD. A local branch whose own name looks like a remote ref wins over that resolution, and anything unresolvable is checked out as requested. The returned `branch` is the branch that was actually checked out, which callers should report instead of the requested name.
-- `deleteBranch(directory, branch, options)`: Delete a branch (supports force flag).
-- `renameBranch(directory, oldName, newName)`: Rename a branch and preserve upstream tracking.
-- `getRemotes(directory)`: Get list of configured remotes.
-
-### Worktree Operations
-- `getWorktrees(directory)`: List all git worktrees for a repository.
-- `validateWorktreeCreate(directory, input)`: Validate worktree creation parameters (mode, branchName, startRef, upstream config).
-- `createWorktree(directory, input)`: Create a new worktree (supports 'new' and 'existing' modes, upstream setup). After populating the worktree, the repository's `post-checkout` hook runs once with git's standard arguments (null ref as previous HEAD, the checked-out HEAD, and flag `1`) from the worktree directory, mirroring `git worktree add` without `--no-checkout`; a missing or non-executable hook is skipped and a failing hook is logged as a warning, never failing worktree creation or the session bootstrap.
-- `removeWorktree(directory, input)`: Remove a worktree (optionally delete local branch).
-- `isLinkedWorktree(directory)`: Check if directory is a linked worktree (not primary).
-
-### Worktree creation from a GitHub pull request
-The UI provisions `pr-<owner>` via `ensureRemoteName`/`ensureRemoteUrl`
-(HTTPS clone URL preferred over SSH) and checks out
-`remotes/pr-<owner>/<head>`. A missing head URL or unreachable fork fails with
-a clear error before a worktree is kept. If upstream fetch fails during
-bootstrap, tracking is left unset rather than writing `branch.*.remote` /
-`branch.*.merge` for a ref that was never fetched.
-
-### Commit and Remote Operations
-- `commit(directory, message, options)`: Create a commit from the current index. `options.stageFiles` may be provided with `options.files` by older callers to stage only selected unstaged rows before committing, but the shared Git panel now stages/unstages explicitly before commit.
-- `pull(directory, options)`: Pull changes from remote.
-- `push(directory, options)`: Push changes to remote (auto-sets upstream if needed).
-- `fetch(directory, options)`: Fetch changes from remote.
-- `removeRemote(directory, options)`: Remove a configured remote (except `origin`).
-- `deleteRemoteBranch(directory, options)`: Delete a remote branch.
-
-### Log Operations
-- `getLog(directory, options)`: Get commit history with stats (supports maxCount, from, to, file filters).
-- `getCommitFiles(directory, commitHash)`: Get file changes for a specific commit.
-- `getCommitFileDiff(directory, hash, filePath, isBinary)`: Get before/after content for a specific file in a commit. Returns `{ original, modified, isBinary }`. Runs `git show <hash>^:<path>` and `git show <hash>:<path>` in parallel; returns empty strings on failure (added/deleted/root-commit edge cases).
-
-### Merge and Rebase Operations
-- `rebase(directory, options)`: Start a rebase onto a target branch.
-- `abortRebase(directory)`: Abort an in-progress rebase.
-- `continueRebase(directory)`: Continue a rebase after conflict resolution.
-- `merge(directory, options)`: Merge a branch into current branch.
-- `abortMerge(directory)`: Abort an in-progress merge.
-- `continueMerge(directory)`: Continue a merge after conflict resolution.
-- `getConflictDetails(directory)`: Get detailed conflict information including operation type, unmerged files, and diff.
-
-### Stash Operations
-- `listStashes(directory)`: List stash entries with ref, message, relative time, and hash.
-- `countStashFiles(directory, refs)`: Batch-count changed files for stash refs with bounded concurrency.
-- `stashPush(directory, options)`: Stash changes, always including untracked files, with optional message.
-- `stashApply(directory, options)`: Apply a stash by ref without removing it.
-- `stashPop(directory, options)`: Apply a stash by ref and drop it only after a successful apply.
-- `stashDrop(directory, options)`: Drop a stash by ref.
-
-## Internal Helpers
-
-The following functions are internal helpers used by exported functions:
-- `buildSshCommand(sshKeyPath)`: Build SSH command string for git config.
-- `buildGitEnv()`: Build Git environment with SSH_AUTH_SOCK resolution.
-- `createGit(directory)`: Create simple-git instance with environment.
-- `normalizeDirectoryPath(value)`: Normalize directory paths (supports ~ expansion).
-- `cleanBranchName(branch)`: Remove refs/heads/ or refs/ prefixes.
-- `parseWorktreePorcelain(raw)`: Parse `git worktree list --porcelain` output.
-- `resolveWorktreeProjectContext(directory)`: Resolve project context (projectID, primaryWorktree, worktreeRoot).
-- `resolveCandidateDirectory(...)`: Generate unique worktree directory candidates.
-- `resolveBranchForExistingMode(...)`: Resolve branch for existing-mode worktree creation.
-- `applyUpstreamConfiguration(...)`: Set upstream tracking for new branches.
-- `runPostCheckoutHook(directory)`: Invoke the worktree's `post-checkout` hook after population, because `git worktree add --no-checkout` and the bootstrap's `git reset --hard` never run git hooks. Runs with git's standard arguments and the worktree as cwd; skips missing/non-executable hooks and never throws on hook failure.
-- And various other internal helpers for Git command execution and parsing.
-
-## Response Contracts
-
-### Status Response
-- `current`: Current branch name.
-- `tracking`: Upstream branch (e.g., 'origin/main').
-- `ahead`: Number of commits ahead of upstream.
-- `behind`: Number of commits behind upstream.
-- `upstreamComparison`: Optional comparison against `upstream/<current-branch>`, with `{ remote, branch, ahead, behind }`.
-- `files`: Array of file objects with `path`, `index`, `working_dir` status codes.
-- `isClean`: Boolean indicating if working tree is clean.
-- `diffStats`: Object mapping file paths to `{ insertions, deletions }`.
-- `mergeInProgress`: Object with `{ head, message }` if merge in progress.
-- `rebaseInProgress`: Object with `{ headName, onto }` if rebase in progress.
-
-### Branches Response
-- `all`: Local branches plus every branch each reachable remote reports via `ls-remote --heads`, formatted as `remotes/<remote>/<branch>`. This is a union: local remote-tracking refs deleted on the remote are pruned, and branches that exist on the remote without a local tracking ref (never fetched) are still included, so a freshly pushed branch appears without requiring a fetch. A remote that fails to answer keeps its locally known branches in the list: "we could not ask" must not be reported as "these branches are gone", because callers use this list to decide whether a base branch exists at all.
-- `current`: Current branch name.
-- `branches`: Per-branch detail keyed by branch name, as reported by `git branch`. Remote-only entries in `all` — branches `ls-remote` reported that were never fetched — have **no** entry here, because `git branch` never saw them. Consumers must treat a missing detail entry as normal and read the name from `all`.
-- Never-fetched remote-only branches also have no local ref, so any operation that resolves one locally has to account for that: `checkoutBranch` fetches the single branch (`git fetch <remote> <branch>`) before creating the tracking branch, and the range helpers (`getRangeDiff`, `getRangeFiles`) reject an unresolvable ref with `Ref "<ref>" is not available locally. Fetch it before comparing.` instead of surfacing git's "ambiguous argument".
-- `defaultBranches`: Each remote's default branch, keyed by remote name. Read from the local `remotes/<name>/HEAD` symbolic ref; for a remote that has none — clone writes it, a hand-added remote may not — the remote itself is asked once with `ls-remote --symref`. A remote that answers neither is absent rather than guessed, and consumers fall back to conventional branch names. Omitted entirely by runtimes that do not provide this Git metadata.
-
-### Runtime availability of range diffs
-- `GET /api/git/range-diff` is served by the AiWorker web server, so it is available to web, desktop, and mobile clients. The shared `GitAPI.getGitRangeDiff` is therefore optional: web supplies the HTTP implementation, and VS Code does not implement it because the extension host serves Git through its own bridge rather than these routes. Features built on range diffs (currently the AI diff walkthrough) are not offered in VS Code.
-
-### Staged and unstaged change handling
-- `status.files` exposes both `index` and `working_dir` codes. Shared UI uses these as separate scopes: staged rows are derived from non-empty `index` statuses, while unstaged rows are derived from `working_dir` statuses and untracked files.
-- A file with both staged and unstaged changes can appear in both UI sections. Staged rows request diffs with `staged: true`; unstaged rows request normal working-tree diffs.
-- The shared Git panel exposes explicit staging actions. Unstaged rows use `stageFile`, staged rows use `unstageFile`, and commits operate on the current staged index.
-- `stageFiles` remains supported for callers that need to stage a selected unstaged subset as part of commit. In that mode the server temporarily unstages unrelated index entries, stages `stageFiles`, commits from the index, then restores temporarily unstaged entries.
-### Worktree Create/Remove Response
-- `head`: HEAD commit SHA.
-- `name`: Worktree name.
-- `branch`: Local branch name.
-- `path`: Absolute path to worktree directory.
-- `directoryCreated`: Present when create returned after the target directory exists while background Git/bootstrap work continues.
-- `bootstrapStatus`: Background setup state. The legacy `status` remains `pending`, `ready`, or `failed`, while `phase` reports `directory-created`, `git-ready`, or `setup-ready`. Fast create starts at `pending`/`directory-created`; population and upstream Git completion advances to `pending`/`git-ready` before setup/start scripts; completed setup is `ready`/`setup-ready`. A missing in-memory state falls back to `ready`/`setup-ready`; clients continue to accept legacy status responses that omit `phase`.
-- Fast-create background failures remove OpenCode sandbox metadata for directories that never became Git worktrees, and remove the pre-created directory only if it is still empty. User-created files are never recursively deleted by this cleanup.
-- Worktree removal waits for any active create/bootstrap task for that directory before deleting it, preventing a background Git or setup task from restoring removed state or racing filesystem cleanup.
-- Worktree bootstrap retries transient `index.lock` conflicts. If the lock remains byte-for-byte and metadata-identical across the retry window, it is treated as stale, removed, and population continues automatically; changing locks are left untouched and reported as failures.
-- Worktree population enables Git `core.longpaths` (local repo config plus `-c core.longpaths=true` on `git reset --hard`) so deeply nested checkouts under the managed data-dir worktree root do not fail on Windows MAX_PATH with "Filename too long". Path-component limits that the filesystem itself rejects still fail bootstrap, with a clearer path-length guidance message.
-
-### Log Response
-- `all`: Array of commit objects with hash, date, message, author info, stats.
-- `latest`: Latest commit object or null.
-- `total`: Total number of commits.
-
-## Notes for Contributors
-
-### Adding a New Git Operation
-1. Add the function to `packages/web/server/lib/git/service.js`.
-2. Export the function if it's part of the public API.
-3. Use `createGit(directory)` to get a simple-git instance with the correct environment. `directory` is required (`baseDir`); never omit it so commands cannot inherit `process.cwd()`.
-4. Use `runGitCommand(cwd, args)` for direct git command execution with better error handling.
-5. Use `runGitCommandOrThrow(cwd, args, fallbackMessage)` for commands that must succeed.
-6. Return consistent error messages; use `parseGitErrorText(error)` to extract meaningful git errors.
-7. Update this file with the new function in the appropriate API section.
-
-### SSH Key Handling
-- SSH keys are escaped and validated via `escapeSshKeyPath` to prevent command injection.
-- On Windows, paths are converted to MSYS format (`C:/path` → `/c/path`).
-- SSH_AUTH_SOCK is automatically resolved via `resolveSshAuthSock` (checks GPG agent, gpgconf).
-
-### Working directory (simple-git)
-- Repository operations always pass an explicit `baseDir` (the opened project/directory path) into simple-git. Omitting `baseDir` would default to `process.cwd()`, which breaks when the server was launched from a neutral directory (e.g. `$HOME`) while the opened project lives elsewhere.
-- Global identity reads use the user home directory as `baseDir` (they do not need a repository).
-- A `GitError` / non-repository result from status or check must not abort project/session enumeration: routes return a soft non-repo payload and log a warning.
-
-### Worktree Naming
-- Worktree names are slugified via `slugWorktreeName`.
-- Random names use adjectives/nouns from `OPENCODE_ADJECTIVES` and `OPENCODE_NOUNS` lists.
-- Branches created for new worktrees use `aiworker/<worktree-name>` pattern.
-
-### Cross-Platform Considerations
-- Use `normalizeDirectoryPath` for all directory inputs to handle `~` and path separators.
-- Use `canonicalPath` for path comparisons to handle case-insensitive filesystems (Windows).
-- Windows Git commands use MSYS/MinGW paths; avoid direct Windows paths in git commands.
-
-### Error Handling
-- All exported functions should throw errors with descriptive messages.
-- Use `console.error` for logging Git operation failures.
-- Return structured objects for operations that need partial success reporting (e.g., merge/rebase conflicts).
-
-### Testing
-- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
-- Consider edge cases: non-Git directories, missing remotes, conflict states, concurrent worktree operations.

package/server/lib/github/DOCUMENTATION.md.bak

@@ -1,183 +0,0 @@
-# GitHub Module Documentation
-
-## Purpose
-
-- This module owns GitHub auth, Octokit access, repo resolution, and Pull Request status resolution for AiWorker.
-- From user perspective, this is the layer that lets the app know which PR belongs to a local branch and keeps that UI feeling current.
-
-## Entrypoints and structure
-
-- `packages/web/server/lib/github/index.js`: public server entrypoint. `routes.js` loads it lazily with `await import('./index.js')` and destructures the handler it needs, so a re-export removed from here breaks a route at request time rather than at build time. Static "unused export" reports do not see these consumers.
-- `packages/web/server/lib/github/routes.js`: Express route registration for `/api/github/*` endpoints.
-- `packages/web/server/lib/github/auth.js`: auth storage, multi-account support, client id, scope config.
-- `packages/web/server/lib/github/device-flow.js`: OAuth device flow.
-- `packages/web/server/lib/github/octokit.js`: Octokit factory for the current auth.
-- `packages/web/server/lib/github/repo/index.js`: remote URL parsing and directory-to-repo resolution.
-- `packages/web/server/lib/github/pr-status.js`: PR lookup across remotes, forks, and upstreams.
-- `packages/web/server/index.js`: API route layer that calls this module.
-- `packages/web/src/api/github.ts`: web client wrapper for GitHub endpoints.
-
-## Public exports
-
-### Auth
-
-- `getGitHubAuth()`: current auth entry.
-- `getGitHubAuthAccounts()`: all configured accounts.
-- `setGitHubAuth({ accessToken, scope, tokenType, user, accountId })`: save or update account.
-- `activateGitHubAuth(accountId)`: switch active account.
-- `clearGitHubAuth()`: clear current account.
-- `getGitHubClientId()`: resolve client id.
-- `getGitHubScopes()`: resolve scopes.
-- `GITHUB_AUTH_FILE`: auth file path.
-
-### Device flow
-
-- `startDeviceFlow({ clientId, scope })`: request device code.
-- `exchangeDeviceCode({ clientId, deviceCode })`: poll for access token.
-
-### Octokit
-
-- `getOctokitOrNull()`: current Octokit or `null`.
-
-### Repo
-
-- `parseGitHubRemoteUrl(raw)`: parse SSH or HTTPS remote URL into `{ owner, repo, url }`.
-- `resolveGitHubRepoFromDirectory(directory, remoteName)`: resolve GitHub repo from a local git remote.
-
-## Auth storage and config
-
-- Auth storage: `~/.config/openchamber/github-auth.json`
-- Writes are atomic and file mode is `0o600`.
-- Client ID resolution order: `AIWORKER_GITHUB_CLIENT_ID` -> `settings.json` -> default.
-- Scope resolution order: `AIWORKER_GITHUB_SCOPES` -> `settings.json` -> default.
-- Account id resolution order: explicit `accountId` -> user login -> user id -> token prefix.
-
-## PR integration overview
-
-- The UI asks `github.prStatus(directory, branch, remote?)` from `packages/web/src/api/github.ts`.
-- That hits `GET /api/github/pr/status` in `packages/web/server/index.js`.
-- The route calls `resolveGitHubPrStatus(...)` in `packages/web/server/lib/github/pr-status.js`.
-- The resolver finds the most likely repo and PR for a local branch.
-- The route then enriches that result with checks, mergeability, and permission-related fields.
-- The client caches and shares the result between sidebar and Git view.
-
-## Consumers of PR data
-
-- `packages/ui/src/components/session/SessionSidebar.tsx` reads all PR entries and maps them to `directory::branch`.
-- `packages/ui/src/components/session/sidebar/SessionGroupSection.tsx` renders the compact badge, PR number, title, checks summary, and GitHub link.
-- `packages/ui/src/components/views/git/PullRequestSection.tsx` uses the same shared entry for the full PR workflow.
-- `packages/ui/src/components/ui/MemoryDebugPanel.tsx` reads request counters for debugging.
-
-## How PR resolution works
-
-- It reads local git status and remotes first.
-- It ranks remotes in this order: explicit remote, tracking remote, `origin`, `upstream`, then the rest.
-- It resolves those remotes into GitHub repos.
-- It expands each repo through `parent` and `source` so PRs in upstream repos can still be found.
-- It skips PR lookup when the current branch matches that repo's default branch.
-- It first searches for **open** PRs by likely source owner plus exact head branch.
-- If that fails, it falls back to broader GitHub search for open PRs on the branch name.
-- An **open PR from any candidate repo always wins** over a closed/merged one, so a merged fork PR can never hide an open upstream PR for the same head.
-- Only when no target has an open PR does it return the branch's newest closed/merged PR, as history.
-- History is looked up **only for the ranked-first remote and the branch's own name** — the repo it actually pushes to. Live status is worth searching the whole fork network for; history is not, and asking every target for it multiplies serial GitHub calls until the route hits its `12s` resolve timeout and returns no status at all.
-- The history answer is remembered per repo+branch so discovery polls do not re-query it: a found closed/merged record for `6h`, and "no history yet" for `10m`. A found record only changes if a second PR appears on the same head, and while that one is open the open-PR path wins without ever reading this cache.
-- Creating, merging, or closing a PR invalidates both the shared repo pull list and that remembered history.
-- The route skips the checks summary and the merge-permission lookup for a closed/merged PR: neither is actionable, and both cost extra GitHub calls.
-- `403` and `404` during repo lookups are treated as expected gaps, not hard errors.
-
-## Shared client state model
-
-- Client key is effectively `directory::branch`.
-- One entry stores last known status, loading state, error, timestamps, watcher count, identity, and resolved remote.
-- Requests are deduplicated by branch signature, not by component instance.
-- This keeps sidebar and Git view aligned and avoids duplicated fetches.
-
-## Persistence
-
-- PR state is persisted in local storage under `aiworker.github-pr-status`.
-- Persisted fields include status, timestamps, identity, and resolved remote.
-- Runtime-only details are not persisted.
-- Persisted entries expire after 12 hours.
-- On reload, users get last known state first, then background refresh resumes.
-
-## Polling and refresh model
-
-- There are two layers: entry-level polling in `useGitHubPrStatusStore` and repo scanning in `useGitHubPrBackgroundTracking`.
-- Entry-level polling decides when a known branch should revalidate PR state.
-- Background tracking decides which directories and branches should even be watched.
-
-## Entry-level polling rules
-
-- Start watching -> immediate refresh.
-- If no PR is found yet -> retry after `2s` and `5s`.
-- Still no PR -> discovery refresh every `5m`.
-- Open PR with pending checks -> refresh about every `1m`.
-- Open PR with non-pending checks -> refresh about every `5m`.
-- Open PR without a stable checks signal -> refresh about every `2m`.
-- Closed or merged PR -> discovery refresh every `5m` (do not permanently stop polling).
-- Hidden tab -> skip polling.
-- Non-forced refreshes use a `90s` TTL.
-- Failed non-forced attempts also observe the `90s` TTL so transient server or rate-limit failures cannot retry on every sidebar update. Forced user/action refreshes bypass this guard.
-
-## Persistence notes for terminal PRs
-
-- Closed/merged branch associations are persisted like open ones, so a reload still shows that the branch's PR was merged.
-- Hydrate resets `lastDiscoveryPollAt` for them, so restored history revalidates on the first watcher tick instead of waiting out a discovery interval.
-
-## Background tracking rules
-
-- Track up to `50` likely directories.
-- Sources are current directory, projects, worktrees, active sessions, and archived sessions.
-- Active directory branch TTL is `15s`.
-- Background directory branch TTL is `2m`.
-- Background scan wakes every `15s`, but only fetches directories whose TTL expired.
-- Each scan reads `branch`, `tracking`, `ahead`, and `behind` from git status.
-- If any of those branch signals change, that branch's PR status refreshes immediately.
-- After that, one more delayed refresh runs after `5s` to catch GitHub eventual consistency.
-
-## UI refresh triggers
-
-- App or tab becomes visible.
-- Window regains focus.
-- Current branch changes.
-- Tracking branch changes.
-- Ahead or behind changes.
-- User selects a different remote in Git view.
-- GitHub auth state changes.
-
-## Action-based refreshes in Git view
-
-- After `Create PR` -> refresh now, then after `2s` and `5s`.
-- After `Merge PR` -> refresh now, then after `2s` and `5s`.
-- After `Mark ready for review` -> refresh now, then after `2s` and `5s`.
-- After `Update PR` -> refresh now, then after `2s` and `5s`.
-
-## Sidebar behavior
-
-- Sidebar shows only compact PR state.
-- Aggregation is by `directory::branch`, so multiple sessions on one branch share one signal.
-- If multiple entries exist, sidebar keeps the strongest visible PR state.
-- Visual state is based on PR health, not merge permissions.
-
-## Git view behavior
-
-- Git view watches one branch directly.
-- It supports create, edit, mark ready, and merge.
-- It can probe alternate remotes so fork-heavy setups still find the right PR.
-- It uses the same shared store as the sidebar.
-
-## Failure handling
-
-- If GitHub is disconnected, API returns `connected: false`.
-- If a repo is private or inaccessible, resolver calls may quietly return no PR.
-- Sidebar stays quiet on missing or inaccessible PR state.
-- Git view is where explicit PR-level problems should be shown.
-
-## Notes for contributors
-
-- Keep the UI calm. Do not add noisy diagnostics to the sidebar.
-- Prefer shared state over per-component fetches.
-- Prefer event-shaped refreshes over blind frequent polling.
-- Prefer correctness for fork and multi-remote setups over assuming `origin` is enough.
-- Device flow handles GitHub `authorization_pending` at caller level.
-- Repo parser supports `git@github.com:`, `ssh://git@github.com/`, and `https://github.com/`.

package/server/lib/linear/DOCUMENTATION.md.bak

@@ -1,97 +0,0 @@
-# Linear Module Documentation
-
-## Purpose
-
-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 AiWorker 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 AiWorker session link. Those comments are opt-in and only appear when this server has a publicly reachable address.
-
-VS Code omits Linear (`RuntimeAPIs.linear` is optional). Hide Linear UI when the API is missing.
-
-## Entrypoints and structure
-
-- `packages/web/server/lib/linear/index.js`: public server entrypoint. `routes.js` loads it lazily with `await import('./index.js')`.
-- `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`.
-- `packages/web/server/lib/linear/auth.js`: auth file, client id, scopes, redirect URI.
-- `packages/web/server/lib/linear/oauth.js`: authorization-code + PKCE S256, public callback broker handoff, refresh, revoke.
-- `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.
-- `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.
-- `packages/web/server/lib/linear/teams.js`: list Linear teams for mapping UI.
-- `packages/web/server/lib/linear/mapping.js`: persist default and per-team AiWorker project paths. Separate from the auth file so disconnect does not wipe maps.
-- `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.
-- `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.
-- `packages/web/src/api/linear.ts`: web client wrapper. Electron and hosted/Capacitor mobile reuse it. VS Code omits `linear`.
-
-## Public routes
-
-- `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.
-- `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`.
-- `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.
-- `POST /api/linear/auth/activate`: body `{ organizationId }`. Makes that stored workspace current. 400 if the id is missing, 404 if it is not stored.
-- `DELETE /api/linear/auth`: revokes the current workspace refresh token when present, then drops that workspace only. Other stored workspaces stay. Mapping is kept.
-- `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.
-- `GET /api/linear/issues/get?id=`: one issue by UUID or identifier, including description, comments, team, `state.id`, priority, and labels.
-- `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.
-- `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.
-- `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.
-- `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.
-- `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.
-- `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: `[AiWorker 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.
-
-`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.
-
-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.
-
-## Auth storage and config
-
-- Auth storage: `~/.config/openchamber/linear-auth.json` (or `$AIWORKER_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.
-- 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`.
-- 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 AiWorker session id.
-- Writes are atomic and file mode is `0o600`.
-- Client ID: `AIWORKER_LINEAR_CLIENT_ID` -> `settings.json` `linearClientId` -> baked-in public default.
-- Client secret: `AIWORKER_LINEAR_CLIENT_SECRET` -> `settings.json` `linearClientSecret`. Optional with PKCE. Do not commit a secret.
-- Scopes: `AIWORKER_LINEAR_SCOPES` -> `settings.json` `linearScopes` -> `read,write,comments:create`.
-- Session comments: `settings.json` `linearSessionComments`, boolean, absent means off. Written only through `PUT /api/linear/preferences`.
-- Broker URL: `AIWORKER_LINEAR_BROKER_URL` -> `settings.json` `linearBrokerUrl` -> `https://api.aiworker.dev/v1/oauth/linear`.
-- Redirect URI: `AIWORKER_LINEAR_REDIRECT_URI` -> `settings.json` `linearRedirectUri` -> `<broker-url>/callback`. Setting an explicit redirect URI bypasses the broker for custom/self-hosted OAuth applications.
-
-Linear requires an exact callback match. The built-in application registers `https://api.aiworker.dev/v1/oauth/linear/callback`; the broker holds only the short-lived authorization code. The local AiWorker 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.
-
-## OAuth contract
-
-- Authorization code + PKCE S256. Linear has no device flow.
-- 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 AiWorker server.
-- 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.
-- `invalid_grant` / 401 on refresh clears that workspace only so a dead token cannot loop. If it was the last workspace, status becomes disconnected.
-- 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.
-
-## Project mapping
-
-AiWorker has projects (directories), not accounts or organizations. Mapping is how create-session (picker and the right-hand panel) picks a directory:
-
-1. If the issue's Linear team has a project path, use that.
-2. Otherwise use the default project path.
-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.
-
-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.
-
-## Shared UI
-
-- `RuntimeAPIs.linear` is optional. Hide Linear settings, the chat picker, and the panel when it is missing (VS Code).
-- Store: `packages/ui/src/stores/useLinearAuthStore.ts`. App start refreshes it from `App.tsx` and `MobileApp.tsx`, not `VSCodeApp`.
-- 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.
-- 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.
-- 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.
-- 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.
-- 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 `AiWorker 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.
-- Magic prompts: `linear.issue.review.visible` / `.instructions`. Do not reuse the GitHub issue-review templates for Linear.
-
-## Notes for contributors
-
-The implementation and deployment hand-off for the stable callback broker is
-in [`OAUTH-BROKER-HANDOFF.md`](./OAUTH-BROKER-HANDOFF.md). It records the exact
-Linear redirect URI that must be registered and why the original loopback
-callback could not support packaged desktop or arbitrary self-hosted servers.
-
-- Do not log tokens, codes, verifiers, or the client secret.
-- Do not add Linear under Git or as a third-party plugin row.
-- Actor is `user`. Do not enable Linear client-credentials tokens for this flow.
-- 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.

package/server/lib/linear/OAUTH-BROKER-HANDOFF.md.bak

@@ -1,91 +0,0 @@
-# Linear OAuth broker hand-off
-
-## Required Linear application change
-
-Register this exact redirect URI in the Linear OAuth application used by the
-baked-in client ID:
-
-`https://api.aiworker.dev/v1/oauth/linear/callback`
-
-Linear compares the full redirect URI, including scheme, host, path, and port.
-Deploy the API broker and apply its D1 migration before testing this branch.
-
-## Why the original callback failed
-
-The first implementation redirected Linear back to the AiWorker server:
-
-`http://127.0.0.1:<listen-port>/linear/oauth/callback`
-
-That address is not stable across AiWorker runtimes:
-
-- packaged desktop prefers its stored local port and can select another free
-  port when needed;
-- local development and the CLI use different ports;
-- self-hosted servers may sit behind a reverse proxy or have no public inbound
-  address at all.
-
-Linear requires an exact pre-registered callback. Registering every possible
-desktop or self-hosted address is impossible, and forcing desktop onto one port
-would make startup fail whenever another process owns that port.
-
-## New flow
-
-The built-in Linear client now uses the stable callback broker in
-`openchamber-website/apps/api`:
-
-1. The AiWorker server generates OAuth state, a PKCE verifier, and a separate
-   claim secret.
-2. The broker stores only hashes of state and the claim secret for ten minutes.
-3. Linear sends its authorization code to the stable public callback.
-4. The AiWorker server polls the broker with state and the claim secret.
-5. The AiWorker server exchanges the code using the PKCE verifier and stores
-   the Linear tokens locally.
-6. After persistence succeeds, AiWorker acknowledges the hand-off and the
-   broker marks it consumed.
-
-The broker never receives the PKCE verifier, access token, or refresh token.
-Private Relay is not involved; the local server only needs outbound HTTPS.
-
-## Compatibility and configuration
-
-- `AIWORKER_LINEAR_BROKER_URL` or `settings.json` `linearBrokerUrl` selects a
-  self-hosted broker. The default is
-  `https://api.aiworker.dev/v1/oauth/linear`.
-- `AIWORKER_LINEAR_REDIRECT_URI` or `settings.json` `linearRedirectUri`
-  bypasses the broker and preserves the direct callback flow for a custom
-  Linear OAuth application.
-
-## Owning files
-
-AiWorker:
-
-- `auth.js`: broker and redirect configuration.
-- `oauth.js`: PKCE, broker registration/poll/acknowledgement, token exchange.
-- `routes.js`: starts authorization and completes broker results during status
-  polling.
-
-Hosted API, in the `openchamber-website` repository:
-
-- `apps/api/src/routes/linear-oauth.ts`
-- `apps/api/migrations/0010_linear_oauth_transactions.sql`
-- `apps/api/LINEAR-OAUTH.md`
-
-## Validation
-
-AiWorker focused tests:
-
-```sh
-bunx vitest run \
-  packages/web/server/lib/linear/oauth.test.js \
-  packages/web/server/lib/linear/auth.test.js \
-  packages/web/server/lib/linear/routes.test.js
-```
-
-Hosted API checks:
-
-```sh
-cd apps/api
-bun test src/routes/linear-oauth.test.ts
-bun run check
-bun run build
-```

package/server/lib/markdown-image-grants/DOCUMENTATION.md.bak

@@ -1,40 +0,0 @@
-# Markdown Image Grants
-
-## Purpose
-
-This module lets the Markdown image gallery display images that an assistant
-explicitly referenced from OpenCode's temporary directory when the UI is on a
-different machine.
-
-## Contract
-
-- Chat Markdown rendering is independent: assistant image syntax renders as an
-  icon and filename, while the gallery only reads finalized Markdown to collect
-  image candidates.
-- `POST /api/openchamber/sessions/:sessionId/markdown-image-grants` prepares up to 12
-  local images in one message-level request. The server fetches the assistant
-  message once and verifies every exact image source before reading files.
-- Authorization recognizes the same common inline and reference-style image
-  destinations collected by the UI, including balanced parentheses, while
-  excluding fenced and inline code.
-- Relative and workspace-contained absolute paths resolve against the active
-  directory. Other absolute paths are accepted only inside
-  `os.tmpdir()/opencode` after `realpath` resolution.
-- PNG, JPEG, GIF, and WebP files are signature-checked and limited to 10 MiB.
-- Prepare requests inspect only file metadata and signatures. Workspace images
-  reuse the existing authenticated `/api/fs/raw` asset route directly. Images
-  under `os.tmpdir()/opencode` receive the existing path-bound `raw`
-  `outsideFileGrant`; this module does not add another asset lifetime, copy, or
-  storage layer. Missing files return per-source results so the gallery can
-  remove only those items.
-
-The routes are AiWorker-owned and must be registered before the generic
-OpenCode proxy. Web, Electron, hosted mobile, and Capacitor use the shared
-server implementation. VS Code does not call this route for workspace images;
-those use its local filesystem bridge. If called, the grant route returns an
-explicit unsupported response because OpenCode temporary images are not
-supported there.
-
-Requests to OpenCode carry the directory in a percent-encoded
-`x-opencode-directory` header, matching the SDK wire format; OpenCode rejects
-raw non-ASCII header values.