@moretea-labs/forge 1.5.0-rc.1

package/docs/operations/controller-browser-plugin.md

@@ -0,0 +1,299 @@
+# Controller Browser Plugin
+
+The `browser` plugin gives the controller a bounded local browser surface for page reading and explicitly authorized interaction. It supports Playwright-managed contexts, loopback CDP attachment, and macOS active-tab attachment through Apple Events for Google Chrome and Vivaldi.
+
+## Scope
+
+Supported action groups:
+
+- **Session lifecycle**: `create_session`, `list_sessions`, `close_session`, `clear_session`, `close_page`
+- **Navigation**: `open_page`, `navigate`, `reload`, `go_back`, `wait_for_load_state`
+- **DOM / extraction**: `get_text`, `get_html`, `query_selector`, `query_all`, `get_attribute`, `extract_links`, `extract_tables`, `extract_forms`, `snapshot_interactive`
+- **Screenshots / artifacts**: `screenshot` (page, full-page, or element selector)
+- **Forms / interaction** (authorized): `click`, `double_click`, `hover`, `focus`, `type`, `fill`, `select_option`, `check`, `uncheck`, `press`, `keyboard_shortcut`, `wait_for_selector`
+- **Bounded file transfer** (authorized): `attach_local_file`, `await_file_transfer`
+- **Diagnostics**: `get_console_errors`, `get_failed_requests`
+
+Still out of scope by design:
+
+- free-form submit / delete / publish / payment / send workflows as first-class actions
+- auto-opening downloaded executables
+- leaking cookies, tokens, or raw profile secrets in responses
+
+Interactions that can mutate remote state still require `confirm_authorization=true`. Domain allowlists remain enforced for every navigation and interaction result.
+
+## Runtime model
+
+- `plugin_id` stays `browser`
+- the provider is local browser automation: configured loopback CDP, macOS Apple Events for an already-running Chrome/Vivaldi tab, or a Playwright persistent context
+- the default profile mode is `repo_local`, with profile data under `.forge/browser/profiles/`
+- `profileMode=custom` is explicit-only and uses the configured Chromium-family profile path directly when launching a managed context
+- saved sessions live under `.forge/browser/sessions/`
+- screenshots live under `.forge/browser/screenshots/`
+- downloads live under `.forge/browser/downloads/`
+
+The browser mode is explicit:
+
+- `managed_persistent` is the default and preserves the previous behavior: each action launches a visible persistent Playwright context, restores the target URL, performs one bounded operation, persists session metadata, then closes the context.
+- `attach_preferred` uses a strict order: configured loopback CDP endpoints; then an already-running, scriptable macOS Vivaldi or Google Chrome instance; then `cdpAttachFallback`. CDP inventory reuses a previously owned matching tab. Apple Events uses the active browser only for discovery, creates a plugin-owned background tab for a new session, preserves the user's active tab, and reattaches directly to the saved window/tab identity on later actions.
+- `isolated` launches a visible persistent context with a per-session repo-local profile under `.forge/browser/profiles/isolated/<session_id>`. It does not share the default plugin profile or a configured custom profile.
+
+Session metadata is reusable across actions via `session_id`. Any action that returns a generated `sessionId` persists that session before returning, so the identifier is immediately valid for follow-up actions. Transient navigation failures can retry with `retries` (1–3).
+
+### Reliability and safety notes
+
+- Domain allowlist is checked before navigation and after interactive URL changes.
+- Selector failures include repair hints (`repairHint`) when possible. Selector snapshots prefer unique `data-*`, role/ARIA, name, and non-generated id anchors; structural `nth-of-type` paths are only a last resort and are derived from the actual DOM sibling position rather than result order.
+- Console errors and failed requests are captured for Playwright/CDP cycles. Apple Events attachment reports empty console/network diagnostics because those streams are not exposed by the browser scripting dictionary.
+- Artifacts stay under `.forge/browser/**` (not arbitrary local paths).
+- CDP attach is bounded to configured loopback endpoints only; the plugin does not scan arbitrary ports or remote hosts. Native discovery checks only the configured Chrome/Vivaldi candidates and does not launch them.
+- CDP browsers are disconnected after the action; Apple Events keeps plugin-owned session tabs open until `close_session`/`close_page` while preserving user-owned tabs; managed contexts are closed after the action. Standard native DOM reads/interactions do not foreground the owned tab and return DOM evidence instead of attempting a screenshot.
+- Health `userFacingStatus` reports `ready`, `domain restricted`, `session active`, or setup states.
+
+## Configuration
+
+The source of truth is `.forge/plugins/browser.json`.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "provider": "playwright",
+  "browserMode": "attach_preferred",
+  "profileMode": "repo_local",
+  "nativeAttachMode": "auto",
+  "nativeBrowserCandidates": ["vivaldi", "chrome"],
+  "cdpAttachFallback": "managed_persistent",
+  "browserChannel": "chromium",
+  "defaultTimeoutMs": 30000,
+  "allowedDomains": ["example.com", "docs.example.com"]
+}
+```
+
+`allowedDomains` is the safety boundary. If it is empty, the plugin can target any HTTP(S) host. If it is set, the plugin accepts only exact hosts or subdomains of those entries.
+
+Additional browser/profile fields:
+
+- `browserMode`
+  - `managed_persistent` keeps the existing persistent-context lifecycle.
+  - `attach_preferred` tries configured CDP endpoints, then macOS Apple Events when enabled, then follows `cdpAttachFallback`.
+  - `isolated` uses a per-session repo-local profile under `.forge/browser/profiles/isolated/`.
+- `profileMode`
+  - `repo_local` keeps the plugin on the repo-owned Playwright profile under `.forge/browser/profiles/default`.
+  - `custom` is the explicit opt-in path for an existing Chrome/Chromium profile.
+- `profileDir`
+  - required when `profileMode=custom`
+  - may point either at a browser user-data directory or at one profile subdirectory such as `Profile 1`
+- `profileDirectory`
+  - optional when `profileDir` points at the browser user-data directory
+  - selects one Chrome profile inside that user-data directory
+- `browserChannel`
+  - `chromium` (default bundled Playwright engine)
+  - `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`
+- `executablePath`
+  - explicit Chrome/Chromium binary path
+  - mutually exclusive with `browserChannel`
+- `cdpEndpoint`
+  - optional primary DevTools endpoint for `attach_preferred`
+  - must be loopback-only and use `http`, `https`, `ws`, or `wss`
+  - HTTP(S) endpoints are probed at `/json/version`; a returned `webSocketDebuggerUrl` is passed to Playwright `connectOverCDP`
+- `cdpEndpointCandidates`
+  - optional ordered fallback endpoints
+  - capped at five total configured endpoints
+- `cdpDiscoveryTimeoutMs`
+  - bounded to 5 seconds; default is 1500 ms
+- `cdpAttachFallback`
+  - `managed_persistent` (default) launches the managed persistent context when attach fails
+  - `fail_closed` returns `PLUGIN_BROWSER_ATTACH_UNAVAILABLE` with CDP and native-attempt diagnostics and does not launch a new browser
+- `nativeAttachMode`
+  - `auto` (default) enables macOS Apple Events attachment after CDP attempts fail
+  - `disabled` skips native browser discovery
+- `nativeBrowserCandidates`
+  - ordered list containing `vivaldi` and/or `chrome`; the default is `["vivaldi", "chrome"]`
+  - if multiple candidates are running and scriptable, the frontmost browser wins; otherwise candidate order wins
+  - discovery checks installation, process state, and active-tab metadata without launching the browser
+
+For an already-running signed-in browser on macOS, prefer `browserMode=attach_preferred` with `nativeAttachMode=auto`. The plugin reuses the running browser process and login state without copying profile data, but does not reuse the user's active tab as an automation target. It creates and owns a separate background tab. `profileMode=custom` remains the explicit path for launching a separate Playwright context against a selected Chromium-family profile.
+
+Example custom Chrome automation-profile binding:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "provider": "playwright",
+  "browserMode": "attach_preferred",
+  "profileMode": "custom",
+  "profileDir": "/Users/alice/Library/Application Support/Google/Chrome",
+  "profileDirectory": "Profile 1",
+  "browserChannel": "chrome",
+  "cdpEndpoint": "http://127.0.0.1:9222",
+  "cdpAttachFallback": "fail_closed",
+  "defaultTimeoutMs": 30000,
+  "allowedDomains": ["appstoreconnect.apple.com"]
+}
+```
+
+If `profileMode=custom` points at a live personal Chrome profile, close that same Chrome/Chromium instance first when the browser reports profile-lock or profile-in-use errors.
+
+For `attach_preferred`, start Chrome/Chromium with a non-default automation profile and `--remote-debugging-port=<port>`. Chrome 136+ blocks remote debugging against the default user data directory; use a separate automation profile. The plugin does not launch Chrome with remote debugging flags by itself.
+
+### Active signed-in Chrome or Vivaldi on macOS
+
+Use native attachment when the target session is already logged in:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "provider": "playwright",
+  "browserMode": "attach_preferred",
+  "nativeAttachMode": "auto",
+  "nativeBrowserCandidates": ["vivaldi", "chrome"],
+  "cdpAttachFallback": "managed_persistent",
+  "allowedDomains": ["chatgpt.com", "example.com"]
+}
+```
+
+The attach order is CDP, then Apple Events, then managed fallback. macOS may require Automation permission for the controller/Node process to control Vivaldi or Google Chrome. The browser must also permit JavaScript from Apple Events for DOM extraction and interaction. If either permission is unavailable or the browser has no window, the attempt is recorded and fallback policy applies. The provider uses the active browser only for discovery, then operates on a plugin-owned tab identified by stable window/tab metadata. It does not read cookies or storage and re-checks the target URL against `allowedDomains` before and after actions.
+
+Native limitations are explicit: console/network event capture is unavailable and native file-input/download semantics are not equivalent to Playwright. A screenshot of a plugin-owned background tab fails closed with `PLUGIN_BROWSER_FOREGROUND_REQUIRED`; Forge does not silently activate the tab just to capture evidence. Use explicit foreground/human handoff, CDP, or a managed context for workflows that require screenshots or capabilities not available through background DOM automation.
+
+### Silent native tab semantics
+
+Apple Events attachment treats silence as the default execution contract:
+
+- new sessions create a background plugin-owned tab and leave the browser's active tab unchanged;
+- saved native sessions reattach directly by stable `windowId` + `tabId`, without rediscovering or borrowing the user's active tab;
+- DOM reads, form fill, click, reload, page-owned navigation, and history back remain in the owned background tab when Chrome/Vivaldi supports them;
+- explicit cross-URL `open_page`/`navigate` on an existing native session uses a replacement transaction: create and validate a new background owned tab, then close the old owned tab. This avoids unreliable in-place background navigation and preserves the user's foreground tab;
+- if replacement validation fails, the new tab is closed and the prior owned tab remains authoritative;
+- native tab ownership is the stable window/tab reference itself. CDP keeps its separate owner-token mechanism;
+- only explicitly foreground-dependent operations such as screenshot capture or human handoff may require visible foreground presentation. They fail closed rather than activating implicitly.
+
+The live macOS acceptance test covers background replacement, DOM fill/click, click-driven navigation, session URL refresh, `go_back`, `reload`, explicit screenshot refusal, session close, and verifies both the user's active Chrome tab and the system frontmost application remain unchanged.
+Run it explicitly on a macOS workstation with a running Chrome instance:
+
+```bash
+bun run test:browser-live
+```
+
+## Tab Resume And Diagnostics
+
+When attaching through CDP, the plugin inventories existing tabs by index, URL, and title. Selection is deterministic:
+
+1. saved session URL and title
+2. saved session URL
+3. requested URL
+4. blank tab
+5. new tab
+
+This avoids opening duplicate tabs when a matching tab already exists. Saved session metadata includes the last browser mode, active mode, CDP endpoint, fallback outcome when applicable, tab key, tab URL/title/index, and a resume diagnostic. If the saved tab is not present during a later attach, responses include `sessionResume.status=stale_tab` and explain whether another target URL tab, a blank tab, or a new tab was used.
+
+Stale or unavailable CDP endpoints and unavailable native browsers return attempt-level diagnostics. With `cdpAttachFallback=managed_persistent`, those diagnostics appear in `browserConnection.fallback`; with `fail_closed`, the action fails before launching a managed context. Native sessions record `provider=macos-apple-events` and `browserProduct=vivaldi|chrome`.
+
+## Policy surface
+
+Readonly actions:
+
+- `open_page`
+- `get_text`
+- `screenshot`
+- `close_page`
+
+These stay `confirmation=none` and `risk=readonly`.
+
+Interactive actions:
+
+- `click`
+- `type`
+- `press`
+- `wait_for_selector`
+
+These require `confirmation=authorization`.
+
+Risk levels:
+
+- `click`, `type`, `press` use `risk=remote_write`
+- `wait_for_selector` uses `risk=workspace_write`
+
+## Allowed-domain enforcement
+
+The plugin enforces `allowedDomains` in three places:
+
+1. It validates the explicit `url` before opening a page.
+2. It validates any saved `session_id` target before interaction.
+3. It re-checks the resulting page URL after the action and rejects the result if navigation leaves the allowed set.
+
+The plugin does not intentionally provide any action that can bypass this boundary.
+
+## Dependency requirement
+
+The browser plugin requires the `playwright` package in the repo runtime.
+
+If Playwright is missing:
+
+- plugin health reports a dependency error
+- action execution returns `PLUGIN_DEPENDENCY_MISSING`
+- the expected remediation is `bun install`
+
+## Interaction results
+
+Successful `click`, `type`, `press`, and `wait_for_selector` responses include:
+
+- the resolved `url`
+- the page `title`
+- an `action.summary`
+- updated `session` metadata
+- a best-effort screenshot path when capture succeeds
+
+Example response shape:
+
+```json
+{
+  "provider": "playwright",
+  "url": "https://example.com/",
+  "title": "Example",
+  "action": {
+    "actionId": "click",
+    "summary": "Clicked #cta."
+  },
+  "session": {
+    "sessionId": "browser_1234abcd",
+    "url": "https://example.com/",
+    "title": "Example"
+  },
+  "screenshot": {
+    "path": ".forge/browser/screenshots/..."
+  }
+}
+```
+
+## Usage notes
+
+- Prefer `open_page` first when you need a stable `session_id`.
+- `click`, `type`, `press`, and `wait_for_selector` accept either `session_id` or `url`.
+- If both `session_id` and `url` are provided, they must resolve to the same page target.
+- `close_page` only removes saved session metadata. It does not delete the persistent profile.
+- `profile_dir` is rejected unless `profile_mode=custom` is already configured or supplied in the same `configure` call.
+- Visible Chromium-family launches are supported, but managed actions still close after they complete. Apple Events attachment preserves the user's current Vivaldi/Chrome process and login state. For longer human-driven login, MFA, or consent steps in a managed profile, use `request_human_handoff` and resume or cancel it explicitly.
+
+## Bun runtime and the Node browser-attach bridge
+
+The Controller Gateway remains Bun-hosted. For `browserMode=attach_preferred`, page actions are executed by a short-lived, bounded Node child because Playwright CDP WebSocket attachment is not reliable in the supported Bun runtime and native attach must share the same authorized adapter path. The bridge does not create a second Browser implementation: it serializes the already-authorized plugin action over stdin and invokes the same Browser adapter under Node.
+
+The child is started directly without a shell. The CDP endpoint remains loopback-only, request and response payloads are bounded, execution has a bounded timeout, and credentials are never placed in argv. Cookies, storage state, authorization headers, and page secrets are not returned by the bridge protocol. The child disconnects from CDP or releases the Apple Events operation without closing the user's Chrome or Vivaldi instance.
+
+`managed_persistent` and `isolated` continue to run directly in the Controller runtime. Configuration, session listing and cleanup, and human-handoff lifecycle actions also remain local. Set `FORGE_NODE_EXECUTABLE` only to an explicitly trusted executable; an invalid configured path fails closed.
+
+A safe live proof against an already running loopback Chrome instance is available with:
+
+```bash
+bun scripts/smoke-browser-cdp-bridge.ts http://127.0.0.1:9222
+```
+
+The smoke reuses an existing HTTP(S) tab, repeats the same session action, verifies that the target count does not increase, and confirms that Chrome remains reachable after the Node child disconnects. It does not read cookies or storage state and does not print the page title or full URL.
+
+Immutable Forge whole-Runtime releases include a dedicated `browser-node-bridge-host.js` bundle built for Node. The Browser adapter resolves that sibling entrypoint when running from a release and falls back to the source TypeScript host only in a source checkout. Release verification treats the bridge host as a required, hashed executable.

package/docs/operations/controller-desktop-plugin.md

@@ -0,0 +1,112 @@
+# Controller Desktop Plugin
+
+The `desktop` plugin is a bundled first-party Forge capability for bounded
+macOS desktop observation and application launch. It is not downloaded from a
+marketplace and it does not require a user-configured socket, executable path, or
+registration descriptor.
+
+## Architecture
+
+```text
+ChatGPT / CLI / Local UI
+  -> list_plugins / get_plugin / plugin_action_execute
+     -> existing plugin policy, schema, receipt, and audit layers
+        -> Desktop adapter (Controller process)
+           -> one-shot managed child process
+              -> JSON-lines stdio handshake and action
+                 -> bundled forge-desktop-helper.mjs
+```
+
+The Controller starts the helper on demand for one action. The child performs a
+versioned handshake, executes one bounded request, returns one structured result,
+and exits. Forge enforces request and response size limits, timeout,
+cancellation, capability negotiation, bounded diagnostics, and process cleanup.
+The helper is launched directly without a shell.
+
+This initial implementation deliberately does not provide:
+
+- plugin search, download, installation, or a marketplace;
+- arbitrary commands or user-configured helper paths;
+- sockets, background registration files, or a second plugin registry;
+- screen capture, clicks, coordinates, keyboard input, or text entry;
+- dynamic MCP tool loading.
+
+The existing static MCP tools remain the public entry point, while action schemas,
+permissions, lifecycle, health, receipts, and audit events remain authoritative in
+the existing plugin runtime.
+
+## Actions
+
+| Action | Effect | Policy |
+| --- | --- | --- |
+| `configure` | Enable or disable the bundled Desktop plugin. | Authorization required. |
+| `status` | Run a live helper handshake and return bounded readiness diagnostics. | Read-only. |
+| `observe` | Read the frontmost macOS application through `NSWorkspace`; no screen pixels are captured. | Read-only. |
+| `open_application` | Open one app by exact `app_name` or `bundle_id`. | Authorization required. |
+
+`open_application` accepts exactly one selector. It invokes `/usr/bin/open` with an
+argv array and never interpolates a shell command.
+
+## Enable on this Mac
+
+Use the controller-scoped plugin action without a repository id:
+
+```json
+{
+  "plugin_id": "desktop",
+  "action_id": "configure",
+  "request_id": "desktop-enable-1",
+  "confirm_authorization": true,
+  "arguments": {
+    "enabled": true
+  }
+}
+```
+
+Then call `get_plugin` for `desktop`, followed by `status` and `observe`.
+No ChatGPT reconnect is required because Forge reuses the existing
+`list_plugins`, `get_plugin`, and `plugin_action_execute` tool schemas. Loading a
+new Runtime revision may require the external lifecycle owner to restart the
+existing single Forge Runtime; it must not create a second Runtime or rollout slot.
+
+Configuration authority is stored under:
+
+```text
+<controller-home>/system/desktop/config.json
+```
+
+The derived manifest and registry remain Controller projections. The helper path
+is resolved from the active Forge installation and is not returned as
+user-facing configuration.
+
+## Permissions
+
+The current version does not request Screen Recording permission because it does
+not capture screenshots. Read-only observation uses AppKit `NSWorkspace` through
+the system JavaScript bridge and does not intentionally trigger Accessibility
+consent prompts. Health reports Accessibility as `not_probed` rather than claiming
+permission that has not been verified.
+
+Future click, keyboard, screenshot, or accessibility-tree actions must be added as
+separate capabilities with explicit permission probes, stronger policy, redaction,
+and fault-injection coverage. They must not be inferred from this initial plugin.
+
+## Failure behavior
+
+The plugin fails closed when:
+
+- it is disabled;
+- the platform is not macOS;
+- the bundled helper is missing;
+- the helper handshake or capability set is incompatible;
+- a response is malformed or exceeds the output bound;
+- the helper crashes, times out, or is cancelled;
+- `open_application` receives zero or multiple selectors.
+
+A helper failure is surfaced as a structured `PLUGIN_MANAGED_PROCESS_*` or
+`PLUGIN_DESKTOP_*` error through the existing plugin receipt and audit path.
+
+
+## Immutable release packaging
+
+Whole-Runtime releases include `forge-desktop-helper.mjs` as a required, hashed sibling artifact. The Desktop adapter resolves it from the validated active Runtime release identity, then uses argv/source candidates only as development compatibility fallbacks. It launches the helper with the same trusted Node resolver used by the bounded Node bridge path; it does not execute the compiled Forge binary as a JavaScript interpreter. Release validation fails closed when the helper is missing or empty, and plugin health reports helper and trusted-runtime availability without returning either local path.

package/docs/operations/controller-performance-and-502.md

@@ -0,0 +1,126 @@
+# Controller Performance and 502 Troubleshooting
+
+This guide covers slow MCP calls, repeated reconnects, proxy `502` responses and Local Controller UI stalls.
+
+## What a 502 Means
+
+A `502` is normally emitted by the HTTPS tunnel or reverse proxy when it cannot obtain a valid response from the local MCP process. It is not proof that an accepted durable Job failed. Check the Job or Run record before retrying a write operation.
+
+## Runtime Protections
+
+The MCP HTTP runtime now uses:
+
+- one shared Controller context across sessions;
+- one global pool of at most 64 retained MCP sessions across all three HTTP paths;
+- 15-minute idle expiry, a 30-minute SSE lease and a two-hour absolute session lifetime;
+- DELETE cleanup and same-client reconnect supersession;
+- oldest-safe stream-only eviction under capacity pressure, while active POST work remains protected;
+- at most 8 simultaneous session initializations;
+- at most 4 active POST requests per session and 32 globally;
+- `429`/`503` overload responses with `Retry-After`;
+- a 1 MB MCP request-body limit;
+- 65-second keep-alive and 70-second header timeout;
+- periodic transport cleanup during runtime and full cleanup on shutdown;
+- one in-process Gateway/MCP transport owned by the canonical Forge Runtime, with no Stable Ingress child or component lifecycle supervisor.
+
+These limits prevent reconnect storms and long-running clients from causing unbounded memory, file scanning or open-transport growth.
+
+## Health Check
+
+Call `GET /health` on the local MCP endpoint. The response includes:
+
+- tool-surface identity and schema version;
+- active and maximum session counts;
+- initializing, active POST and active SSE stream counts;
+- available capacity, utilization, evictable/protected counts and oldest stream/POST ages;
+- close-reason counters for DELETE, supersession, lease/lifetime expiry and capacity eviction;
+- overload rejection count;
+- authentication configuration status.
+
+A growing `rejectedOverload` value with no matching capacity-eviction or close activity means clients are submitting protected work faster than the Controller can accept it. A pool full of stream-only sessions should now self-recover. Retrying with backoff is preferable to increasing every limit.
+
+Call `GET /ready` separately. A 503 from `/ready` with `/health` still returning 200 means the Runtime is live but cannot safely admit another initialize. `sessionCapacity.recoveryRecommended=false` preserves active work and waits; `true` is evidence for standalone Recovery's bounded whole-Runtime restart policy after the configured stall limit.
+
+## Diagnostic Order
+
+1. Confirm the local process answers `/health` directly on `127.0.0.1`.
+2. Confirm the public tunnel points to the current local port and protocol.
+3. Compare tool-surface headers with the expected Controller profile.
+4. Inspect active Jobs and Runs instead of repeating a potentially accepted mutation.
+5. Check whether a heavy named check or repository command is already running.
+6. Compare `sessions.active`, `capacityAvailable`, `evictable`, `protected`, `oldestStreamAgeMs` and close counters. A full stream-only pool without eviction indicates a regression.
+7. Restart only after `/ready` recommends bounded recovery or liveness fails, and only after durable state has been inspected; do not delete `.ai/harness` to recover from a connection problem.
+
+## Slow Local UI
+
+The dashboard uses one shared state poller regardless of browser-tab count. Snapshot requests are reused for a short window, and historical Agent Jobs/Edit Sessions are limited before their JSON files are parsed. If the UI remains slow, inspect exceptionally large Issue files or unbounded event logs rather than deleting workflow state.
+
+## Compact Status and Fast-Path Responses
+
+Default MCP tool responses stay compact so clients avoid nested
+controller / repository / runtime dumps:
+
+| Surface | Default budget | Detail |
+| --- | --- | --- |
+| `repository_command_execute` `process_direct` success | < 8 KB | one `stdout`/`stderr` pair; no nested `process` dump |
+| `process_direct` failure | < 16 KB | error code, retryable, exitCode, bounded stderr, processId |
+| `local_bridge_status` summary | < 16 KB | mode, endpoint, health, job counts; no runtimeStorage/bindings |
+| `get_job` summary | < 16 KB | pass `detail_level=full` for full job |
+| Artifact ref | < 4 KB | use `get_artifact` for body |
+| `rh_status` summary | < 32 KB | pass `detail_level=detail` for expanded |
+
+Pass `detail_level=detail` (or `detail=true`) when full routing, process
+metadata, recentJobs, or owner evidence is required.
+
+### Local Bridge endpoint
+
+Do not infer a Local Bridge endpoint from retired slot conventions:
+
+- Root template default Local Controller port is **8766**.
+- Forge has no blue/green inactive slot or `+10` alternate Runtime port.
+- The authoritative endpoint comes from Controller Home configuration and the current Runtime projection (`localController.endpoint` / `port`), not from hardcoding.
+
+Status model fields:
+
+- `mode`: `standalone` | `embedded` | `disabled` | `remote` | `unknown`
+- `processRunning`, `endpointConfigured`, `endpointReachable`
+- `expectedSurface`, `requiredForReadiness`
+
+Rules:
+
+- `mode=embedded` does not invent a legacy standalone `8766` probe target.
+- `mode=disabled` with `requiredForReadiness=false` does not emit
+  misleading `LOCAL_BRIDGE_ENDPOINT_UNAVAILABLE` as a readiness blocker.
+- Standalone required endpoints still fail closed when unreachable.
+- Historical `recentJobs` failures are operational stats, not current
+  active readiness blockers.
+
+### Completion target defaultBranch cache
+
+`resolveCompletionTargetBranch` caches registry `defaultBranch` using:
+
+1. **Registry mtime** — any change to `repositories.json` invalidates
+   immediately.
+2. **30 second TTL** — when mtime is unchanged, a change that is not
+   reflected in the registry file may take up to 30 seconds to become
+   visible.
+
+Documented operator expectation:
+
+> registry mtime 变化时立即失效；未检测到 mtime 变化时，defaultBranch 变更最多存在 30 秒可见延迟。
+
+Different repository roots never share a cache entry. When the registry
+is unavailable, Git discovery (`origin/HEAD`, `main`/`master`, current
+branch) is used.
+
+## Safe Cleanup
+
+Safe source-distribution exclusions:
+
+- `node_modules/`;
+- `.git/` when producing a portable source archive;
+- `.codegraph/`;
+- `.ai/` runtime state in a clean distribution archive;
+- `_ops/`, coverage, logs and temporary package files.
+
+Do not remove source, tests, architecture documents, task history or workflow templates merely to reduce archive size.