@vellumai/assistant 0.4.55 → 0.4.57

package/docs/architecture/integrations.md

@@ -430,7 +430,7 @@ sequenceDiagram
 | `ask_missing_credential` | A known template pattern matches but no credential is bound to the session |
 | `ask_unauthenticated`    | Completely unknown host — prompt for unauthenticated access                |
 
-**Trust rule persistence**: The `createProxyApprovalCallback` in `session-tool-setup.ts` is wired into the session startup path and routes policy "ask" decisions through the existing `PermissionPrompter` UI. Trust rules use the `network_request` tool name (not `proxy:*`) with URL-based scope patterns (e.g., `https://api.example.com/*`), aligning with the `buildCommandCandidates()` allowlist generation in `checker.ts`.
+**Trust rule persistence**: The `createProxyApprovalCallback` in `conversation-tool-setup.ts` is wired into the session startup path and routes policy "ask" decisions through the existing `PermissionPrompter` UI. Trust rules use the `network_request` tool name (not `proxy:*`) with URL-based scope patterns (e.g., `https://api.example.com/*`), aligning with the `buildCommandCandidates()` allowlist generation in `checker.ts`.
 
 **Proxied bash permission restriction**: The `ToolExecutor` sets `persistentDecisionsAllowed = false` when the bash tool is invoked with `network_mode: 'proxied'`. This prevents users from saving permanent trust rules for proxied bash commands, since the proxy session's credential scope can change between invocations.
 
@@ -499,7 +499,7 @@ The proxy subsystem intercepts outbound HTTPS requests and injects stored creden
 | `assistant/src/tools/network/script-proxy/logging.ts`         | Log sanitization (header/URL redaction) and safe decision trace builders for policy and credential resolution           |
 | `assistant/src/tools/network/script-proxy/types.ts`           | Type definitions — session, policy decisions, approval callback                                                         |
 | `assistant/src/tools/executor.ts`                             | `persistentDecisionsAllowed` gate — disables trust rule saving for proxied bash                                         |
-| `assistant/src/daemon/session-tool-setup.ts`                  | `createProxyApprovalCallback` — wired into session startup, uses `network_request` tool name with URL-based trust rules |
+| `assistant/src/daemon/conversation-tool-setup.ts`             | `createProxyApprovalCallback` — wired into session startup, uses `network_request` tool name with URL-based trust rules |
 | `assistant/src/permissions/checker.ts`                        | `network_request` trust rule matching and risk classification (Medium)                                                  |
 
 ### Runtime Wiring Summary
@@ -508,13 +508,13 @@ The proxy subsystem is fully wired, including credential injection. The session
 
 - **MITM handler config**: `mitmHandler` is configured with the local CA path and a `rewriteCallback` that performs per-credential specificity-based template selection — for each credential it picks the most specific matching header template (exact > wildcard), blocks on same-credential equal-specificity ties or cross-credential ambiguity, and for the winning `header`-type template resolves the secret from secure storage and sets the outbound header. Wildcard patterns (`*.fal.run`) match the bare apex domain (`fal.run`) via apex-inclusive matching.
 - **Policy callback**: `evaluateRequestWithApproval()` is called via the `policyCallback`; for `'matched'` decisions it injects credential headers (reading the secret value at injection time), while `'ambiguous'` decisions are blocked and `'ask_*'` decisions route through the approval callback
-- **Approval callback**: `createProxyApprovalCallback()` from `session-tool-setup.ts` routes approval prompts through the `PermissionPrompter`, using the `network_request` tool name with URL-based trust rules
+- **Approval callback**: `createProxyApprovalCallback()` from `conversation-tool-setup.ts` routes approval prompts through the `PermissionPrompter`, using the `network_request` tool name with URL-based trust rules
 - **networkMode plumbing**: `shell.ts` passes `{ networkMode }` to `wrapCommand()`, which forwards it to the native backend
 - **Session lifecycle**: `createSession` / `startSession` / `stopSession` with idle timeout and per-conversation limits
 
 ---
 
-## Asset Search and Materialize — Cross-Thread Media Reuse
+## Asset Search and Materialize — Cross-Conversation Media Reuse
 
 The `asset_search` and `asset_materialize` tools enable the assistant to discover and use previously uploaded media assets (images, documents, audio) across conversations. Assets are stored as base64-encoded blobs in the `attachments` table and linked to messages via the `message_attachments` join table.
 
@@ -533,7 +533,7 @@ sequenceDiagram
     Search->>DB: query attachments (filters)
     DB-->>Search: matching rows (metadata only, no base64)
     Search->>Visibility: filterVisibleAttachments(results, currentContext)
-    Note over Visibility: Private-thread attachments filtered out<br/>unless viewer is in the same thread
+    Note over Visibility: Private-conversation attachments filtered out<br/>unless viewer is in the same conversation
     Visibility-->>Search: visible results
     Search-->>Model: metadata list (IDs, filenames, types, sizes)
 
