inercia · inercia · Jul 14, 2026 · Jul 5, 2026 · Jul 5, 2026 · Jul 5, 2026
diff --git a/.augment/rules/01-go-conventions.md b/.augment/rules/01-go-conventions.md
@@ -81,6 +81,12 @@ for attempt := 1; attempt <= maxAttempts; attempt++ {
 
 **Key principle**: Only *tighten* deadlines, never extend. `shouldFailFastCreateAttempt` bails when remaining budget < per-attempt timeout.
 
+### Cross-Package Mirrored Constants Drift
+
+When a package can't import another (e.g. `internal/conversation` can't import `internal/acpproc`), it may hardcode a **local mirror** of a schedule/budget constant, flagged with a comment like `// Mirror of shared_acp_process.go set_model constants` (see `internal/conversation/constraints_test.go`'s `scheduleSum`). Changing the source constant does **not** auto-update the mirror.
+
+**Rule**: When changing a retry schedule/timeout constant, `grep` for comments referencing it (e.g. the old sum/values) across the whole module — not just the owning package — and update every mirror + stale doc comment describing the old math in the same change.
+
 ## Explicit Lock Management in Retry Loops
 
 `defer mu.Unlock()` does **not** compose safely with manual unlock + retry. If the locked variable is reassigned during retry, defer fires on the wrong object → double-unlock panic.

diff --git a/.augment/rules/02-session.md b/.augment/rules/02-session.md
@@ -130,6 +130,8 @@ Stored in `loop.json`. Only top-level sessions may have loop prompts (child →
 
 **Critical**: Changing `LoopStore.Update()` signature requires updating BOTH `session_loop_api.go` (PATCH handler) AND `mcpserver/server.go` (MCP tool) — both call `Update()`.
 
+**Un-loop/re-loop persistence symmetry**: `Detach()` saves settings to a slot and clears the active config (un-loop); `GetSaved()`/restore reads it back. A fresh loop `Set()` (not a restore) must be followed by `ClearSaved()` so a stale saved slot doesn't leak in later — required in both `session_loop_write.go` (`handleSetLoop`) and `mcpserver/server.go` (MCP create-loop path).
+
 ## Auxiliary Package
 
 The `internal/auxiliary` package provides a hidden ACP session for utility tasks. Lazy init, auto-approve permissions, file writes denied, thread-safe.

diff --git a/.augment/rules/03-cli-acp.md b/.augment/rules/03-cli-acp.md
@@ -95,3 +95,4 @@ Located in `config/agents/builtin/<agent>/` (shipped) or `MITTO_DIR/agents/custo
 **MCP scopes**: `user` (global), `project` (per-repo), `local` (uncommitted).
 **Agent defaults** (seeded at discovery): Pre-fill ACP server settings. Request-wins: user values take precedence.
 **Commands**: `mcp-list.sh`, `mcp-install.sh`, `mcp-remove.sh` (scope must match metadata).
+**stderrPatterns** (mitto-k6h): Optional per-agent regex patterns applied by the ACP stderr monitor. `crash` (union with hardcoded baseline → `onCrashDetected` bypasses SDK 60s timeout), `ignore` (suppress from debug log; buffer capture unaffected), `degraded` (plumbed only, behaviour deferred). Compiled once at process start; invalid regex is skipped with a warn (never fatal). CI guard: `make check-stderr-patterns`. Compile happens in `internal/web` (only layer with both `agents.Manager` and ACP-server mapping); `*conversation.CompiledStderrPatterns` is injected into `SharedACPProcessConfig`/`BackgroundSessionConfig` via a per-server-name resolver. See [docs/devel/acp.md § Stderr Pattern Detection](../../docs/devel/acp.md).
diff --git a/.augment/rules/07-prompts.md b/.augment/rules/07-prompts.md
@@ -163,7 +163,9 @@ Updates replicate the 5-layer REST API merge. Name slugification via `config.Slu
 
 ## enabledWhen Filtering & Preferred Models
 
-Server-side via `filterPromptsByEnabled()` / `buildPromptEnabledContext()`. Use `enabledWhen` (CEL) exclusively. Full CEL context: see `05-msghooks.md`. Useful functions: `FileExists(".git/config")`, `CommandExists("gh")`, `Tools.HasPattern("github_*")`.
+Server-side via `filterPromptsByEnabled()` / `buildPromptEnabledContext()`. Use `enabledWhen` (CEL) exclusively. Full CEL context: see `05-msghooks.md`. Useful functions: `FileExists(".git/config")`, `CommandExists("gh")`, `Tools.HasPattern("github_*")`, `BeadsCount("label", "open,in_progress")` / `HasBeads("label", "open,in_progress")`.
+
+**Beads gating (`BeadsCount` / `HasBeads`)**: query the workspace's `bd` (beads) DB from CEL AND Go templates. Both accept two comma-separated string args — `labels` (ALL match) and `statuses` (ANY match) — and run `bd list -l <labels> --status <statuses> --all --json` in `Workspace.Folder` (5s timeout, 5s in-memory cache). **Fail-open**: missing `bd`, non-zero exit, unparseable JSON, or timeout returns a positive sentinel (count=1 / true) so gated prompts are never wrongly hidden; a legitimate `[]` returns 0/false. Always short-circuit with cheap gates first so `bd` isn't exec'd when there's no DB: `CommandExists("bd") && DirExists(".beads") && HasBeads("support-question", "open,in_progress")`. Shared pure-Go helper (`beadsCount` in `internal/config/templatefuncs.go`) is the single source of truth for both surfaces — the CEL macros (`beadsCountMacro`, `hasBeadsMacro`) auto-inject `Workspace.Folder`.
 
 **Per-conversation user data (`UserData`)**: exposed as a `map[string]string` in both the template context (`{{ UserData "NAME" }}` / `{{ index .UserData "NAME" }}`) and CEL (`UserData["NAME"]` / `"NAME" in UserData`), built from the same conversation attributes that back `Session.UserDataJSON`. Wired exactly like `Args` (struct field + `cel.Variable` + `buildActivation` normalization + template func), but populated at **both** menu time (`buildPromptEnabledContext`) and send time (`buildProcessorInput`) — the parity invariant — so menu gating and body rendering agree. Use it for set-if-unset, else-do-Y flows; the opaque `UserDataJSON` blob cannot drive a per-field conditional.
 
@@ -175,7 +177,7 @@ Prompts may declare preferred model(s) for auto-selection at prompt-dispatch tim
 
 ```yaml
 preferredModels:
-  - modelName: Claude Sonnet   # matches a profile by its `name` (case-insensitive)
+  - modelName: Claude Sonnet 4 # matches a profile by its `name` (case-insensitive)
   - modelTag: Coding           # selects any profile carrying this tag (case-insensitive)
 ```
 

diff --git a/.augment/rules/08-config.md b/.augment/rules/08-config.md
@@ -79,7 +79,7 @@ Per-workspace config via RC files (`{workspace}/.mittorc` or `.mitto/mittorc[.ya
 
 ## Workspace Persistence
 
-Workspaces persisted in `workspaces.json` (except CLI `--dir`). `folders.json` (crash-safe) holds folder-level settings; metadata stays in `.mittorc` (version-controllable).
+Workspaces persisted in `workspaces.json` (except CLI `--dir`). `folders.json` (crash-safe) holds folder-level settings; metadata stays in `.mittorc` (version-controllable). Folder-level settings include a `pinned` bool (defaults `false`) that, when `true`, keeps the folder visible in the sidebar even without conversations; toggled via `GET/PUT /api/folders/pin` (`internal/web/handlers/folder_pin.go`) and projected onto workspace records by `ApplyFolderDefaults`.
 
 ## Global Settings REST API
 
@@ -101,15 +101,17 @@ Note: `/mitto/api/settings` manages global `settings.json`. For per-session feat
 models:
   - name: Claude Opus          # UI label (read-only)
     criteria: { matchMode: contains, pattern: Opus }  # Case-insensitive pattern matching
-    tags: [Smartest, Reasoning, Expensive]            # Interface-only semantic tags
+    tags: [Smartest, Reasoning, Expensive]            # Capability tags, consumed at runtime
 ```
 
 **Tag union matching** (additive): If a model name matches multiple profiles (e.g., `Claude Opus 4.5`):
 - First: Matches `Claude` profile → `[Anthropic]`
 - Then: Matches `Opus` profile → Adds `[Smartest, Reasoning, Expensive]`
 - Result: `[Anthropic, Smartest, Reasoning, Expensive]` (union)
 
-Use `matchMode: contains` for robust cross-version matching. Tags are interface-only; runtime consumption is tracked separately (see `mitto-2cc`). Shipped defaults include: Claude, Opus, Sonnet, Haiku, GPT-5, GPT-4, Gemini. Test: `TestParse_EmbeddedDefaultModelProfiles()` in `internal/config/config_test.go`.
+Use `matchMode: contains` for robust cross-version matching. Shipped defaults include: Claude, Opus, Sonnet, Haiku, GPT-5, GPT-4, Gemini. Test: `TestParse_EmbeddedDefaultModelProfiles()` in `internal/config/config_test.go`.
+
+**Canonical Go defaults (always available, not just first-run seed)**: `config.DefaultModelProfiles()` hardcodes the same 7 profiles in Go — the single source of truth, kept in sync with `config.default.yaml`'s `models:` block by `make check-model-tags`. `(*Config).EffectiveModelProfiles()` returns `settings.json`'s `Models` unioned with these defaults (user profile wins on name collision, defaults fill gaps; nil-safe). All tag/name resolution — `ModelProfileByName`, `ModelProfilesByTag`, `ResolveModelTags` — routes through `EffectiveModelProfiles()`, so a prompt's `preferredModels: {modelTag: Coding}` resolves even when `settings.json` predates or omits `models:` (previously it silently no-opped to the baseline model — this was the root cause of `preferredModels` "not working" for users with pre-existing settings). `config.CanonicalModelTags()` returns the sorted, de-duped tag set; `make check-model-tags` rejects any builtin prompt's `modelTag` that isn't in this set.
 
 ## ACP Server Constraints
 

diff --git a/.augment/rules/09-macos-app.md b/.augment/rules/09-macos-app.md
@@ -28,8 +28,11 @@ touch Mitto.app && killall Finder && killall Dock
 
 ## Environment Detection
 
+Prefer the shared `isNativeApp()` from `web/static/utils/native.js` (re-exported by `utils/index.js`) over redefining the predicate inline. Implementation: `typeof window.mittoPickFolder === "function"` — `mittoPickFolder` is the sentinel bound only by the WKWebView host. Use it to gate any UI whose action requires a bound `window.mitto*` function (e.g. the folder-header "Open ▸" submenu in `SessionList.js`).
+
 ```javascript
-const isMacApp = typeof window.mittoPickFolder === "function";
+import { isNativeApp } from "../utils/index.js";
+if (!isNativeApp()) return []; // hide native-only UI in browser context
 ```
 
 ### Bound Native Functions

diff --git a/.augment/rules/15-web-backend-session-lifecycle.md b/.augment/rules/15-web-backend-session-lifecycle.md
@@ -71,12 +71,23 @@ The GC suspends idle loop sessions whose next prompt is far away, saving ACP res
 | `inactivity`        | `ArchiveReasonInactivity`     | Auto-archive after configured inactive period|
 | `acp_start_failures`| `ArchiveReasonACPFailures`    | `ACPStartFailureCount` ≥ threshold (3)       |
 
-Broadcast in `session_archived` WebSocket message as `archive_reason` field.
+Broadcast in `session_archived` WebSocket message as `archive_reason` field. `acp_start_failures` on a loop conversation is the only reason eligible for Auto-Unarchive Recovery (below).
 
 ## Auto-Archive
 
 Config: `session.auto_archive_inactive_after: "1w"` (in `checkAutoArchive()`). Excluded: already-archived, child sessions, sessions with loop prompts (enabled or paused).
 
+## Auto-Unarchive Recovery
+
+Loop conversations auto-archived due to broken ACP (`ArchiveReasonACPFailures`) are retried automatically by `LoopRunner.checkAutoUnarchiveRecovery()`, called from `RunOnce()` right after `checkAutoArchive()`.
+
+- **Eligibility**: `meta.Archived && meta.ArchiveReason == ArchiveReasonACPFailures` + loop config exists. Excludes `Manual`/`Inactivity` and non-loop ACP-failure archives.
+- **Retry cadence**: 1h per conversation (`DefaultAutoUnarchiveRetryInterval`), anchored on `Metadata.AutoUnarchiveLastAttemptAt` else `ArchivedAt`. Retries indefinitely — the resume-failure path re-archives on continued outage, restarting cadence from the new `ArchivedAt`.
+- **Anti-storm stagger**: 10m global minimum gap (`DefaultAutoUnarchiveStaggerInterval`), tracked in-memory (`LoopRunner.lastAutoUnarchiveAttempt`, `r.mu`); each poll attempts only the most-overdue eligible session. **Never `time.Sleep`** in this path — it stalls loop delivery.
+- **On-by-default**: `autoUnarchiveEnabled=true`; `SetAutoUnarchiveRecovery(enabled, retryInterval, stagger)` — duration `<= 0` keeps current value (lets tests override one).
+- **Callback** (`onAutoUnarchive`, wired in `server.go`): mirrors manual unarchive — clear archive fields → `ResumeSession()` → broadcast → `handlers.RestoreLoopOnUnarchive()`.
+- **Cadence persistence**: `attemptAutoUnarchive()` persists `AutoUnarchiveLastAttemptAt` (outside `r.mu`) *before* the callback so it survives a crash; cleared only on `nil` return. Also cleared on any successful manual unarchive (`session_update.go`).
+
 ## ACP Process Crash Recovery
 
 `classifyACPError()` → **Permanent** (command not found, syntax error) = stop + guidance. **Transient** (network, crash) = retry with backoff.
@@ -89,6 +100,12 @@ Death detection (three layers): OS polling (~2s), `conn.Done()` EOF (~seconds),
 
 When ACP handshake times out transiently, `BackgroundSession.InitializeWithACP()` defers retry up to 3 attempts with exponential backoff. The error event is persisted in the session event log (viewable in UI). Retries happen deferred in a separate goroutine to avoid blocking session creation or WebSocket initialization. After 3 attempts, the session enters error state with guidance.
 
+## Shared Handshake Budget: Stale vs. Cold-Timeout (anti-regression)
+
+`internal/conversation/shared_session_handshaker.go` bounds concurrent `session/load` + `session/new` handshakes with **one shared deadline** to prevent stacking (`mitto-1ut`). The budget cap MUST be **released** for the `session/new` fallback when the `session/load` probe **timed out** (process genuinely cold) — otherwise `session/new` inherits only `budget − probeTimeout` (e.g. `240s − 45s = 195s`), less than a single `MCPInitTimeout` attempt (240s), guaranteeing starvation. Only cap the fallback when the probe **fast-failed** (JSON-RPC `-32602` stale). Track this via `probeTimedOut`. Test seam: `loadBlocksUntilCtxDone` in `fakeSharedProcess` (`TestHandshaker_ResumeSharedACPSession_ColdProbeTimeout_NoNewDeadline`). Pre-attempt cancellations in `acpproc/shared_acp_process.go` emit a self-diagnosing error (elapsed vs. per-attempt budget) instead of a raw deadline.
+
+**Clear persisted `acp_session_id` on load failure (`mitto-y1g`)**: In `resumeSharedACPSession`, both load-failure branches (`-32602 Session not found` **and** probe timeout) must call `hsClearPersistedACPSessionID()` before falling back to `session/new`. Otherwise the stale ID stays on disk and every subsequent cold-start / process recycle re-triggers the same doomed `session/load` — catastrophic when an always-active loop session is one of the offenders (each recycle burns the probe cap before the `session/new` fallback). Mirror `hsPersistACPSessionID`; assert both branches clear in the regression test.
+
 ## MCP Server Lifecycle
 
 | Event               | MCP Server Action          |

diff --git a/.augment/rules/20-web-frontend-core.md b/.augment/rules/20-web-frontend-core.md
@@ -45,6 +45,10 @@ App
 └── Dialogs (Settings, Workspace, Rename, Delete, etc.)
 ```
 
+### Sidebar Tree Sources
+
+`SessionList` synthesizes its folder groups from **two sources**: (a) the working directories of active + stored conversations, and (b) any configured workspace whose `folders.json` entry has `pinned: true`. This lets users keep folders visible in the sidebar even when they hold no conversations — pinned via the sidebar toolbar's `AddFolderDialog`, unpinned via the folder context menu's "Remove from sidebar" entry (both call `PUT /api/folders/pin`).
+
 ## File Structure
 
 | File                           | Purpose                                       |
@@ -58,6 +62,7 @@ App
 | `components/Icons.js`          | SVG icon components                           |
 | `components/SessionPanel.js`   | Unified side panel (Properties + User Data tabs) |
 | `components/SettingsDialog.js` | Settings modal                                |
+| `components/AddFolderDialog.js` | "Add folder to sidebar" dialog: pin existing hidden workspace or delegate to WorkspacesDialog for a new one |
 | `hooks/useWebSocket.js`        | WebSocket connection management               |
 | `hooks/useResizeHandle.js`     | Drag-to-resize with mouse and touch           |
 | `hooks/useSwipeNavigation.js`  | Mobile swipe gestures                         |

diff --git a/.augment/rules/25-web-frontend-components.md b/.augment/rules/25-web-frontend-components.md
@@ -119,7 +119,7 @@ const { showToast, dismissToast, toasts } = useToast();
 showToast({ message: "Saved", style: "success" }); // auto-dismiss 5s
 ```
 
-Durations: info/success=5s, warning/error=10s. Max 5 simultaneous. Render via `<ToastContainer />`. Use `error` (red) for actual errors only.
+Durations: info/success=5s, warning=10s. `error` toasts NEVER auto-dismiss — they persist until the user closes them (dismiss button), so critical errors can't be missed. Max 5 simultaneous. Render via `<ToastContainer />`. Use `error` (red) for actual errors only.
 
 ## useResizeHandle / useSwipeNavigation
 

diff --git a/.augment/rules/32-testing-playwright.md b/.augment/rules/32-testing-playwright.md
@@ -123,6 +123,23 @@ In Docker, ACP connections take ~1.1s. After clicking new-session, **wait for `m
 await page.waitForFunction(() => !!localStorage.getItem("mitto_last_session_id"));
 ```
 
+## Testing Native-App-Gated UI
+
+For features gated on `isNativeApp()` (`web/static/utils/native.js`), stub the sentinel `window.mittoPickFolder` **before navigation** with `page.addInitScript` — Playwright runs in a plain browser, so `isNativeApp()` returns `false` by default.
+
+```typescript
+async function stubNativeApp(page) {
+  await page.addInitScript(() => {
+    Object.defineProperty(window, "mittoPickFolder",
+      { configurable: true, get: () => () => {}, set: () => {} });
+  });
+}
+```
+
+**Apply per-test, NOT in `beforeEach`** — move `helpers.navigateAndWait(page)` into each test so a negative test can navigate un-stubbed to assert the gated UI is absent. Cover both positive (stubbed → visible) and negative (un-stubbed → hidden) paths in the same spec. Reference: `tests/ui/specs/open-in-context-menu.spec.ts`.
+
+Same rule applies when patching backend config the frontend reads once via `fetchConfig()` on mount (e.g. `ui.mac.open_in` targets): PATCH it in `beforeEach` **before** the first `navigateAndWait`, otherwise the mount reads stale defaults.
+
 ## Browser-Specific Issues
 
 | Issue | Browser | Cause |