@aiworker/web 1.22.0 → 1.22.2

package/server/lib/event-stream/DOCUMENTATION.md.bak

@@ -1,62 +0,0 @@
-# Event Stream Module Documentation
-
-## Purpose
-This module contains the AiWorker message-stream WebSocket protocol and runtime bridge. It keeps the browser-facing WebSocket transport separate from the upstream OpenCode SSE transport.
-
-## Entrypoints and structure
-- `packages/web/server/lib/event-stream/index.js`: public entrypoint re-exporting protocol and runtime helpers.
-- `packages/web/server/lib/event-stream/global-hub.js`: shared global upstream SSE hub for server-side subscribers and browser WS fan-out.
-- `packages/web/server/lib/event-stream/global-ws-bridge.js`: browser-facing global WS bridge that subscribes clients to the shared global hub.
-- `packages/web/server/lib/event-stream/directory-ws-bridge.js`: browser-facing per-directory WS bridge that owns one scoped upstream reader per connection.
-- `packages/web/server/lib/event-stream/protocol.js`: path constants, SSE envelope parsing, and WebSocket frame serialization helpers.
-- `packages/web/server/lib/event-stream/upstream-reader.js`: reusable upstream SSE reader with event-id tracking, stall recovery, and reconnect handling.
-- `packages/web/server/lib/event-stream/runtime.js`: thin WebSocket server runtime for upgrade handling and path dispatch to the global/directory bridges.
-- `packages/web/server/lib/event-stream/protocol.test.js`: unit tests for protocol helpers.
-- `packages/web/server/lib/event-stream/upstream-reader.test.js`: unit tests for upstream SSE reader behavior.
-- `packages/web/server/lib/event-stream/runtime.test.js`: unit tests for runtime-side broadcaster behavior.
-
-## Public exports
-
-### Protocol helpers
-- `MESSAGE_STREAM_GLOBAL_WS_PATH`: `/api/global/event/ws`
-- `MESSAGE_STREAM_DIRECTORY_WS_PATH`: `/api/event/ws`
-- `MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS`: heartbeat interval for browser-facing WS connections.
-- `parseSseEventEnvelope(block)`: parses an SSE block into `{ eventId, directory, payload }`.
-- `sendMessageStreamWsFrame(socket, payload)`: serializes and sends a JSON WS frame.
-- `sendMessageStreamWsEvent(socket, payload, options)`: sends an event frame with optional `eventId` and `directory`.
-
-### Runtime helpers
-- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.
-- `createGlobalUiEventBroadcaster({ sseClients, wsClients, writeSseEvent })`: returns a broadcaster that fans out the same synthetic UI event to SSE and WS clients.
-- `createMessageStreamWsRuntime(...)`: mounts the message-stream WS server, upgrade handler, and SSE-to-WS bridge onto the web HTTP server.
-
-### Upstream reader helpers
-- `DEFAULT_UPSTREAM_STALL_TIMEOUT_MS`: default idle timeout before an attached upstream SSE fetch is aborted for reconnect.
-- `DEFAULT_UPSTREAM_RECONNECT_DELAY_MS`: default delay between upstream reconnect attempts.
-- `createUpstreamSseReader(...)`: creates a start/stop reader for OpenCode SSE streams. The reader parses SSE blocks, tracks the latest `Last-Event-ID`, reconnects after closed or stalled upstream streams, and reports events through callbacks.
-
-## Runtime behavior
-- Browser clients connect to the WS endpoints above.
-- AiWorker still fetches OpenCode upstream event streams over SSE.
-- The web server creates one shared global message-stream hub. OpenCode watcher side effects and global WS clients subscribe to that hub, so there is one upstream `/global/event` SSE reader for both server-side processing and browser fan-out.
-- The global hub keeps a bounded replay buffer keyed by SSE `eventId` so reconnecting browser clients can receive buffered events after their requested `Last-Event-ID`.
-- Directory WS clients still attach one upstream `/event?directory=...` SSE reader per connection because directory streams are scoped.
-- If an upstream SSE stream stalls after the browser WS is already ready, the reader aborts that upstream fetch and reconnects upstream with `Last-Event-ID`, keeping the browser WS alive when recovery is fast.
-- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and can run scoped state repair without requiring the browser WS to close.
-- Health checks are reserved for initial upstream connect failures and explicit upstream-unavailable responses, not for ordinary stall recovery on an already-established stream.
-- Global synthetic events such as `aiworker:session-status`, `aiworker:session-activity`, `aiworker:notification`, and `aiworker:heartbeat` are preserved on the WS path, but heartbeat frames are emitted only while an upstream SSE stream is actively attached.
-- Global UI broadcasts are fan-out capable across both SSE and WS clients.
-- The reusable upstream reader centralizes SSE fetch/parsing/reconnect behavior for the WS runtime and OpenCode watcher. Additional event consumers should move to it only with parity tests for their lifecycle and error semantics.
-- Browser transport concerns live in the WS bridge modules; server-side global stream ownership lives in `global-hub.js`.
-
-## Notes for contributors
-- Keep protocol helpers pure and small so they can be unit tested without spinning up a server.
-- Keep `runtime.js` focused on WebSocket upgrade and endpoint dispatch. Put global browser-client lifecycle in `global-ws-bridge.js`, directory stream lifecycle in `directory-ws-bridge.js`, and upstream stream sharing in `global-hub.js`.
-- Do not change upstream OpenCode transport assumptions here; OpenCode remains SSE-based.
-- Keep global replay bounded; do not turn it into an unbounded event log.
-
-## Testing
-- Run `bun test packages/web/server/lib/event-stream/protocol.test.js`
-- Run `bun test packages/web/server/lib/event-stream/upstream-reader.test.js`
-- Run `bun test packages/web/server/lib/event-stream/runtime.test.js`
-- Run repo validation before finalizing: `bun run type-check`, `bun run lint`, `bun run build`

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

