@loompad/cli 0.1.0 → 1.1.1

package/docs/refactoring/NOTES.md

@@ -0,0 +1,129 @@
+# Modularization notes
+
+## Constraints
+- No framework migration in this change; Next.js is a possible later choice.
+- Preserve URLs, event payloads, persisted config/state, and the public SDK.
+- Keep changes on `dev/Harsha`; no publishing or deployment is requested.
+- Ordinary tests use fake agents and isolated LOOM_HOME. Do not run paid
+  `verify-*` scripts as regression tests.
+
+## Baseline observations
+- `app-page.ts`: 15,434 lines, HTML/CSS/browser JS inside a TS template literal.
+- `server.ts`: 5,148 lines, route registration plus daemon lifecycle.
+- `runtime.ts`: 3,815 lines, project coordination plus multiple state owners.
+- Root dependencies were absent; Node 24.3.0 and npm 11.14.1 are installed.
+- `npm test` omits app-page-console-dom, app-queue-dom, app-servers-dom and
+  app-update-dom after excluding them from the parallel pass. Include all DOM
+  suites in final verification.
+- Historical design documents are not authoritative for current behavior.
+
+## Progress and decisions
+- Browser: ordinary ES modules in `src/web`, feature factories for per-project
+  closures, ordered CSS layers, and a document shell. esbuild packages the JS;
+  assets remain inline in the served page. No framework decision is required.
+- API: ordered feature registrars in `src/daemon/routes`, each receiving a typed
+  subset of daemon capabilities. Middleware and WebSocket lifecycle stay in
+  `server.ts`. Shared system helpers preserve their old exports.
+- Runtime: accounting, briefings, queue and turns own their state under
+  `src/daemon/runtime`. ProjectRuntime remains the public coordinator.
+- Build and desktop staging include generated web assets; daemon fingerprints
+  include CSS and HTML so desktop detects style-only changes.
+- Explicit dependency analysis exposed pre-existing out-of-scope browser calls:
+  preview attachments, notification replies, and explorer refresh. These now
+  use explicit mounted-project callbacks. Late screenshots are discarded if
+  their composer has been replaced by navigation.
+
+## Verification history
+- Initial build passed. The initial full test run in the sandbox hit EPERM
+  opening local sockets: 57 failed files, 69 passed, 1 skipped. This is not a
+  usable green baseline. Subsequent integration runs use allowed local sockets.
+- Browser extraction: 88 DOM checks passed; 45 static page checks passed.
+- Route extraction: 8 suites / 110 tests passed (auth, daemon, scoped clients,
+  workspace, relay, tasks, skills MCP, providers).
+- Runtime extraction: 124 tests passed, two test fixtures referenced a private
+  map that moved. Fixtures now access its owning turn module; the full rerun passes.
+- Full suite found a real source-mode regression: type-only re-exports worked
+  under tsc/Vitest but failed in the CLI's tsx process. Marked those exports
+  `type`; all 126 non-DOM suites now pass (1,342 tests, 17 skipped).
+- Browser unresolved-name analysis: zero unresolved names after extraction.
+- npm pack dry-run includes all four `dist/web` artifacts. Docker runner now
+  copies the browser build script; desktop staging verifies the new assets.
+- Build/typecheck/diff checks pass. Default DOM suites pass; pipe validation
+  exposed a timing-sensitive target-selector test in the previously omitted
+  queue suite. It now pauses the queue during selection instead of depending
+  on a two-second agent sleep; all six queue DOM tests pass in both modes.
+
+## Current module map
+
+| Previous hotspot | Current coordinator | Extracted responsibilities |
+| --- | --- | --- |
+| `app-page.ts` (15,434 lines) | 30 lines | `src/web/`: entry, feature modules, project factories, CSS layers and shell |
+| `server.ts` (5,148 lines) | 863 lines | `routes/`: typed feature registrars; `system.ts`: shared process helpers |
+| `runtime.ts` (3,815 lines) | 2,633 lines | `runtime/`: accounting, briefings, queue and turns; shared contracts in `runtime-support.ts` |
+
+All 217 literal HTTP registrations retain their original method/path order.
+The emitted CSS and non-script HTML match the original served page byte for byte.
+Feature factory exports were pruned to callbacks the coordinator actually uses;
+state setters are exposed only where the feature writes that binding.
+
+## Validation scope and follow-up boundaries
+
+- The default backend passed 1,342 non-DOM tests and all 125 DOM tests (the new
+  screenshot navigation test was corrected and passed in a focused rerun).
+- The source-mode CLI regression is fixed; compiled and source entrypoints are
+  both covered. Source-mode BUILD_REV retains the original `dev` marker.
+- Phone protocol copies match; all 41 phone pure-logic tests pass.
+- Docker image, Electron GUI and native phone builds were not run. Runner
+  build inputs and packaged asset paths were checked; desktop behavior has
+  automated coverage. Phone dependencies are not installed in this checkout.
+- No paid agent verification, deployment or framework migration.
+- This is an extraction with stable contracts. Browser shared session state and
+  per-project view coordination remain explicit; runtime agent event handling,
+  handoffs and orchestra lifecycle still live in ProjectRuntime. Future work
+  can change these boundaries incrementally once the framework is chosen.
+- Browser edits require rebuilding assets; there is no watch pipeline yet.
+
+
+## Final verification
+
+Completed on Node 24.3.0 / macOS. Full runs plus focused reruns after corrections:
+
+| Configuration | Passing tests | Skipped tests |
+| --- | --- | --- |
+| Default: non-DOM + DOM | 1,342 + 125 = 1,467 | 17 |
+| Forced pipe: non-DOM + DOM | 1,339 + 125 = 1,464 | 20 |
+| Phone pure logic | 41 | 0 |
+
+The full default attempt needed a focused rerun of the new screenshot test
+fixture; the full pipe attempt needed a focused rerun of the queue target test
+fixture. Both corrected suites pass. The final queue test also passes under
+the default backend. No unresolved test failures remain; a final monolithic
+`npm test` was not repeated after those focused reruns.
+
+Additional checks passed: `npm run build`, `npm run typecheck`, phone relay-copy
+consistency, npm package dry-run asset inclusion, browser unresolved-name
+analysis, exact CSS/non-script HTML comparison, endpoint registration order,
+and whitespace checks for both tracked and new files.
+
+Local test logs (temporary, not committed): `/tmp/loom-final-tests.log`,
+`/tmp/loom-pipe-tests.log`, `/tmp/loom-screenshot-tests.log`,
+`/tmp/loom-default-queue-tests.log`, `/tmp/loom-pipe-queue-tests.log`, and
+`/tmp/loom-phone-tests.log`.
+
+Branch is `dev/Harsha`, based on main at `838f994`. Publication target is
+`igharsha7/loom` (`origin`); the original repository is retained as `upstream`.
+TODO.md has no remaining work within the requested three steps.
+
+## Brain prerequisite follow-up
+
+The next phase separates event storage, conversation metadata, native adapter
+state/lifecycle, Brain preparation and client delivery. See
+[BOUNDARIES.md](BOUNDARIES.md) for ownership, fixes and remaining Brain work.
+Verification: build/typecheck passed; full test suite passed 1,482 tests with
+17 skipped, including all 125 browser DOM tests. It is now committed at
+`584a3b6a86bfa9af2a0a8ecbeac57e6aa4578e7a`. Brain continuity implementation remains
+pending review of [the plan](../proposals/brain-continuity-implementation.md).
+
+Brain cleanup and final validation are recorded in [BRAIN-AUDIT](BRAIN-AUDIT.md)
+and [BRAIN-NOTES](BRAIN-NOTES.md). Native execution no longer uses legacy decision
+mining/injection/extraction; supported compatibility workflows remain available.

