Accumulated fixes and improvements

.augment/rules/00-overview.md

@@ -40,7 +40,8 @@ internal/processors/  → Command processors (pre/post processing via external c
 internal/runner/      → Restricted runner, sandbox execution (go-restricted-runner)
 internal/secrets/     → Secure credential storage (Keychain on macOS)
 internal/session/     → Session persistence (Store/Recorder/Player/Lock/Queue/Flags)
-internal/web/         → Web interface server (HTTP, WebSocket, MarkdownBuffer)
+internal/conversation/→ Runtime conversation domain: BackgroundSession, SessionManager, QueueTitleWorker, streaming buffers, domain interfaces (never imports internal/web)
+internal/web/         → HTTP/WebSocket delivery + infrastructure layer; wires and serves the conversation domain (depends on internal/conversation)
 web/static/           → Frontend (Preact/HTM)
   ├── components/     → UI components (ChatInput, QueueDropdown, Message, etc.)
   ├── hooks/          → Custom hooks (useWebSocket, useSwipeNavigation, useResizeHandle)

.augment/rules/01-go-conventions.md

@@ -13,55 +13,31 @@ keywords:
 
 ## Callback Patterns
 
-### Consistent Parameter Ordering
-
-When callbacks need ordering/tracking info, put it first:
-
+Ordering/tracking info first:
 ```go
 OnAgentMessage func(seq int64, html string)
 OnToolCall     func(seq int64, id, title, status string)
 ```
 
-### Passing Data Through Buffers
-
-When buffering content that needs metadata (like seq), track it in the buffer:
-
+For buffered content with metadata, track in buffer:
 ```go
 type Buffer struct {
     content    strings.Builder
     pendingSeq int64  // Metadata from first write
 }
-
-func (b *Buffer) Write(seq int64, data string) {
-    if b.content.Len() == 0 {
-        b.pendingSeq = seq  // First write's metadata wins
-    }
-    b.content.WriteString(data)
-}
-
 func (b *Buffer) Flush() {
-    seq := b.pendingSeq  // Capture before reset
+    seq := b.pendingSeq
     b.pendingSeq = 0
     b.onFlush(seq, b.content.String())
 }
 ```
 
 ## Interface-Based Decoupling
 
-Define interface where it's USED, not where it's implemented:
-
+Define interface where it's USED:
 ```go
-type SeqProvider interface {
-    GetNextSeq() int64
-}
-
-type WebClient struct {
-    seqProvider SeqProvider
-}
-
-func (bs *BackgroundSession) GetNextSeq() int64 {
-    return bs.getNextSeq()
-}
+type SeqProvider interface { GetNextSeq() int64 }
+type WebClient struct { seqProvider SeqProvider }
 ```
 
 ## Deadlock Prevention
@@ -76,6 +52,35 @@ r.mu.Lock(); defer r.mu.Unlock(); r.recordEvent(...)
 r.mu.Lock(); defer r.mu.Unlock(); r.store.AppendEvent(...)
 ```
 
+## Bounded Deadline Context in Retry Loops
+
+When a retry loop has no parent deadline (deadline-less or very generous context), each per-attempt timeout consumes wall-clock time independently, burning all attempts even on hung transport.
+
+**Pattern** (mitto-8d7): Derive a `budgetCtx` that caps the *entire sequence*:
+
+```go
+const totalBudget = 60 * time.Second
+
+budgetCtx := ctx
+if dl, ok := ctx.Deadline(); !ok || time.Until(dl) > totalBudget {
+    var budgetCancel context.CancelFunc
+    budgetCtx, budgetCancel = context.WithTimeout(ctx, totalBudget)
+    defer budgetCancel()
+}
+
+// Use budgetCtx inside the loop (never extend caller's deadline)
+for attempt := 1; attempt <= maxAttempts; attempt++ {
+    if budgetCtx.Err() != nil {
+        return nil, fmt.Errorf("context cancelled before attempt %d", attempt)
+    }
+    attemptCtx, cancel := context.WithTimeout(budgetCtx, perAttemptTimeout)
+    // ... attempt logic ...
+    cancel()
+}
+```
+
+**Key principle**: Only *tighten* deadlines, never extend. `shouldFailFastCreateAttempt` bails when remaining budget < per-attempt timeout.
+
 ## 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.

.augment/rules/02-session.md

@@ -69,6 +69,27 @@ func (bs *BackgroundSession) onAgentMessage(seq int64, html string) {
 }
 ```
 
+### Event.Meta: Generic Metadata Bag
+
+Attach optional metadata to events using `RecordOption` during persistence:
+
+```go
+// Persist with metadata
+recorder.RecordEventWithSeq(event,
+    session.WithMeta(session.EventMeta{
+        WorkingDir: "/path/to/dir",
+        TaskID:     "task-123",
+    }),
+)
+```
+
+**Key patterns**:
+- `Event.Meta` is a generic map (`map[string]interface{}`), size-capped at 64 KB
+- Metadata is **not persisted to events.jsonl** — stored separately in `event_meta.jsonl`
+- On event read, metadata is attached if a corresponding entry exists
+- Use `WithMeta()` `RecordOption` to inject metadata during `RecordEventWithSeq()`
+- Observers notified via `EventMetaObserver` interface (see `11-web-backend-sequences.md`)
+
 ### MaxSeq Tracking
 
 The `Metadata.MaxSeq` field tracks the highest persisted sequence number. `ACPStartFailureCount` persists cold-start failure state across app restarts — `session_manager.go` increments it on exhausted retries and auto-archives when it reaches 3:
@@ -98,26 +119,16 @@ lock.SetWaitingPermission("File write")  // During permission request
 
 ## Periodic Prompts (PeriodicStore)
 
-Stored in `periodic.json` per session. API: `GET/PUT/PATCH/DELETE /api/sessions/{id}/periodic`, `POST /api/sessions/{id}/periodic/run-now`.
-
-```go
-ps := store.Periodic(sessionID)
-ps.Set(&session.PeriodicPrompt{Prompt: "...", Frequency: ..., Enabled: true})
-ps.Update(prompt, promptName, frequency, enabled, freshContext, maxIterations)  // partial update (pointer args, nil = no-op)
-ps.RecordSent()                         // increments iteration_count + updates last_sent_at + next_scheduled_at
-ps.TriggerNow(sessionID, resetTimer)    // immediate delivery via periodicRunner
-```
+Stored in `periodic.json`. Only top-level sessions may have periodic prompts (child → 400).
 
-**Max iterations / auto-stop** (`PeriodicPrompt` fields):
-- `MaxIterations` (json `max_iterations`, 0/absent = unlimited) — per-conversation cap on scheduled runs.
-- `IterationCount` (json `iteration_count`) — runs delivered so far; incremented **only** by `RecordSent` (never by `Update`/`Set`, which preserve it).
-- `ReachedMaxIterations()` → true when `MaxIterations > 0 && IterationCount >= MaxIterations`.
-- **Auto-stop**: in `periodic_runner.go` `deliverPrompt`'s `OnComplete`, after `RecordSent` the runner compares `IterationCount` against `config.EffectiveMaxPeriodicIterations(promptMax, configMax)` (smallest positive of prompt cap, config `max_periodic_iterations` default 100, hardcoded `GlobalMaxPeriodicIterations`=1000). When reached it **disables** the periodic (`Update(enabled=false)`) — it is **not** archived/deleted — and broadcasts via the `onPeriodicAutoStopped` callback.
+**Key fields**:
+- `PromptName` — references workspace prompt by name (resolved at send time via cache)
+- `MaxIterations` — cap on runs (0 = unlimited). Auto-disables when reached.
+- `Trigger` — `schedule` (default) or `onCompletion` (event-driven)
+- `DelaySeconds` — wait after agent idle before firing (onCompletion only)
+- `MaxDurationSeconds` — wall-clock cap since first run
 
-**Key rules**:
-- Only top-level/parent sessions may have periodic prompts (child sessions return 400)
-- `PromptName` references a named workspace prompt by name instead of embedding full text. `Validate()` accepts empty `Prompt` when `PromptName` is set. The periodic runner resolves the name to text at send time via the prompts cache.
-- **Caller update required**: Changing `PeriodicStore.Update()` signature requires updating **both** `internal/web/session_periodic_api.go` (PATCH handler) AND `internal/mcpserver/server.go` (MCP tool handler) — both call `Update()`.
+**Critical**: Changing `PeriodicStore.Update()` signature requires updating BOTH `session_periodic_api.go` (PATCH handler) AND `mcpserver/server.go` (MCP tool) — both call `Update()`.
 
 ## Auxiliary Package
 

.augment/rules/03-cli-acp.md

@@ -18,67 +18,26 @@ keywords:
 
 ## CLI Patterns
 
-### Cobra Command Structure
+Multi-workspace: `mitto web --dir auggie:/path/to/project1 --dir claude-code:/path/to/project2`
 
-```go
-var cliCmd = &cobra.Command{
-    Use:   "cli",
-    Short: "One-line description",
-    RunE:  runCLI,
-}
-```
-
-### User Feedback
-
-```go
-fmt.Printf("🚀 Starting ACP server: %s\n", server.Name)
-fmt.Printf("✅ Connected (protocol v%v)\n", version)
-```
-
-### Multi-Workspace CLI Usage
-
-```bash
-mitto web --dir /path/to/project1 --dir /path/to/project2
-mitto web --dir auggie:/path/to/project1 --dir claude-code:/path/to/project2
-```
-
-### `--host` Flag (Security-Sensitive)
-
-`mitto web --host 0.0.0.0` binds to all interfaces (needed for Docker). Default is `127.0.0.1`.
-
-**Security**: The local listener runs without authentication. When `--host` is not a loopback address, a runtime warning is printed. Never expose to untrusted networks.
+`--host 0.0.0.0` (Docker) vs `127.0.0.1` (default). No authentication on local listener; warn if exposed.
 
 ## ACP Protocol
 
-### SDK: `github.com/coder/acp-go-sdk`
-
-- The `Client` struct implements `acp.Client` interface
-- Use `acp.ClientSideConnection` for protocol handling
-- JSON-RPC 2.0 over stdin/stdout of the agent subprocess
-
-### ContentBlock — Discriminated Union
+SDK: `github.com/coder/acp-go-sdk` over JSON-RPC 2.0 stdin/stdout.
 
+**ContentBlock** (discriminated union): Check type via nil-pointer checks, NOT `Type()`:
 ```go
-// Check type via nil pointer checks (NOT a Type() method):
-if block.Image != nil { /* block.Image.Data, block.Image.MimeType */ }
-else if block.Text != nil { /* block.Text.Text */ }
-
-// Create blocks via helpers:
-acp.TextBlock("hello")
-acp.ImageBlock(base64Data, "image/png")
+if block.Image != nil { use block.Image.Data }
+else if block.Text != nil { use block.Text.Text }
 ```
 
-**Anti-pattern**: `block.Type()`, `acp.ContentBlockTypeImage` do NOT exist.
-
-### Connection Lifecycle
-
+**Connection lifecycle**:
 ```go
-conn, err := acp.NewConnection(ctx, command, autoApprove, output, logger)
-defer conn.Close()
-
-conn.Initialize(ctx)       // Returns AgentCapabilities
-conn.NewSession(ctx, cwd)  // Returns SessionID + Modes
-conn.Prompt(ctx, message)  // Streaming response via callbacks
+conn, err := acp.NewConnection(ctx, cmd, autoApprove, output, logger)
+conn.Initialize(ctx)  // AgentCapabilities
+conn.NewSession(ctx, cwd)  // SessionID + Modes
+conn.Prompt(ctx, msg)  // Streaming via callbacks
 ```
 
 ### Agent Capabilities
@@ -88,6 +47,32 @@ caps := resp.AgentCapabilities
 bs.agentSupportsImages = caps.PromptCapabilities.Image
 ```
 
+### Error Code Extraction & Logging
+
+Wrap `*acp.RequestError` extraction in a helper for structured logging (mitto-8d7):
+
+```go
+// rpcErrorCode extracts the JSON-RPC error code from err when it (or any error it
+// wraps) is an *acp.RequestError. Used to surface a structured, queryable rpc_code
+// field in addition to the full error string.
+func rpcErrorCode(err error) (int, bool) {
+    var re *acp.RequestError
+    if errors.As(err, &re) && re != nil {
+        return re.Code, true
+    }
+    return 0, false
+}
+
+// Log both code and message:
+rpcCode, _ := rpcErrorCode(err)
+logger.Warn("NewSession failed",
+    "rpc_code", rpcCode,
+    "error", err.Error(),
+)
+```
+
+This decouples error-code queries (e.g., alerting on `-32603` internal server errors) from full error strings.
+
 ### Permission Handling
 
 ```go
@@ -104,38 +89,9 @@ resp := CancelledPermissionResponse()
 
 ## Agent Definitions
 
-Agents are defined in `config/agents/builtin/<agent>/` (shipped) or `MITTO_DIR/agents/custom/<agent>/` (user-created).
-
-### Key Types (`internal/agents/types.go`)
-
-| Type | Purpose |
-|------|---------|
-| `AgentMetadata` | Parsed from `metadata.yaml` |
-| `MCPMetadata` | MCP scope capabilities (`Scopes []string`) |
-| `MCPInstallInput` | JSON input to `mcp-install.sh` (includes `Scope` field) |
-| `AgentDefinition` | Resolved agent with metadata + filesystem location |
-
-### metadata.yaml structure
-
-```yaml
-name: claude-code
-displayName: Claude Code
-acpId: claude
-mcp:
-  scopes: ["user", "project", "local"]  # supported scopes
-install:
-  method: npx
-  package: "@anthropic-ai/claude-code"
-```
-
-**MCP scope values**: `user` (global config), `project` (per-repo), `local` (local-only, not committed).
-
-### Agent Commands
-
-- `CommandMCPList` (via `mcp-list.sh`) — List MCP servers
-- `CommandMCPInstall` (via `mcp-install.sh`) — Install MCP server
-- `CommandMCPRemove` (via `mcp-remove.sh`) — Remove MCP server (scope must match metadata)
-
-### Adding Agents
+Located in `config/agents/builtin/<agent>/` (shipped) or `MITTO_DIR/agents/custom/<agent>/` (custom).
 
-Create `config/agents/builtin/<name>/metadata.yaml` + scripts (`install.sh`, `mcp-list.sh`, `mcp-install.sh`, `mcp-remove.sh`). Set `mcp.scopes` in metadata.
+**metadata.yaml**: Defines agent, MCP scopes, install method, default env/constraints/tags.
+**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).