@@ -1,47 +0,0 @@
-# FS Module Documentation
-
-## Purpose
-Own filesystem API behavior for the web server runtime, including workspace-bound file operations, directory listing, reveal, and background command execution jobs.
-
-## Entrypoints and structure
-- `packages/web/server/lib/fs/routes.js`: route registration and runtime-owned state for `/api/fs/*` endpoints.
-- `packages/web/server/lib/fs/search.js`: fuzzy filesystem search runtime used by non-FS routes (for example project icon discovery).
-
-## Public exports
-- `registerFsRoutes(app, dependencies)` from `routes.js`
-  - Registers all filesystem routes:
-    - `GET /api/fs/home`
-    - `POST /api/fs/mkdir`
-    - `GET /api/fs/read`
-    - `GET /api/fs/raw`
-    - `GET /api/fs/serve/:path(*)`
-    - `POST /api/fs/write`
-    - `POST /api/fs/upload`
-    - `POST /api/fs/delete`
-    - `POST /api/fs/rename`
-    - `POST /api/fs/reveal`
-    - `POST /api/fs/exec`
-    - `GET /api/fs/exec/:jobId`
-    - `GET /api/fs/list`
-    - `GET /api/fs/git-dirs` — shallow nested git repository discovery for the
-      Git tab (depth- and visit-capped readdir walk; `.git` directory, file, or
-      symlink marks a repository boundary; junk directories and symlinks are
-      never descended into)
-  - Owns exec job queue state (`execJobs`) and lifecycle/TTL pruning.
-  - Enforces workspace boundary checks with active project + worktree fallback support.
-  - The active project directory is validated with `fs.realpath`, so when the project root is itself a symlink the workspace base no longer matches the paths the client sends. Workspace resolution therefore retries against the raw directory the client requested (`requestedDirectory` from `resolveProjectDirectory`) before falling back to worktree roots. Symlinks are still resolved afterwards, and write/exec routes keep their canonical containment check against the resolved base.
-- `createFsSearchRuntime({ fsPromises, path, spawn, resolveGitBinaryForSpawn })` from `search.js`
-  - Returns `{ searchFilesystemFiles(rootPath, options) }`.
-  - Supports fuzzy matching, hidden-file handling, and optional `git check-ignore` filtering.
-
-## Composition contract with `index.js`
-- `index.js` provides composition-time dependencies only (platform primitives + callbacks such as `resolveProjectDirectory`, `normalizeDirectoryPath`, and `buildAugmentedPath`).
-- `index.js` no longer owns FS route handlers or FS exec job state.
-
-## Notes for contributors
-- Keep filesystem policy (workspace root checks, error mapping, exec timeout behavior) inside this module, not in the composition root.
-- Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Policy denials such as workspace-boundary or missing-grant failures must not use that marker because a native folder picker cannot remediate them.
-- Read-only routes authorize the requested path against the workspace before resolving symlinks. A symlink reached through the workspace may therefore target a file outside it, while a directly requested outside path still requires an exact-path grant. Write routes keep canonical-target boundary checks.
-- If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
-- `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.
-- `POST /api/fs/upload` accepts one `application/octet-stream` body with `path` and optional `overwrite=true` query parameters. The body streams into a same-directory temp file with a 100 MiB default cap configurable through `AIWORKER_FS_UPLOAD_MAX_BYTES`; failed and oversized uploads clean up that temp file. New files commit through an atomic no-replace link, existing files return `409` unless overwrite is explicit, directory targets are rejected, and the destination parent resolves before writing so uploads cannot escape through workspace symlinks.

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.