package/docs/refactoring/T3-PORT-NOTES.md

@@ -0,0 +1,165 @@
+# t3code port — notes
+
+Working notes for the port: what t3code does, where, and how Loom maps it. Paths
+under `t3code/` refer to the local clone at `/Volumes/Programming Vault/t3code`
+(MIT, © T3 Tools Inc.). Ported files carry an attribution header.
+
+## Vocabulary mapping
+
+| t3code | Loom | Note |
+| --- | --- | --- |
+| thread | chat (conversation) | Loom's `MAIN_CHAT` and named chats. |
+| provider instance | agent config entry (`agents[].id`) | Kind plus options (bin, model, permissions). |
+| driver kind | agent kind (`codex`, `claude-code`) | |
+| session | one live provider session per **(chat, agent)** | t3code keys by thread alone because a thread never changes driver. Loom switches provider within a chat, so a chat can hold a parked session per agent. |
+| runtime mode | permission mode | full-access ↔ bypass, auto-accept-edits ↔ auto, approval-required ↔ ask. |
+| resume cursor | native session id (Codex thread id, Claude session id) | Persisted in the session directory. |
+
+## Sources read
+
+- Adapter contract: `t3code/apps/server/src/provider/Services/ProviderAdapter.ts`
+  (capabilities: `sessionModelSwitch`, `supportsConversationRollback`,
+  `promptlessTurnContinuation`; operations: start/send/interrupt/respond/
+  respondToUserInput/stop/list/has/readThread/rollbackThread/compaction/stopAll;
+  one `streamEvents` stream).
+- Runtime events: `t3code/packages/contracts/src/providerRuntime.ts` — envelope
+  `{eventId, provider, providerInstanceId, threadId, createdAt, turnId?, itemId?,
+  requestId?, providerRefs?, raw?, type, payload}`; ~50 types.
+- Session inputs: `t3code/packages/contracts/src/provider.ts`
+  (`ProviderSession`, `ProviderSessionStartInput`, `ProviderSendTurnInput`,
+  `ProviderTurnStartResult`).
+- Service: `t3code/apps/server/src/provider/Layers/ProviderService.ts` — routes
+  by the persisted binding; recovers a missing live session by adopting an
+  existing one or restarting from the resume cursor; refuses a cross-driver
+  switch (`ProviderCommandReactor.ts:690`).
+- Directory: `t3code/apps/server/src/provider/Services/ProviderSessionDirectory.ts`
+  — binding `{threadId, provider, providerInstanceId, status, resumeCursor,
+  runtimePayload, runtimeMode, lastSeenAt}`; stopped rows kept for their cursors.
+- Reaper: `t3code/apps/server/src/provider/Layers/ProviderSessionReaper.ts` — 30 min
+  inactivity, 5 min sweep; skips active turns and background work.
+
+## Decisions
+
+- **2026-09-28.** Port, not fork; plain TypeScript, no Effect. Warm sessions.
+  Codex and Claude Code only for now.
+- **2026-09-28, Phase 1.** Build the foundation (contract, service, directory,
+  reaper, ingestion) against a fake adapter and do not wire it into dispatch yet.
+  Phase 2's warm adapters change the turn lifecycle, so a temporary bridge around
+  the per-turn adapters would be thrown away.
+- **2026-09-28, Phase 1.** Session directory is a JSON file under
+  `.loom/providers/`, not a SQLite table: the event log has a JSONL fallback, and
+  the directory must work with both.
+- **2026-09-28.** Loom keeps other agents' sessions in a chat alive (parked) when
+  the chat switches agent, instead of t3code's `stopStaleSessionsForThread`. The
+  reaper bounds how long they stay warm.
+- **2026-09-28, Phase 1.** Ingestion emits a tool's `tool_call` when the item
+  **completes** (with its outcome), not when it starts. The old Claude adapter
+  reported tools as they started. Phase 3 adds item start/progress to the log and
+  UI; until then a long tool shows when it finishes.
+- **2026-09-28, Phase 1.** A turn the provider reports as `failed` becomes an
+  `error` with no `run_complete`, as t3code treats it. The old Claude adapter still
+  emitted `run_complete` after an error result outside Brain; Phase 2's adapter
+  follows the new rule.
+- **2026-09-28, Phase 1.** Approvals keep Loom's existing cards: `ApprovalBridge`
+  turns `request.opened` into a card through the daemon broker and answers with
+  `respondToRequest`. t3code's native approval options (accept for session,
+  accept always) arrive with Phase 3.
+- **2026-09-28, Phase 1.** `ensureSession` registers a start synchronously before
+  its first await, so concurrent callers always share it. A turn can finish before
+  `sendTurn` returns; the service remembers each session's last finished turn so
+  it never re-marks it active.
+
+## Sources read (Phase 1, continued)
+
+- Ingestion: `t3code/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts`
+  — assistant and reasoning text are the streamed deltas; the completed item's
+  `detail` is a whole-block snapshot used only when nothing streamed (lines
+  ~1960–2260).
+
+
+## Sources read (Phase 2)
+
+- Codex runtime: `t3code/apps/server/src/provider/Layers/CodexSessionRuntime.ts` —
+  `openCodexThread` (resume with `excludeTurns`, recoverable resume errors),
+  `buildTurnStartParams`, server-request handlers (approvals park on a deferred,
+  `acceptForSession` → session scope, permissions granted or an empty grant),
+  `interruptTurn` (settle open approvals *before* `turn/interrupt`), `close`.
+- Codex mapping: `t3code/apps/server/src/provider/Layers/CodexAdapter.ts` —
+  `mapToRuntimeEvents` (lines ~1307–2010), `toCanonicalItemType`,
+  `normalizeCodexTokenUsage` (`last.totalTokens` is the context in use).
+- Claude: `t3code/apps/server/src/provider/Layers/ClaudeAdapter.ts` — `startSession`
+  (~4382: prompt queue, `sessionId` chosen up front or `resume`,
+  `includePartialMessages`, `canUseTool`), `sendTurn` (~5127: `setModel`, user
+  message `uuid` = turn id), `interruptTurn` (~5276: closes the session),
+  `handleStreamEvent` (~2849), `handleResultMessage`, `stopSessionInternal`.
+- Verified live (2026-09-28, claude 2.1.x): resuming an unknown session id makes
+  `initializationResult()` reject with "No conversation found with session ID"
+  within ~2 s, before any prompt is read; a fresh session initializes in ~1 s
+  without a model call.
+
+## Decisions (Phase 2)
+
+- **2026-09-28 (superseded in Phase 3).** Phase 2 first kept process-group
+  settlement for continuity turns by ending the session after each one. That
+  contradicted the decided strategy: warm sessions everywhere, with turn-level
+  settlement replacing the process-group rule.
+- **2026-09-28, Phase 3.** Turn-level settlement for every turn: settled when the
+  harness reports the turn done and no command it started (a `command_execution`
+  item) is still running. The session stays warm, Brain turns included. A command
+  still running after 60 s leaves a Brain turn's quiescence unknown; an ordinary
+  turn moves on after 5 s (a harness can end a turn with an abandoned item). A
+  background process a tool detaches is outside what the harness reports, so it is
+  outside this guarantee.
+- **2026-09-28.** Loom's "auto" keeps `approvalPolicy: never` for Codex (t3code's
+  auto-accept-edits uses `on-request`): Loom promises auto never stops to ask.
+- **2026-09-28.** A handoff briefing now rides in front of the prompt for Claude
+  too (framed, as Codex always had it): a warm session's system prompt is fixed
+  when it starts.
+- **2026-09-28.** A failed turn outside continuity is not re-thrown by `send()`:
+  ingestion already logged the error, and the error event ends the turn. Continuity
+  turns still throw so Brain records the failure.
+- **2026-09-28.** Claude `Bash` is reported as the canonical `shell` tool (command
+  execution), like Codex. Nothing in Loom keyed on the name `Bash`.
+- **2026-09-28.** Codex `item/tool/requestUserInput` is still answered empty and
+  MCP elicitations declined; structured questions are Phase 3.
+- **2026-09-28.** One `ProviderService` per agent working directory (not per
+  project): native state already lives in the agent's directory (a worktree agent
+  has its own `.loom`), and the session directory file must have one writer.
+
+## Sources read (Phase 3)
+
+- `t3code/apps/server/src/provider/CodexDeveloperInstructions.ts` — plan/default
+  collaboration-mode prompts (ported verbatim, minus T3's browser/device blocks).
+- `CodexSessionRuntime.ts` — `buildCodexCollaborationMode` (~595: mode, model,
+  reasoning_effort default "medium", developer_instructions), request_user_input
+  handler (~2347) and `toCodexUserInputAnswer` (~1145), permissions approval
+  (`scope: "session"` on acceptForSession).
+- `CodexAdapter.ts` — `toUserInputQuestions` (~883), async questions on
+  `agentMessage` with `delivery: "async"` (~1694, `responseMode: "message"`), plan
+  item → `turn.proposed.completed`.
+- `ClaudeAdapter.ts` — `handleAskUserQuestion` (~4441: question id = question text,
+  answers returned as `updatedInput.answers`), `canUseTool` (~4651: ExitPlanMode
+  captured and denied, full-access allows, otherwise asks),
+  `toSessionPermissionUpdates` (~311), `sendTurn` plan mode via
+  `setPermissionMode` (~5179), `compaction: { type: "slash-command", command:
+  "/compact" }` (~5561).
+- Verified live: Claude Code's plan mode writes its plan to
+  `~/.claude/plans/<slug>.md` before calling ExitPlanMode.
+
+## Decisions (Phase 3)
+
+- **2026-09-28.** Claude's `canUseTool` is registered in every mode (as t3code) so
+  questions and plans reach Loom. Other tools: full access allows; approval-required
+  asks a person; auto denies without asking (Loom's auto never stops to ask — a tool
+  runs there only if Claude's settings pre-allow it, as before).
+- **2026-09-28.** Tool progress is live-only (websocket `item` frames), not new log
+  events: the log keeps one `tool_call` per finished tool, which is what Brain's
+  evidence and the transcript read.
+- **2026-09-28.** Codex plan mode is sent only when a turn is a plan turn, and the
+  default mode once afterwards to leave it — not on every turn as t3code does — so
+  a user who never plans gets Codex's own prompt unchanged.
+- **2026-09-28.** A plan turn on a provider agent uses native plan mode (which
+  changes nothing) instead of Loom's "write plans/…md" briefing; Loom writes the
+  proposed plan to `plans/` itself, so the artifact stays.
+- **2026-09-28.** A Claude write outside the session directory (plan mode's own
+  plan file) is a tool call, not a project file edit.

package/docs/refactoring/T3-PORT-TODO.md

@@ -0,0 +1,123 @@
+# t3code port — TODO
+
+Plan: [t3code-port.md](../proposals/t3code-port.md). Notes and sources:
+[T3-PORT-NOTES.md](T3-PORT-NOTES.md). Scope for now: **Codex and Claude Code only**;
+relay, mobile and other providers are out of scope.
+
+Rules: phase by phase, fakes-only tests at every step, one authorized live check per
+harness per phase, and never modify a provider's own config (`~/.codex/config.toml`,
+Claude settings); override per session through the protocol instead.
+
+## Phase 1 — Provider contract and service ✅ (2026-09-28)
+
+- [x] `src/providers/contracts.ts`: provider kinds, runtime modes, session and turn
+  inputs, capabilities, normalized item data, and the canonical runtime event union
+  (26 types), ported from t3code `packages/contracts/src/provider*.ts`.
+- [x] `src/providers/adapter.ts`: the `ProviderAdapter` interface and `EventHub`.
+- [x] `src/providers/errors.ts`: `ProviderError` (validation, not_found,
+  session_missing, unsupported, request, transport) with `notSubmitted`.
+- [x] `src/providers/directory.ts`: session directory keyed by (chat, agent), in
+  memory and as an atomic JSON file; unreadable files moved aside.
+- [x] `src/providers/service.ts`: `ProviderService` — register/unregister,
+  ensureSession (live / resumed / fresh, shared concurrent start, lost session →
+  `session_missing` or fresh on request), sendTurn, interrupt, respond, compact,
+  rollback, stop, stopAll, event fan-in keeping the directory and active turns.
+- [x] `src/providers/reaper.ts`: idle reaper (30 min / 5 min; skips running turns
+  and caller-reported background work).
+- [x] `src/providers/ingestion.ts`: canonical events → Loom log events; streamed
+  text assembled per item with completed-item fallback; live delta channel; Brain
+  tags per turn; large command output to artifacts.
+- [x] `src/providers/approvals.ts`: `request.opened` → Loom approval cards → answer
+  through the service; cards close when the turn or session ends.
+- [x] Fake adapter and tests (`test/providers/`, 45 tests). Full suite green.
+- [x] Docs: ARCHITECTURE owner rows; notes.
+- [ ] Live check: none this phase — nothing is wired to a real harness yet.
+
+## Phase 2 — Warm sessions for Codex and Claude ✅ (2026-09-28)
+
+- [x] Codex adapter on the contract (`src/providers/codex/`): one `app-server` per
+  chat session in its own process group, thread kept open, turns and interrupts on
+  one connection; notifications, deltas and server requests mapped to canonical
+  events (t3code's `mapToRuntimeEvents`, `toCanonicalItemType`,
+  `normalizeCodexTokenUsage`); approvals wait for `respondToRequest`; manual
+  compaction (`thread/compact/start`).
+- [x] Claude adapter on the contract (`src/providers/claude/`): one streaming-input
+  `query()` per chat session, session id chosen up front, `initializationResult()`
+  proves the session (a lost resume fails here, before any prompt), turns pushed as
+  user messages, `setModel` in-session, `canUseTool` → `request.opened`, partial
+  messages → deltas, interrupt closes the session (t3code's hard boundary).
+- [x] Runtime dispatch: `ProviderAgent` (`src/providers/agent.ts`) is the runtime's
+  Adapter for `codex` and `claude-code`; one `ProviderService` per working
+  directory with the file directory, reaper and approval bridge. `SendInput.chat`
+  added; sessions keyed by (chat, agent). Old per-turn adapters deleted
+  (`adapters/codex.ts`, `adapters/claude-code.ts`); `codex-rpc.ts` moved to
+  `providers/codex/rpc.ts`. The pre-warm per-agent session id migrates to the main
+  chat's binding. A rebuilt agent (model/permission change) takes over its
+  predecessor's sessions. MCP server changes restart and resume the session.
+- [x] Brain: turn-level settlement — a turn is settled when the harness reports it
+  done and no command it started is still running; the session stays warm.
+  (Phase 2 first shipped "a continuity turn ends its session"; corrected in Phase 3
+  to the decided turn-level rule. See notes.)
+- [x] Token streaming: `content.delta` → `LiveDeltaThrottle` (50 ms) → `delta`
+  websocket frames; a minimal streaming bubble in the web thread, replaced by the
+  finished message.
+- [x] Tests: `test/providers/warm.test.ts` (16), throttle test; fakes serve many
+  turns per process (`scripts`, `turnsOf`); existing Codex/Claude/MCP/continuity
+  tests run against the warm agent. Full suite green.
+- [x] Live check per harness (read-only mode, scratch project): Codex
+  (`gpt-6-astra` override; `~/.codex/config.toml` untouched) and Claude each ran one
+  turn; session stayed warm after the turn, the reply streamed as a delta, the
+  process group was gone after stop.
+
+## Phase 3 — Interaction parity ✅ (2026-09-28)
+
+- [x] Tool progress: `item.started/updated/completed` → live `item` websocket frames
+  (a "running" row in the thread), command output as live deltas; the finished tool
+  is still one `tool_call` in the log.
+- [x] Approvals with native options: `request.opened.options` (Allow / Allow for this
+  session / Deny); Loom cards gain "Allow for session" when offered; Codex gets
+  `acceptForSession`, Claude gets its own permission suggestions scoped to the session.
+- [x] Structured user input: Codex `item/tool/requestUserInput` (answers
+  `{id: {answers: []}}`), Codex async questions (answer with the next message),
+  Claude `AskUserQuestion` via `canUseTool` (answers keyed by question text).
+  `needs_input` carries `questions`, `requestId`, `responseMode`; answered via
+  `POST /api/projects/:id/agents/:agent/answers`; question cards in the thread.
+- [x] Plan mode: Codex collaboration mode (t3code's developer instructions, ported
+  in `providers/codex/instructions.ts`), left on the next default turn; Claude
+  `setPermissionMode("plan")` and `ExitPlanMode` captured as the proposed plan.
+  Loom's plan turns on provider agents use native plan mode; the runtime saves the
+  proposed plan to `plans/<day>-<slug>.md` (`status: plan_saved`).
+- [x] Manual compaction: Codex `thread/compact/start`; Claude `/compact` as a turn
+  (t3code's slash-command compaction). `POST /api/projects/:id/agents/:agent/compact`.
+- [x] Reasoning effort: agent option `effort` → Codex `turn/start.effort`, Claude
+  query `effort` at session start.
+- [x] Turn-level settlement (correction of Phase 2), bounded: 60 s for Brain turns
+  (then quiescence unknown), 5 s for ordinary turns.
+- [x] Tests: `test/providers/interaction.test.ts` (13),
+  `test/providers/runtime-interaction.test.ts` (2). Full suite green.
+- [x] Live check (read-only, scratch project): a plan-mode turn on each harness.
+  Codex explored with one command and proposed a plan (captured). Claude wrote its
+  plan to its own `~/.claude/plans/` file and called ExitPlanMode (captured); the
+  project was untouched. Found and fixed: that plan file was logged as a project
+  edit.
+- Moved: model catalogs (`model/list`, `supportedModels()`) to Phase 6 (provider
+  management). Per-turn diffs: Loom's own `turn_diff` (git, per turn) already covers
+  both providers; Codex's `turn.diff.updated` is mapped but not yet shown.
+
+## Phase 4 — Checkpoints and revert
+
+- [ ] Hidden-ref checkpoints per turn; revert coordinated with native rollback;
+  refuse before touching files when rollback is unsupported.
+
+## Phase 5 — Cross-provider switching
+
+- [ ] Park/resume sessions across providers within a chat; Brain packet sized by the
+  target's context window; switch offered at a usage limit; revert across a provider
+  boundary; continuity on by default.
+
+## Phase 6 — Provider management
+
+- [ ] Instances (several accounts per driver), auth status, install/update
+  detection, native session history import.
+
+## Phase 7 — UI overhaul

package/docs/refactoring/TODO.md

@@ -0,0 +1,46 @@
+# Modularization work
+
+Branch: `dev/Harsha`, based on local `main` at `838f994`.
+
+Scope: preserve existing behavior and public contracts while separating the web
+client, HTTP routes, and project runtime. Framework selection is deferred.
+
+## 0. Baseline
+- [x] Create the requested branch from main; confirm a clean checkout.
+- [x] Read contribution instructions and map the three large modules.
+- [x] Install dependencies and build; baseline test run was blocked by sandbox socket restrictions (see notes).
+
+## 1. Web client
+- [x] Extract browser JavaScript, styles, and document shell.
+- [x] Split browser behavior into feature modules with explicit dependencies.
+- [x] Preserve startup order, pairing, asset packaging, and desktop/phone behavior.
+- [x] Run script parsing, DOM, packaging, and daemon tests.
+
+## 2. HTTP routes
+- [x] Separate route registration by feature with typed dependencies.
+- [x] Preserve middleware order, authentication, response shapes, and streaming.
+- [x] Run API, auth, WebSocket, and affected integration tests.
+
+## 3. Project runtime
+- [x] Extract accounting and budget ownership.
+- [x] Extract briefing and memory coordination.
+- [x] Extract queue coordination and turn execution.
+- [x] Preserve lifecycle, interruption, retries, chat routing, and cleanup.
+- [x] Run runtime, adapter, queue, memory, route, and orchestra regressions.
+
+## 4. Finish
+- [x] Update source maps and contributor instructions.
+- [x] Build, typecheck, run the full suite including omitted DOM suites.
+- [x] Verify packaging and `git diff --check`.
+- [x] Record limitations and final verification in NOTES.md.
+
+Completed: all three requested extractions. Framework selection remains deferred.
+See NOTES.md for verification results and deliberately retained boundaries.
+
+The next authorized phase is tracked in [BOUNDARIES.md](BOUNDARIES.md): separating
+storage, native adapters, Brain preparation and client delivery before building
+Brain continuity. The completed checklist above describes the earlier extraction.
+
+Brain continuity implementation is tracked separately in [BRAIN-TODO.md](BRAIN-TODO.md),
+with source research and edge-case IDs in [BRAIN-NOTES.md](BRAIN-NOTES.md).
+The plan is awaiting user review; the checklist does not authorize implementation.

package/docs/refactoring/brain-benchmark-2026-09-28.json

@@ -0,0 +1,48 @@
+{
+  "measuredAt": "2026-09-28T08:24:36.883Z",
+  "node": "v24.3.0",
+  "hardware": {
+    "platform": "darwin",
+    "arch": "arm64",
+    "cpu": "Apple M4",
+    "memoryBytes": 17179869184
+  },
+  "corpus": {
+    "events": 10001,
+    "buriedUserPoints": 20,
+    "attempts": 30,
+    "paidCalls": 0,
+    "git": false
+  },
+  "preparationMs": {
+    "p50": 19.03137499999866,
+    "p95": 25.583166000000347
+  },
+  "retrievalMs": {
+    "p50": 0.29900000000088767,
+    "p95": 0.7585829999989073
+  },
+  "daemonLoopMs": {
+    "p95": 19.464191,
+    "max": 25.772031
+  },
+  "appAddedTokens": {
+    "minimum": 3034,
+    "maximum": 3034,
+    "estimation": "UTF-8 bytes / 3 heuristic"
+  },
+  "exactReplayEstimatedTokens": 258978,
+  "allBuriedUserPointsIncluded": true,
+  "legacyRecent400ContainsFirstPoint": false,
+  "processMemory": {
+    "rss": 119554048,
+    "heapTotal": 48218112,
+    "heapUsed": 22705600,
+    "external": 2129463,
+    "arrayBuffers": 25235
+  },
+  "diskBytes": 4829184,
+  "nativeTokens": null,
+  "helperTokens": 0,
+  "continuationQuality": "native understanding not measured; exact source inclusion checked"
+}

package/docs/refactoring/brain-benchmark-audit-2026-09-28.json

@@ -0,0 +1,48 @@
+{
+  "measuredAt": "2026-09-28T09:18:19.345Z",
+  "node": "v24.3.0",
+  "hardware": {
+    "platform": "darwin",
+    "arch": "arm64",
+    "cpu": "Apple M4",
+    "memoryBytes": 17179869184
+  },
+  "corpus": {
+    "events": 10001,
+    "buriedUserPoints": 20,
+    "attempts": 30,
+    "paidCalls": 0,
+    "git": false
+  },
+  "preparationMs": {
+    "p50": 13.088791999999557,
+    "p95": 13.847000000000662
+  },
+  "retrievalMs": {
+    "p50": 0.2079169999997248,
+    "p95": 0.22337500000003274
+  },
+  "daemonLoopMs": {
+    "p95": 18.120703,
+    "max": 19.021823
+  },
+  "turnInputEstimatedTokens": {
+    "minimum": 3047,
+    "maximum": 3047,
+    "estimation": "UTF-8 bytes / 3 heuristic"
+  },
+  "exactReplayEstimatedTokens": 258978,
+  "allBuriedUserPointsIncluded": true,
+  "legacyRecent400ContainsFirstPoint": false,
+  "processMemory": {
+    "rss": 123125760,
+    "heapTotal": 47955968,
+    "heapUsed": 22995376,
+    "external": 2129449,
+    "arrayBuffers": 25221
+  },
+  "diskBytes": 4829184,
+  "nativeTokens": null,
+  "helperTokens": 0,
+  "continuationQuality": "native understanding not measured; exact source inclusion checked"
+}

package/docs/release-notes/v0.2.0.md

@@ -0,0 +1,35 @@
+## Loom 0.2.0 — Loom Teams
+
+Several people, each with their own agents, on one GitHub repo — without
+stepping on each other. Built in five phases (78 design decisions, in
+[docs/teams-architecture.md](https://github.com/nickthelegend/loom/blob/main/docs/teams-architecture.md)):
+
+1. **See each other.** Teammates' live agents, goals and the files they touch;
+   a team feed of goals, PRs and CI. End-to-end encrypted: the hub can't read
+   your goals.
+2. **Stop colliding.** Tasks declare the files they touch; overlaps need a
+   decision; hard zones take one goal at a time; merge conflicts are predicted
+   before anyone opens a PR; `loom.team.json` is the team's policy.
+3. **One brain.** What one agent learns, every agent knows — labelled by how
+   sure to be. Canon lives in `AGENTS.md`, reviewed like code.
+4. **Land safely.** Failing checks are rerun, then fixed on the same PR; an
+   agent from another vendor reviews; one click lands through GitHub's rules;
+   stacks, Adopt, budgets, a merge-queue doctor.
+5. **Runners.** Your own always-on Loom takes your goals while your laptop
+   sleeps; move a running goal there and bring it back. Deploy status and
+   release notes.
+
+**Get started:** [docs/teams.md](https://github.com/nickthelegend/loom/blob/main/docs/teams.md).
+
+### Downloads
+
+- **macOS**: `Loom-Desktop-0.2.0-arm64.dmg` (Apple Silicon) or `-x64.dmg` (Intel)
+- **Windows**: the `.exe` installer
+- **Linux**: `.AppImage` or `.deb`
+- **Android**: `loompad-0.2.0-android.apk`
+- **CLI**: `npm install -g github:nickthelegend/loom`
+
+The installers are unsigned. On macOS, right-click → Open the first time; on
+Windows, "More info → Run anyway". Checksums are in `SHA256SUMS.txt`.
+
+Full list of changes: [CHANGELOG.md](https://github.com/nickthelegend/loom/blob/main/CHANGELOG.md).

package/docs/release-notes/v0.2.1.md

@@ -0,0 +1,59 @@
+## Loom 0.2.1 — the prompt queue, and a real Android build
+
+### Line up the next ones
+
+Type while an agent is mid-turn, or while a goal is still running, and the
+prompt waits above the composer instead of being refused or quietly swallowed.
+
+- **Queue as many as you like.** They run strictly one at a time, in order.
+- **Each prompt says who takes it:** one agent by name, the **orchestrator**
+  (a whole new goal, started when the running one finishes), or **Auto** to let
+  the router pick. Change a waiting prompt's target and the baton goes with it.
+- **Edit, reorder, drop.** Click a queued prompt to rewrite it (⌘⏎ saves, Esc
+  cancels), move it up or down, or remove it — all before it runs.
+- **Pause and resume.** **Stop** pauses too: stopping a turn never silently
+  discards what you lined up behind it.
+- **A question holds the queue.** If the agent stops to ask you something, the
+  next queued prompt would answer a question you never read — so the queue waits
+  and says who asked. Your reply goes out at once and lifts the hold.
+- **A prompt enters the conversation when it is sent**, not when it is queued,
+  so the thread stays an honest record of what each agent was asked.
+
+It survives a daemon restart (reloaded paused, so an hour-old queue doesn't
+start itself) and it is the same queue everywhere: the web app, the desktop app,
+the phone, and `loom queue` in the terminal — `add`, `edit`, `to`, `move`, `rm`,
+`clear`, `pause`, `resume`.
+
+### Fixed
+
+- **The v0.2.0 apk had no JavaScript bundle** and would only open against a
+  running dev server. This one is a release build with the bundle in it, signed
+  with the project's release key — check it with
+  `apksigner verify --print-certs`.
+- **The macOS app is now a valid signed bundle** (ad-hoc). `codesign --verify
+  --deep --strict` passes; v0.2.0 carried only the linker's signature.
+- **An overridden `loom/review` stays overridden.** A review that came back
+  after the owner had overridden it used to write `failure` over their decision
+  — and, once that was fixed, to leave its own "reviewing…" status pending for
+  ever on a repo that requires the check. Both are gone.
+- **Agent turns are no longer blamed for Loom's own `.loom/` files** in a
+  project that doesn't gitignore them.
+- **grok-code and agy** are detected from their own auth files instead of being
+  reported signed-out, and the status bar says **live**, not offline, before a
+  project is open.
+- **A reply that lands after its window closed** no longer throws from a redraw.
+
+### Downloads
+
+- **macOS**: `Loom-Desktop-0.2.1-arm64.dmg` (Apple Silicon) or `-x64.dmg` (Intel)
+- **Windows**: the `.exe` installer
+- **Linux**: `.AppImage` or `.deb`
+- **Android**: `loompad-0.2.1-android.apk`
+- **CLI**: `npm install -g github:nickthelegend/loom`
+
+The Android apk is signed with the project's release key. The desktop
+installers are not signed by a certificate authority: on macOS the app is
+ad-hoc signed, so right-click → Open the first time; on Windows, "More info →
+Run anyway". Checksums are in `SHA256SUMS.txt`.
+
+Full list of changes: [CHANGELOG.md](https://github.com/nickthelegend/loom/blob/main/CHANGELOG.md).