@@ -542,24 +542,24 @@ sequenceDiagram
     Materialize->>DB: load attachment (including base64 data)
     Materialize->>Visibility: isAttachmentVisible(attachmentCtx, currentCtx)
     Note over Visibility: Second visibility check at materialize time<br/>prevents TOCTOU between search and materialize
-    Materialize->>Materialize: size check (max 50 MB)
+    Materialize->>Materialize: size check (max 100 MB)
     Materialize->>Sandbox: write decoded bytes to destination
     Materialize-->>Model: "Materialized 'photo.jpg' to /workspace/media/photo.jpg"
 ```
 
-### Private Thread Visibility Gate
+### Private Conversation Visibility Gate
 
-Attachments from private threads are only visible to the same private thread. Standard-thread attachments are visible everywhere. The policy is enforced at both the search and materialize stages to prevent cross-thread data leakage.
+Attachments from private conversations are only visible to the same private conversation. Standard-conversation attachments are visible everywhere. The policy is enforced at both the search and materialize stages to prevent cross-conversation data leakage.
 
 ```mermaid
 graph TB
     subgraph "Visibility Rules"
-        ATT_STD["Attachment from<br/>standard thread"]
-        ATT_PVT["Attachment from<br/>private thread"]
+        ATT_STD["Attachment from<br/>standard conversation"]
+        ATT_PVT["Attachment from<br/>private conversation"]
 
-        VIEWER_ANY["Any thread<br/>(standard or private)"]
-        VIEWER_SAME["Same private thread<br/>(matching conversationId)"]
-        VIEWER_OTHER["Different private thread<br/>or standard thread"]
+        VIEWER_ANY["Any conversation<br/>(standard or private)"]
+        VIEWER_SAME["Same private conversation<br/>(matching conversationId)"]
+        VIEWER_OTHER["Different private conversation<br/>or standard conversation"]
     end
 
     ATT_STD -->|"always visible"| VIEWER_ANY
@@ -567,11 +567,11 @@ graph TB
     ATT_PVT -->|"hidden"| VIEWER_OTHER
 ```
 
-**Source conversation lookup**: The `getAttachmentSourceConversations()` function traces an attachment's lineage through `message_attachments` -> `messages` -> `conversations` to determine which threads it belongs to and whether any of them are private.
+**Source conversation lookup**: The `getAttachmentSourceConversations()` function traces an attachment's lineage through `message_attachments` -> `messages` -> `conversations` to determine which conversations it belongs to and whether any of them are private.
 
-**Mixed-source attachments**: If an attachment is linked to messages in both standard and private conversations (e.g., the user shared the same file in two threads), the attachment is treated as globally visible because at least one source is non-private.
+**Mixed-source attachments**: If an attachment is linked to messages in both standard and private conversations (e.g., the user shared the same file in two conversations), the attachment is treated as globally visible because at least one source is non-private.
 
-**Orphan attachments**: Attachments with no message linkage (orphans) are treated as universally visible rather than hidden, since they have no private-thread provenance.
+**Orphan attachments**: Attachments with no message linkage (orphans) are treated as universally visible rather than hidden, since they have no private-conversation provenance.
 
 ### Search Capabilities
 
@@ -586,18 +586,18 @@ graph TB
 ### Materialize Safeguards
 
 - **Sandbox path enforcement**: Destination path must resolve inside the sandbox working directory
-- **Size limit**: 50 MB ceiling prevents materializing excessively large attachments
+- **Size limit**: 100 MB ceiling prevents materializing excessively large attachments
 - **Double visibility check**: Both `asset_search` and `asset_materialize` independently verify visibility, preventing TOCTOU races between search and use
 - **Risk level**: Both tools are `RiskLevel.Low` since they read existing data and write only within the sandbox
 
 ### Key Source Files
 
-| File                                              | Role                                                                                    |
-| ------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `assistant/src/tools/assets/search.ts`            | `asset_search` tool — cross-thread attachment metadata search with visibility filtering |
-| `assistant/src/tools/assets/materialize.ts`       | `asset_materialize` tool — decode and write attachment to sandbox path                  |
-| `assistant/src/daemon/media-visibility-policy.ts` | Pure policy module — `isAttachmentVisible()`, `filterVisibleAttachments()`              |
-| `assistant/src/memory/schema.ts`                  | `attachments` and `message_attachments` table schemas                                   |
-| `assistant/src/memory/conversation-crud.ts`       | `getConversationThreadType()` — thread type lookup for visibility context               |
+| File                                              | Role                                                                                          |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `assistant/src/tools/assets/search.ts`            | `asset_search` tool — cross-conversation attachment metadata search with visibility filtering |
+| `assistant/src/tools/assets/materialize.ts`       | `asset_materialize` tool — decode and write attachment to sandbox path                        |
+| `assistant/src/daemon/media-visibility-policy.ts` | Pure policy module — `isAttachmentVisible()`, `filterVisibleAttachments()`                    |
+| `assistant/src/memory/schema.ts`                  | `attachments` and `message_attachments` table schemas                                         |
+| `assistant/src/memory/conversation-crud.ts`       | `getConversationType()` — conversation type lookup for visibility context                     |
 
 ---

package/docs/architecture/memory.md

@@ -51,7 +51,7 @@ graph TB
         HYBRID["Hybrid Search<br/>dense + sparse RRF on Qdrant"]
         RECENCY["Recency Search<br/>conversation-scoped, DB only"]
         MERGE["Merge + Deduplicate<br/>weighted score combination"]
-        SCOPE["Scope Filter<br/>scope_id filtering<br/>(strict | global_fallback)<br/>Private threads: own scope + 'default'"]
+        SCOPE["Scope Filter<br/>scope_id filtering<br/>(strict | global_fallback)<br/>Private conversations: own scope + 'default'"]
         TIER["Tier Classification<br/>score > 0.8 → tier 1<br/>score > 0.6 → tier 2<br/>below → dropped"]
         STALE["Staleness Computation<br/>kind-specific lifetimes<br/>+ reinforcement from<br/>source conversation count"]
         DEMOTE["Stale Demotion<br/>very_stale tier 1 → tier 2"]
@@ -75,7 +75,7 @@ graph TB
         OVF_T4["Tier 4: Injection downgrade<br/>→ minimal mode"]
         OVF_POLICY["Overflow policy resolver<br/>auto_compress / request_approval / fail_gracefully"]
         OVF_APPROVE["Approval gate<br/>PermissionPrompter"]
-        OVF_DENY["Graceful deny message<br/>(not session_error)"]
+        OVF_DENY["Graceful deny message<br/>(not conversation_error)"]
     end
 
     MSG_IN --> STORE
@@ -149,7 +149,7 @@ Normal context compaction (the "Context Window Management" subgraph above) runs
 
 When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards, `minKeepRecentUserTurns: 0` allows summarizing even the most recent history, and `targetInputTokensOverride` sets a tighter budget. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
 
-If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. In interactive sessions, the user is prompted for approval before this lossy step. If the user declines, the session emits a graceful assistant explanation message rather than a `session_error`, ending the turn cleanly. Non-interactive sessions auto-compress without prompting.
+If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. In interactive sessions, the user is prompted for approval before this lossy step. If the user declines, the session emits a graceful assistant explanation message rather than a `conversation_error`, ending the turn cleanly. Non-interactive sessions auto-compress without prompting.
 
 The key distinction: normal compaction is a cost-optimized background process that preserves conversational quality; overflow recovery is a convergence mechanism that prioritizes session survival over context richness. Both share the same summarization infrastructure but operate under different pressure thresholds and constraints.
 
@@ -250,7 +250,7 @@ The recall pipeline runs on every turn that passes the `needsMemory` gate (skips
 9. **Two-layer XML injection** (`formatting.ts`): Budget-aware rendering into four XML sections:
 
    ```xml
-   <memory_context>
+   <memory_context __injected>
 
    <user_identity>
    <!-- identity-kind tier 1 items (plain statements) -->
@@ -273,7 +273,7 @@ The recall pipeline runs on every turn that passes the `needsMemory` gate (skips
 
    Empty sections are omitted. Each section has a per-item token budget (150 tokens for tier 1, 100 for tier 2). Tier 1 sections consume budget first; tier 2 uses the remainder.
 
-10. **Injection strategy**: The rendered `<memory_context>` block is injected as a separate user + assistant acknowledgment message pair before the last user message (`injectMemoryRecallAsSeparateMessage`). This separates memory context from the user's actual query.
+10. **Injection strategy**: The rendered `<memory_context __injected>` block is prepended as a text content block to the last user message (`injectMemoryRecallAsUserBlock`), following the same pattern as workspace, temporal, and other runtime injections. Stripping is handled by the generic `stripUserTextBlocksByPrefix` mechanism matching the `<memory_context __injected>` prefix (with a backward-compat entry for the legacy `<memory_context>` prefix from older history). This avoids synthetic message pairs and preserves prompt prefix caching between turns.
 
 ### Internal-Only Trust Gating
 
@@ -283,7 +283,7 @@ Two trust gates enforce trust-class-based access control over the memory pipelin
 
 - **Write gate** (`indexer.ts`): The `extract_items` job only runs for messages from trusted actors (guardian or undefined provenance). Messages from untrusted actors (`trusted_contact`, `unknown`) are still segmented and embedded — so they appear in conversation context — but no item extraction is triggered. This prevents untrusted channels from injecting or mutating long-term memory items.
 
-- **Read gate** (`session-memory.ts`): When the current session's actor is untrusted, the memory recall pipeline returns a no-op context — no recall injection. This ensures untrusted actors cannot surface or exploit previously extracted memory.
+- **Read gate** (`conversation-memory.ts`): When the current session's actor is untrusted, the memory recall pipeline returns a no-op context — no recall injection. This ensures untrusted actors cannot surface or exploit previously extracted memory.
 
 Trust policy is **cross-channel and trust-class-based**: decisions use `trustContext.trustClass`, not the channel string. Desktop sessions default to `trustClass: 'guardian'`. External channels (Telegram, WhatsApp, phone) provide explicit trust context via the resolver. Messages without provenance metadata are treated as trusted (guardian); all new messages carry provenance.
 
@@ -310,36 +310,36 @@ When the embedding backend or Qdrant is unavailable:
 
 ---
 
-## Private Threads — Isolated Memory and Strict Side-Effect Controls
+## Private Conversations — Isolated Memory and Strict Side-Effect Controls
 
-Private threads provide per-conversation memory isolation and stricter tool execution controls. When a conversation is created with `threadType: 'private'`, the daemon assigns it a unique memory scope and enforces additional safeguards to prevent unintended side effects.
+Private conversations provide per-conversation memory isolation and stricter tool execution controls. When a conversation is created with `conversationType: 'private'`, the daemon assigns it a unique memory scope and enforces additional safeguards to prevent unintended side effects.
 
 ### Schema Columns
 
 Two columns on the `conversations` table drive the feature:
 
-| Column            | Type                               | Values                                                                   | Purpose                                                                                                                        |
-| ----------------- | ---------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| `thread_type`     | `text NOT NULL DEFAULT 'standard'` | `'standard'` or `'private'`                                              | Determines whether the conversation uses shared or isolated memory and permission policies                                     |
-| `memory_scope_id` | `text NOT NULL DEFAULT 'default'`  | `'default'` for standard threads; `'private:<uuid>'` for private threads | Scopes all memory writes (items, segments) to this namespace; embeddings are isolated indirectly via their parent item/segment |
+| Column              | Type                               | Values                                                                               | Purpose                                                                                                                        |
+| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `conversation_type` | `text NOT NULL DEFAULT 'standard'` | `'standard'` or `'private'`                                                          | Determines whether the conversation uses shared or isolated memory and permission policies                                     |
+| `memory_scope_id`   | `text NOT NULL DEFAULT 'default'`  | `'default'` for standard conversations; `'private:<uuid>'` for private conversations | Scopes all memory writes (items, segments) to this namespace; embeddings are isolated indirectly via their parent item/segment |
 
 ### Memory Isolation
 
 ```mermaid
 graph TB
-    subgraph "Standard Thread"
+    subgraph "Standard Conversation"
         STD_WRITE["Memory writes<br/>→ scope_id = 'default'"]
         STD_READ["Memory recall<br/>reads scope_id = 'default' only"]
     end
 
-    subgraph "Private Thread"
+    subgraph "Private Conversation"
         PVT_WRITE["Memory writes<br/>→ scope_id = 'private:&lt;uuid&gt;'"]
         PVT_READ["Memory recall<br/>reads scope_id = 'private:&lt;uuid&gt;'<br/>+ fallback to 'default'"]
     end
 
     subgraph "Shared Memory Pool"
-        DEFAULT_SCOPE["'default' scope<br/>(all standard thread memories)"]
-        PRIVATE_SCOPE["'private:&lt;uuid&gt;' scope<br/>(isolated to one thread)"]
+        DEFAULT_SCOPE["'default' scope<br/>(all standard conversation memories)"]
+        PRIVATE_SCOPE["'private:&lt;uuid&gt;' scope<br/>(isolated to one conversation)"]
     end
 
     STD_WRITE --> DEFAULT_SCOPE
@@ -349,53 +349,53 @@ graph TB
     PVT_READ -.->|"fallback"| DEFAULT_SCOPE
 ```
 
-**Write isolation**: All memory items and segments created during a private thread are tagged with its `memory_scope_id` (e.g. `'private:abc123'`). Embeddings are isolated indirectly — they reference scoped items/segments via `target_type`/`target_id`, so scope filtering at the item/segment level cascades to their embeddings. All scoped data is invisible to standard threads and other private threads.
+**Write isolation**: All memory items and segments created during a private conversation are tagged with its `memory_scope_id` (e.g. `'private:abc123'`). Embeddings are isolated indirectly — they reference scoped items/segments via `target_type`/`target_id`, so scope filtering at the item/segment level cascades to their embeddings. All scoped data is invisible to standard conversations and other private conversations.
 
-**Read fallback**: When recalling memories for a private thread, the retriever queries both the thread's own scope and the `'default'` scope. This ensures the assistant still has access to general knowledge (user profile, preferences, facts) learned in standard threads, while private-thread-specific memories take precedence in ranking. The fallback is implemented via `ScopePolicyOverride` with `fallbackToDefault: true`, which overrides the global scope policy on a per-call basis.
+**Read fallback**: When recalling memories for a private conversation, the retriever queries both the conversation's own scope and the `'default'` scope. This ensures the assistant still has access to general knowledge (user profile, preferences, facts) learned in standard conversations, while private-conversation-specific memories take precedence in ranking. The fallback is implemented via `ScopePolicyOverride` with `fallbackToDefault: true`, which overrides the global scope policy on a per-call basis.
 
 ### SessionMemoryPolicy
 
-The daemon derives a `SessionMemoryPolicy` from the conversation's `thread_type` and `memory_scope_id` when creating or restoring a session:
+The daemon derives a `SessionMemoryPolicy` from the conversation's `conversation_type` and `memory_scope_id` when creating or restoring a session:
 
 ```typescript
 interface SessionMemoryPolicy {
   scopeId: string; // 'default' or 'private:<uuid>'
-  includeDefaultFallback: boolean; // true for private threads
-  strictSideEffects: boolean; // true for private threads
+  includeDefaultFallback: boolean; // true for private conversations
+  strictSideEffects: boolean; // true for private conversations
 }
 ```
 
-Standard threads use `DEFAULT_MEMORY_POLICY` (`{ scopeId: 'default', includeDefaultFallback: false, strictSideEffects: false }`). Private threads set all three fields: the private scope ID, default-fallback enabled, and strict side-effect controls enabled.
+Standard conversations use `DEFAULT_MEMORY_POLICY` (`{ scopeId: 'default', includeDefaultFallback: false, strictSideEffects: false }`). Private conversations set all three fields: the private scope ID, default-fallback enabled, and strict side-effect controls enabled.
 
 ### Strict Side-Effect Prompt Gate
 
-When `strictSideEffects` is `true` (all private threads), the `ToolExecutor` promotes any `allow` permission decision to `prompt` for side-effect tools — even when a trust rule would normally auto-allow the invocation. Deny decisions are preserved unchanged; only `allow` -> `prompt` promotion occurs.
+When `strictSideEffects` is `true` (all private conversations), the `ToolExecutor` promotes any `allow` permission decision to `prompt` for side-effect tools — even when a trust rule would normally auto-allow the invocation. Deny decisions are preserved unchanged; only `allow` -> `prompt` promotion occurs.
 
 ```mermaid
 graph TB
-    TOOL["Tool invocation in<br/>private thread"] --> PERM["Normal permission check<br/>(trust rules + risk level)"]
+    TOOL["Tool invocation in<br/>private conversation"] --> PERM["Normal permission check<br/>(trust rules + risk level)"]
     PERM --> DECISION{"Decision?"}
     DECISION -->|"deny"| DENY["Blocked<br/>(unchanged)"]
     DECISION -->|"prompt"| PROMPT["Prompt user<br/>(unchanged)"]
     DECISION -->|"allow"| SIDE_CHECK{"isSideEffectTool()?"}
     SIDE_CHECK -->|"no"| ALLOW["Auto-allow<br/>(read-only tools pass)"]
-    SIDE_CHECK -->|"yes"| FORCE_PROMPT["Promote to prompt<br/>'Private thread: side-effect<br/>tools require explicit approval'"]
+    SIDE_CHECK -->|"yes"| FORCE_PROMPT["Promote to prompt<br/>'Private conversation: side-effect<br/>tools require explicit approval'"]
 ```
 
-This ensures that file writes, bash commands, host operations, and other mutating tools always require explicit user confirmation in private threads, providing an additional safety layer for sensitive conversations.
+This ensures that file writes, bash commands, host operations, and other mutating tools always require explicit user confirmation in private conversations, providing an additional safety layer for sensitive conversations.
 
 ### Key Source Files
 
-| File                                         | Role                                                                                       |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `assistant/src/memory/schema.ts`             | `conversations` table: `threadType` and `memoryScopeId` column definitions                 |
-| `assistant/src/daemon/session.ts`            | `SessionMemoryPolicy` interface and `DEFAULT_MEMORY_POLICY` constant                       |
-| `assistant/src/daemon/server.ts`             | `deriveMemoryPolicy()` — maps thread type to memory policy                                 |
-| `assistant/src/daemon/session-tool-setup.ts` | Propagates `memoryPolicy.strictSideEffects` as `forcePromptSideEffects` into `ToolContext` |
-| `assistant/src/tools/executor.ts`            | `forcePromptSideEffects` gate — promotes allow to prompt for side-effect tools             |
-| `assistant/src/memory/search/types.ts`       | `ScopePolicyOverride` interface for per-call scope control                                 |
-| `assistant/src/memory/retriever.ts`          | `buildScopeFilter()` — builds scope ID list from override or global config                 |
-| `assistant/src/daemon/session-memory.ts`     | Wires `scopeId` and `includeDefaultFallback` into recall                                   |
+| File                                              | Role                                                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `assistant/src/memory/schema.ts`                  | `conversations` table: `conversationType` and `memoryScopeId` column definitions           |
+| `assistant/src/daemon/conversation.ts`            | `SessionMemoryPolicy` interface and `DEFAULT_MEMORY_POLICY` constant                       |
+| `assistant/src/daemon/server.ts`                  | `deriveMemoryPolicy()` — maps conversation type to memory policy                           |
+| `assistant/src/daemon/conversation-tool-setup.ts` | Propagates `memoryPolicy.strictSideEffects` as `forcePromptSideEffects` into `ToolContext` |
+| `assistant/src/tools/executor.ts`                 | `forcePromptSideEffects` gate — promotes allow to prompt for side-effect tools             |
+| `assistant/src/memory/search/types.ts`            | `ScopePolicyOverride` interface for per-call scope control                                 |
+| `assistant/src/memory/retriever.ts`               | `buildScopeFilter()` — builds scope ID list from override or global config                 |
+| `assistant/src/daemon/conversation-memory.ts`     | Wires `scopeId` and `includeDefaultFallback` into recall                                   |
 
 ---
 
@@ -452,19 +452,19 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 
 ### Key files
 
-| File                                                  | Role                                                                                                                                       |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `assistant/src/workspace/top-level-scanner.ts`        | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap                                                                             |
-| `assistant/src/workspace/top-level-renderer.ts`       | Renders `TopLevelSnapshot` to `<workspace_top_level>` XML block                                                                            |
-| `assistant/src/daemon/session-runtime-assembly.ts`    | Runtime injections and strip helpers (`<workspace_top_level>`, `<temporal_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`) |
-| `assistant/src/onboarding/onboarding-orchestrator.ts` | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata                                              |
-| `assistant/src/daemon/session-agent-loop.ts`          | Agent loop orchestration, runtime injection wiring, strip chain                                                                            |
+| File                                                    | Role                                                                                                                                       |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `assistant/src/workspace/top-level-scanner.ts`          | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap                                                                             |
+| `assistant/src/workspace/top-level-renderer.ts`         | Renders `TopLevelSnapshot` to `<workspace_top_level>` XML block                                                                            |
+| `assistant/src/daemon/conversation-runtime-assembly.ts` | Runtime injections and strip helpers (`<workspace_top_level>`, `<temporal_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`) |
+| `assistant/src/onboarding/onboarding-orchestrator.ts`   | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata                                              |
+| `assistant/src/daemon/conversation-agent-loop.ts`       | Agent loop orchestration, runtime injection wiring, strip chain                                                                            |
 
 ---
 
 ## Temporal Context Injection — Date Grounding
 
-The session injects a `<temporal_context>` block into every user message at runtime, giving the model awareness of the current date, current local time, current UTC time, timezone source metadata, upcoming weekend/work week windows, and a 14-day horizon of labelled future dates. This enables reliable reasoning about future dates (e.g. "plan a trip for next weekend") without persisting volatile temporal data in conversation history.
+The session injects a `<temporal_context>` block into every user message at runtime, giving the model awareness of the current date, current local time, current UTC time, and timezone source metadata. This enables reliable reasoning about dates and times without persisting volatile temporal data in conversation history.
 
 ### Per-turn flow
 
@@ -488,18 +488,17 @@ graph TB
 - **Clock source invariant**: Absolute time (`now`) always comes from the assistant host clock (`Date.now()`), never from channel/client clocks.
 - **Timezone precedence**: If `ui.userTimezone` is configured, temporal context uses it for local-date interpretation. Otherwise it falls back to memory-stored timezone, then assistant host timezone.
 - **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic and timezone validation/canonicalization.
-- **Bounded output**: Hard-capped at 1500 characters and 14 horizon entries to prevent prompt bloat.
 - **Runtime-only**: The injected `<temporal_context>` block is stripped from `this.messages` after the agent loop completes via `stripTemporalContext`. It never persists in conversation history.
 - **Specific strip prefix**: The strip function matches the exact injected prefix (`<temporal_context>\nToday:`) to avoid accidentally removing user-authored text that starts with `<temporal_context>`.
 - **Retry paths**: Temporal context is included in all three `applyRuntimeInjections` call sites (main path, compact retry, media-trim retry).
 
 ### Key files
 
-| File                                               | Role                                                                                    |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `assistant/src/daemon/date-context.ts`             | `buildTemporalContext()` — generates the `<temporal_context>` XML block                 |
-| `assistant/src/daemon/session-runtime-assembly.ts` | `injectTemporalContext()` / `stripTemporalContext()` helpers                            |
-| `assistant/src/daemon/session-agent-loop.ts`       | Wiring: computes temporal context, passes to `applyRuntimeInjections`, strips after run |
+| File                                                    | Role                                                                                    |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `assistant/src/daemon/date-context.ts`                  | `buildTemporalContext()` — generates the `<temporal_context>` XML block                 |
+| `assistant/src/daemon/conversation-runtime-assembly.ts` | `injectTemporalContext()` / `stripTemporalContext()` helpers                            |
+| `assistant/src/daemon/conversation-agent-loop.ts`       | Wiring: computes temporal context, passes to `applyRuntimeInjections`, strips after run |
 
 ---
 
@@ -550,7 +549,7 @@ graph TB
 
 1. **Lazy initialization**: The git repository is created on first use, not at workspace creation. When `ensureInitialized()` is called, it checks for a `.git` directory. If absent, it runs `git init`, creates a `.gitignore` (excluding `data/`, `logs/`, `*.log`, `*.sock`, `*.pid`, `session-token`), sets the git identity to "Vellum Assistant", and creates an initial baseline commit capturing any pre-existing files. The baseline commit is intentional — it makes `git log`, `git diff`, and `git revert` work cleanly from the start. Both new and existing workspaces get the same treatment. For existing repos (e.g. created by older versions or external tools), `.gitignore` rules and git identity are set idempotently on each init, ensuring proper configuration regardless of how the repo was originally created.
 
-2. **Turn-boundary commits**: After each conversation turn (user message + assistant response cycle), `session.ts` commits workspace changes via `commitTurnChanges(workspaceDir, sessionId, turnNumber)`. The commit runs in the `finally` block of `runAgentLoop`, guarded by a `turnStarted` flag that is set once the agent loop begins executing. This guarantees a commit attempt even when post-processing (e.g. `resolveAssistantAttachments`) throws, or when the user cancels mid-turn. The commit is raced against a configurable timeout (`workspaceGit.turnCommitMaxWaitMs`, default 4s) via `Promise.race`. If the commit exceeds the timeout, the turn proceeds immediately while the commit continues in the background. Note: the background commit is NOT awaited before the next turn starts, so brief cross-turn file attribution windows are possible but accepted as a tradeoff for responsiveness. Commit outcomes are logged with structured fields (`sessionId`, `turnNumber`, `filesChanged`, `durationMs`) for observability.
+2. **Turn-boundary commits**: After each conversation turn (user message + assistant response cycle), `conversation.ts` commits workspace changes via `commitTurnChanges(workspaceDir, sessionId, turnNumber)`. The commit runs in the `finally` block of `runAgentLoop`, guarded by a `turnStarted` flag that is set once the agent loop begins executing. This guarantees a commit attempt even when post-processing (e.g. `resolveAssistantAttachments`) throws, or when the user cancels mid-turn. The commit is raced against a configurable timeout (`workspaceGit.turnCommitMaxWaitMs`, default 4s) via `Promise.race`. If the commit exceeds the timeout, the turn proceeds immediately while the commit continues in the background. Note: the background commit is NOT awaited before the next turn starts, so brief cross-turn file attribution windows are possible but accepted as a tradeoff for responsiveness. Commit outcomes are logged with structured fields (`sessionId`, `turnNumber`, `filesChanged`, `durationMs`) for observability.
 
 3. **Heartbeat safety net**: A `HeartbeatService` runs on a 5-minute interval, checking all tracked workspaces for uncommitted changes. It auto-commits when changes exceed either an age threshold (5 minutes since first detected) or a file count threshold (20+ files). This catches changes from long-running bash scripts, background processes, or crashed sessions that miss turn-boundary commits.
 
@@ -562,7 +561,7 @@ graph TB
 
 7. **Circuit breaker with exponential backoff**: `WorkspaceGitService` tracks consecutive commit failures and backs off exponentially (2s, 4s, 8s... up to 60s configurable max). When the breaker is open, `commitIfDirty()` short-circuits without attempting git operations. On success, the breaker resets. State transitions are logged at info/warn level with structured fields (`consecutiveFailures`, `backoffMs`).
 
-8. **Turn-commit timeout protection**: The turn-boundary commit in `session.ts` uses `Promise.race` with a configurable timeout (`workspaceGit.turnCommitMaxWaitMs`, default 4s). If the commit exceeds the timeout, the turn proceeds immediately (the commit continues in the background). This prevents slow git operations from blocking the conversation loop.
+8. **Turn-commit timeout protection**: The turn-boundary commit in `conversation.ts` uses `Promise.race` with a configurable timeout (`workspaceGit.turnCommitMaxWaitMs`, default 4s). If the commit exceeds the timeout, the turn proceeds immediately (the commit continues in the background). This prevents slow git operations from blocking the conversation loop.
 
 9. **Non-blocking enrichment queue**: After each successful commit, a `CommitEnrichmentService` runs async enrichment fire-and-forget. The queue has configurable max size (default 50), concurrency (default 1), per-job timeout (default 30s), and retry count (default 2 with exponential backoff). On queue overflow, the oldest job is dropped with a warning log. On graceful shutdown, in-flight jobs drain while pending jobs are discarded. Currently writes placeholder JSON metadata to git notes (`refs/notes/vellum`) as a scaffold for future LLM enrichment.
 
@@ -592,7 +591,7 @@ graph TB
 - **Commit at turn boundaries, not per-tool-call**: A single commit per turn captures all file mutations from that turn atomically. This avoids noisy per-file commits and keeps the history meaningful.
 - **Lazy init with baseline commit**: The repo is created on first use, not at daemon startup. Existing workspaces get their files captured in an "Initial commit: migrated existing workspace" on first use, rather than requiring an explicit migration step. The baseline commit ensures `git log`, `git diff`, and `git revert` work cleanly from the start.
 - **Mutex serialization**: All git operations go through a per-workspace `Mutex` to prevent concurrent `git add`/`git commit` from corrupting the index. The mutex uses a FIFO wait queue.
-- **Finally-block commit guarantee in session-agent-loop.ts**: Turn commits run in the `finally` block of `runAgentLoop`, ensuring they execute even when post-processing throws or the user cancels. The `turnStarted` flag prevents commits for turns that were blocked before the agent loop started. All errors are caught and logged as warnings. The commit is raced against a timeout (`turnCommitMaxWaitMs`, default 4s); if it exceeds the timeout the turn proceeds and the commit continues in the background without synchronization. Brief cross-turn file attribution is accepted as a tradeoff for keeping the conversation loop responsive.
+- **Finally-block commit guarantee in conversation-agent-loop.ts**: Turn commits run in the `finally` block of `runAgentLoop`, ensuring they execute even when post-processing throws or the user cancels. The `turnStarted` flag prevents commits for turns that were blocked before the agent loop started. All errors are caught and logged as warnings. The commit is raced against a timeout (`turnCommitMaxWaitMs`, default 4s); if it exceeds the timeout the turn proceeds and the commit continues in the background without synchronization. Brief cross-turn file attribution is accepted as a tradeoff for keeping the conversation loop responsive.
 - **Branch enforcement at init time**: `ensureOnMainLocked()` is called during initialization to ensure the workspace is on the `main` branch. If the workspace is on the wrong branch or in a detached HEAD state, it auto-corrects to `main` with a warning log. Per-commit enforcement is unnecessary since nothing in the codebase switches branches.
 - **We intentionally don't provide custom history APIs** -- assistants should use git commands naturally via Bash (e.g. `git log`, `git diff`, `git show`). The workspace git repo is a standard git repository that any tool can interact with.
 
@@ -606,7 +605,7 @@ graph TB
 | `assistant/src/workspace/turn-commit.ts`                       | `commitTurnChanges()`: turn-boundary commit with structured metadata + enrichment enqueue                                       |
 | `assistant/src/workspace/provider-commit-message-generator.ts` | `ProviderCommitMessageGenerator`: LLM-based commit message generation with circuit breaker and deterministic fallback           |
 | `assistant/src/workspace/heartbeat-service.ts`                 | `HeartbeatService`: periodic safety-net auto-commits, shutdown commits, enrichment enqueue                                      |
-| `assistant/src/daemon/session-agent-loop.ts`                   | Integration: turn-boundary commit with `raceWithTimeout` protection in `runAgentLoop` finally block                             |
+| `assistant/src/daemon/conversation-agent-loop.ts`              | Integration: turn-boundary commit with `raceWithTimeout` protection in `runAgentLoop` finally block                             |
 | `assistant/src/daemon/lifecycle.ts`                            | Integration: `HeartbeatService` start/stop and shutdown commit                                                                  |
 | `assistant/src/config/schema.ts`                               | `WorkspaceGitConfigSchema`: timeout, backoff, and enrichment queue configuration                                                |
 

package/docs/architecture/security.md

@@ -197,7 +197,7 @@ The `tool_permission_simulate` HTTP endpoint lets clients dry-run a tool invocat
 - The daemon runs `classifyRisk()` and `check()` against the live trust rules, then returns the decision (`allow`, `deny`, or `prompt`), risk level, reason, matched rule ID, and (when decision is `prompt`) the full `promptPayload` with allowlist/scope options.
 - **Simulation-only allow/deny**: A simulated `allow` or `deny` decision does not persist any state. No trust rules are created or modified.
 - **Always-allow persistence**: When the tester UI's "Always Allow" action is used, the client sends a separate `add_trust_rule` message that persists the rule to `trust.json`, identical to the existing confirmation flow.
-- **Private-thread override**: When `forcePromptSideEffects` is true, side-effect tools that would normally be auto-allowed are promoted to `prompt`.
+- **Private-conversation override**: When `forcePromptSideEffects` is true, side-effect tools that would normally be auto-allowed are promoted to `prompt`.
 - **Non-interactive override**: When `isInteractive` is false, `prompt` decisions are converted to `deny` (no client available to approve).
 
 ---
@@ -299,7 +299,7 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 | File                                                 | Role                                                                  |
 | ---------------------------------------------------- | --------------------------------------------------------------------- |
 | `assistant/src/tools/credentials/vault.ts`           | `credential_store` tool — store, list, delete, prompt actions         |
-| `assistant/src/security/secure-keys.ts`              | Keychain read/write via `/usr/bin/security` CLI                       |
+| `assistant/src/security/secure-keys.ts`              | Async secure key CRUD via keychain broker and encrypted file store    |
 | `assistant/src/tools/credentials/metadata-store.ts`  | JSON file metadata CRUD for credential records                        |
 | `assistant/src/tools/credentials/broker.ts`          | Brokered credential access with policy enforcement and transient send |
 | `assistant/src/tools/credentials/policy-validate.ts` | Policy input validation (allowedTools, allowedDomains)                |