@comfanion/usethis_search 4.1.0-dev.3 → 4.2.0-dev.2

package/cache/manager.ts

@@ -1,21 +1,29 @@
 /**
  * Workspace Cache Manager
  *
- * In-memory cache of files attached to the AI's workspace context.
- * search() attaches top results + graph relations here.
- * message.before hook injects cached content into every LLM request.
+ * In-memory cache of chunks attached to the AI's workspace context.
+ * search() attaches top result chunks + graph relation chunks here.
+ * message.before hook injects cached chunks into every LLM request.
+ *
+ * Chunk-based architecture:
+ *   - Each file can be split into multiple chunks (e.g. "src/auth.ts:chunk-5")
+ *   - Chunks are keyed by chunkId (not path)
+ *   - getChunksByPath(path) groups chunks by file
+ *   - freshen() marks chunks as needing refresh if file modified
  *
  * Persistence:
  *   .opencode/.workspace/{sessionId}.json   — per-session workspace state
  *   .opencode/.workspace/latest.json        — fallback (current session)
  *
  *   Only metadata + paths are saved. Content is re-read from disk on restore.
+ *   Note: Chunks cannot be re-read from disk (chunk boundaries not stored).
+ *   Restore uses saved content if available, otherwise skips chunk.
  *
  * Lifecycle:
- *   search("auth") -> attach top N main files + graph relations
- *   message.before -> inject all cached files into user message
+ *   search("auth") -> attach top N chunks (from multiple files)
+ *   message.before -> inject all cached chunks into user message
  *   workspace.detach / workspace.clear -> manual cleanup
- *   ensureBudget() -> auto-evict oldest low-score files when over limit
+ *   ensureBudget() -> auto-evict oldest low-score chunks when over limit
  *   save() / restore() -> persist to / load from .opencode/.workspace/
  */
 
@@ -26,15 +34,19 @@ import crypto from "crypto"
 // ── Types ───────────────────────────────────────────────────────────────────
 
 export interface WorkspaceEntry {
+  /** Unique chunk identifier (e.g. "src/auth/login.ts:chunk-5") */
+  chunkId: string
   /** Relative file path (e.g. "src/auth/login.ts") */
   path: string
-  /** Full file content (loaded in memory, NOT persisted to JSON) */
+  /** Chunk content (NOT full file — just this chunk) */
   content: string
-  /** Estimated token count (~content.length / 4) */
+  /** Estimated token count for this chunk (~content.length / 4) */
   tokens: number
-  /** MD5 hash of content — used by freshen() to detect disk changes */
+  /** Chunk index within file (0-based) */
+  chunkIndex: number
+  /** MD5 hash of chunk content — used by freshen() to detect changes */
   contentHash: string
-  /** How this file got into workspace */
+  /** How this chunk got into workspace */
   role: "search-main" | "search-graph" | "manual"
   /** Timestamp when attached */
   attachedAt: number
@@ -42,7 +54,7 @@ export interface WorkspaceEntry {
   attachedBy: string
   /** Search relevance score (0-1) */
   score?: number
-  /** File metadata from search results */
+  /** Chunk metadata from search results */
   metadata?: {
     language?: string
     function_name?: string
@@ -50,15 +62,20 @@ export interface WorkspaceEntry {
     heading_context?: string
     /** Graph relation type (for role=search-graph) */
     relation?: string
-    /** Which main file pulled this graph file in */
-    mainFile?: string
+    /** Which main chunk pulled this graph chunk in */
+    mainChunkId?: string
+    /** Start/end line numbers in original file */
+    startLine?: number
+    endLine?: number
   }
 }
 
 /** Serialized entry — content included only when persistContent=true */
 interface PersistedEntry {
+  chunkId: string
   path: string
   tokens: number
+  chunkIndex: number
   role: WorkspaceEntry["role"]
   attachedAt: number
   attachedBy: string
@@ -66,6 +83,8 @@ interface PersistedEntry {
   metadata?: WorkspaceEntry["metadata"]
   /** Only present when config.persistContent=true (debug mode) */
   content?: string
+  /** MD5 hash of chunk content (for freshen detection) */
+  contentHash?: string
 }
 
 /** On-disk workspace snapshot */
@@ -73,28 +92,30 @@ interface WorkspaceSnapshot {
   sessionId: string
   savedAt: string
   totalTokens: number
-  fileCount: number
+  chunkCount: number
   /** true if content is included in entries */
   debug: boolean
   entries: PersistedEntry[]
+  /** Deprecated: old fileCount field (for backward compatibility) */
+  fileCount?: number
 }
 
 export interface WorkspaceConfig {
-  /** Max total tokens across all files (default: 50000) */
+  /** Max total tokens across all chunks (default: 50000) */
   maxTokens: number
-  /** Max number of files (default: 30) */
-  maxFiles: number
-  /** How many top search results to attach (default: 5) */
+  /** Max number of chunks (default: 100) */
+  maxChunks: number
+  /** How many top search chunks to attach (default: 10) */
   attachTopN: number
-  /** Max graph relations per main file (default: 3) */
-  attachRelatedPerFile: number
-  /** Min score for main files to be attached (default: 0.65) */
+  /** Max graph relation chunks per main chunk (default: 3) */
+  attachRelatedPerChunk: number
+  /** Min score for main chunks to be attached (default: 0.65) */
   minScoreMain: number
-  /** Min score for graph relations to be attached (default: 0.5) */
+  /** Min score for graph relation chunks to be attached (default: 0.5) */
   minScoreRelated: number
   /**
-   * Save full file content in workspace snapshots (default: false).
-   * When true: .workspace/{sessionId}.json includes content for every file.
+   * Save full chunk content in workspace snapshots (default: false).
+   * When true: .workspace/{sessionId}.json includes content for every chunk.
    * Useful for debugging — see exactly what the AI saw.
    * Warning: snapshots can be 10-50MB+ with content enabled.
    */
@@ -102,23 +123,23 @@ export interface WorkspaceConfig {
   /**
    * Auto-prune old search tool outputs from chat history (default: true).
    * When true: message.before hook replaces old search outputs with 1-line summaries.
-   * Files are already in workspace injection — keeping big outputs wastes tokens.
+   * Chunks are already in workspace injection — keeping big outputs wastes tokens.
    */
   autoPruneSearch: boolean
   /**
-   * Substitute tool outputs when files are in workspace (default: true).
-   * When true: read(), grep(), glob() outputs are replaced with compact messages
-   * if all matched files are in workspace cache.
-   * Saves tokens since files are already visible in workspace injection.
+   * Substitute tool outputs when chunks are in workspace (default: true).
+   * When true: read() outputs are replaced with compact messages
+   * if file has chunks in workspace cache.
+   * Saves tokens since chunks are already visible in workspace injection.
    */
   substituteToolOutputs: boolean
 }
 
 export const DEFAULT_WORKSPACE_CONFIG: WorkspaceConfig = {
   maxTokens: 50_000,
-  maxFiles: 30,
-  attachTopN: 5,
-  attachRelatedPerFile: 3,
+  maxChunks: 100,
+  attachTopN: 10,
+  attachRelatedPerChunk: 3,
   minScoreMain: 0.65,
   minScoreRelated: 0.5,
   persistContent: false,
@@ -129,6 +150,7 @@ export const DEFAULT_WORKSPACE_CONFIG: WorkspaceConfig = {
 // ── Implementation ──────────────────────────────────────────────────────────
 
 class WorkspaceCache {
+  /** Map of chunks keyed by chunkId (e.g. "src/auth.ts:chunk-5") */
   private entries = new Map<string, WorkspaceEntry>()
   private _totalTokens = 0
   private config: WorkspaceConfig
@@ -165,31 +187,31 @@ class WorkspaceCache {
    * Safe to call multiple times — second call with a different sessionId
    * will save current state, then restore for the new session.
    */
-  async init(projectRoot: string, sessionId?: string): Promise<void> {
-    // If re-initializing with a new session — flush current state first
-    if (this.projectRoot && this.sessionId && sessionId && sessionId !== this.sessionId) {
-      await this.save()
-    }
-
-    this.projectRoot = projectRoot
-    this.sessionId = sessionId || `session-${Date.now()}`
-
-    // Try to restore existing workspace for this session
-    const restored = await this.restore(this.sessionId)
-    if (restored) {
-      console.log(`[workspace] Restored session ${this.sessionId} (${this.entries.size} files, ${this._totalTokens} tokens)`)
-    } else if (!sessionId) {
-      // Only fall back to latest.json when no specific session requested
-      // (avoids clobbering a fresh session with stale data)
-      const restoredLatest = await this.restore("latest")
-      if (restoredLatest) {
-        console.log(`[workspace] Restored from latest (${this.entries.size} files, ${this._totalTokens} tokens)`)
-      }
-    }
-
-    // Register process exit handler (once)
-    this.registerShutdownHook()
-  }
+   async init(projectRoot: string, sessionId?: string): Promise<void> {
+     // If re-initializing with a new session — flush current state first
+     if (this.projectRoot && this.sessionId && sessionId && sessionId !== this.sessionId) {
+       await this.save()
+     }
+
+     this.projectRoot = projectRoot
+     this.sessionId = sessionId || `session-${Date.now()}`
+
+     // Try to restore existing workspace for this session
+     const restored = await this.restore(this.sessionId)
+     if (restored) {
+       console.log(`[workspace] Restored session ${this.sessionId} (${this.entries.size} chunks, ${this._totalTokens} tokens)`)
+     } else if (!sessionId) {
+       // Only fall back to latest.json when no specific session requested
+       // (avoids clobbering a fresh session with stale data)
+       const restoredLatest = await this.restore("latest")
+       if (restoredLatest) {
+         console.log(`[workspace] Restored from latest (${this.entries.size} chunks, ${this._totalTokens} tokens)`)
+       }
+     }
+
+     // Register process exit handler (once)
+     this.registerShutdownHook()
+   }
 
   /** Whether shutdown hook is registered */
   private _shutdownRegistered = false
@@ -202,48 +224,51 @@ class WorkspaceCache {
     if (this._shutdownRegistered) return
     this._shutdownRegistered = true
 
-    const flush = () => {
-      // Synchronous-ish flush — best effort
-      // Node process is exiting, so we can't await.
-      // Use writeFileSync as last resort.
-      try {
-        const dir = this.getWorkspaceDir()
-        if (!dir || this.entries.size === 0) return
-
-        const id = this.sessionId || "latest"
-        const includeContent = this.config.persistContent
-
-        const snapshot = {
-          sessionId: id,
-          savedAt: new Date().toISOString(),
-          totalTokens: this._totalTokens,
-          fileCount: this.entries.size,
-          debug: includeContent,
-          entries: Array.from(this.entries.values()).map(e => {
-            const p: any = {
-              path: e.path,
-              tokens: e.tokens,
-              role: e.role,
-              attachedAt: e.attachedAt,
-              attachedBy: e.attachedBy,
-              score: e.score,
-              metadata: e.metadata,
-            }
-            if (includeContent) p.content = e.content
-            return p
-          }),
-        }
-
-        const data = JSON.stringify(snapshot, null, 2)
-        const fsSync = require("fs")
-
-        fsSync.mkdirSync(dir, { recursive: true })
-        fsSync.writeFileSync(path.join(dir, `${id}.json`), data, "utf-8")
-        fsSync.writeFileSync(path.join(dir, "latest.json"), data, "utf-8")
-      } catch {
-        // Best effort — process is dying
-      }
-    }
+     const flush = () => {
+       // Synchronous-ish flush — best effort
+       // Node process is exiting, so we can't await.
+       // Use writeFileSync as last resort.
+       try {
+         const dir = this.getWorkspaceDir()
+         if (!dir || this.entries.size === 0) return
+
+         const id = this.sessionId || "latest"
+         const includeContent = this.config.persistContent
+
+         const snapshot = {
+           sessionId: id,
+           savedAt: new Date().toISOString(),
+           totalTokens: this._totalTokens,
+           chunkCount: this.entries.size,
+           debug: includeContent,
+           entries: Array.from(this.entries.values()).map(e => {
+             const p: any = {
+               chunkId: e.chunkId,
+               path: e.path,
+               tokens: e.tokens,
+               chunkIndex: e.chunkIndex,
+               role: e.role,
+               attachedAt: e.attachedAt,
+               attachedBy: e.attachedBy,
+               score: e.score,
+               metadata: e.metadata,
+               contentHash: e.contentHash,
+             }
+             if (includeContent) p.content = e.content
+             return p
+           }),
+         }
+
+         const data = JSON.stringify(snapshot, null, 2)
+         const fsSync = require("fs")
+
+         fsSync.mkdirSync(dir, { recursive: true })
+         fsSync.writeFileSync(path.join(dir, `${id}.json`), data, "utf-8")
+         fsSync.writeFileSync(path.join(dir, "latest.json"), data, "utf-8")
+       } catch {
+         // Best effort — process is dying
+       }
+     }
 
     process.on("exit", flush)
     process.on("SIGINT", () => { flush(); process.exit(0) })
@@ -268,165 +293,162 @@ class WorkspaceCache {
     }
   }
 
-  /**
-   * Save workspace metadata to disk immediately.
-   */
-  async save(snapshotId?: string): Promise<void> {
-    const dir = this.getWorkspaceDir()
-    if (!dir) return
-
-    const id = snapshotId || this.sessionId || "latest"
-
-    const includeContent = this.config.persistContent
-
-    const snapshot: WorkspaceSnapshot = {
-      sessionId: id,
-      savedAt: new Date().toISOString(),
-      totalTokens: this._totalTokens,
-      fileCount: this.entries.size,
-      debug: includeContent,
-      entries: Array.from(this.entries.values()).map(e => {
-        const persisted: PersistedEntry = {
-          path: e.path,
-          tokens: e.tokens,
-          role: e.role,
-          attachedAt: e.attachedAt,
-          attachedBy: e.attachedBy,
-          score: e.score,
-          metadata: e.metadata,
-        }
-        if (includeContent) {
-          persisted.content = e.content
-        }
-        return persisted
-      }),
-    }
-
-    try {
-      await fs.mkdir(dir, { recursive: true })
-
-      // Save session-specific file
-      const sessionFile = path.join(dir, `${id}.json`)
-      await fs.writeFile(sessionFile, JSON.stringify(snapshot, null, 2), "utf-8")
-
-      // Also save as latest.json (always keep current state accessible)
-      const latestFile = path.join(dir, "latest.json")
-      await fs.writeFile(latestFile, JSON.stringify(snapshot, null, 2), "utf-8")
-    } catch (error) {
-      console.error("[workspace] Failed to save:", error)
-    }
-  }
-
-  /**
-   * Restore workspace from disk.
-   * Re-reads file content from project files (NOT from snapshot).
-   * Files that no longer exist on disk are skipped.
-   *
-   * Returns true if snapshot was found and loaded.
-   */
-  async restore(snapshotId?: string): Promise<boolean> {
-    const dir = this.getWorkspaceDir()
-    if (!dir || !this.projectRoot) return false
-
-    const id = snapshotId || this.sessionId || "latest"
-    const snapshotFile = path.join(dir, `${id}.json`)
-
-    let snapshot: WorkspaceSnapshot
-    try {
-      const raw = await fs.readFile(snapshotFile, "utf-8")
-      snapshot = JSON.parse(raw)
-    } catch {
-      return false // No snapshot found
-    }
-
-    // Clear current state
-    this.entries.clear()
-    this._totalTokens = 0
-
-    // Re-read file content from disk (or use saved content in debug mode)
-    let loaded = 0
-    let skipped = 0
-
-    for (const entry of snapshot.entries) {
-      let content: string | null = null
-
-      // If snapshot has content (debug mode) — use it directly
-      if (entry.content) {
-        content = entry.content
-      } else {
-        // Otherwise re-read from disk
-        try {
-          const fullPath = path.join(this.projectRoot, entry.path)
-          content = await fs.readFile(fullPath, "utf-8")
-        } catch {
-          // File no longer exists or unreadable
-        }
-      }
-
-      if (content === null) {
-        skipped++
-        continue
-      }
-
-      const tokens = this.countTokens(content)
-
-      this.entries.set(entry.path, {
-        path: entry.path,
-        content,
-        tokens,
-        contentHash: this.hashContent(content),
-        role: entry.role,
-        attachedAt: entry.attachedAt,
-        attachedBy: entry.attachedBy,
-        score: entry.score,
-        metadata: entry.metadata,
-      })
-      this._totalTokens += tokens
-      loaded++
-    }
-
-    if (skipped > 0) {
-      console.log(`[workspace] Restore: ${loaded} loaded, ${skipped} skipped (files missing)`)
-    }
-
-    return loaded > 0
-  }
-
-  /**
-   * List all saved workspace snapshots.
-   */
-  async listSnapshots(): Promise<{ id: string; savedAt: string; fileCount: number; totalTokens: number }[]> {
-    const dir = this.getWorkspaceDir()
-    if (!dir) return []
-
-    try {
-      const files = await fs.readdir(dir)
-      const snapshots: { id: string; savedAt: string; fileCount: number; totalTokens: number }[] = []
-
-      for (const file of files) {
-        if (!file.endsWith(".json") || file === "latest.json") continue
-
-        try {
-          const raw = await fs.readFile(path.join(dir, file), "utf-8")
-          const snap: WorkspaceSnapshot = JSON.parse(raw)
-          snapshots.push({
-            id: snap.sessionId,
-            savedAt: snap.savedAt,
-            fileCount: snap.fileCount,
-            totalTokens: snap.totalTokens,
-          })
-        } catch {
-          // Corrupt file — skip
-        }
-      }
-
-      // Sort by savedAt descending
-      snapshots.sort((a, b) => b.savedAt.localeCompare(a.savedAt))
-      return snapshots
-    } catch {
-      return []
-    }
-  }
+   /**
+    * Save workspace metadata to disk immediately.
+    * Chunks are keyed by chunkId in the snapshot.
+    */
+   async save(snapshotId?: string): Promise<void> {
+     const dir = this.getWorkspaceDir()
+     if (!dir) return
+
+     const id = snapshotId || this.sessionId || "latest"
+
+     const includeContent = this.config.persistContent
+
+     const snapshot: WorkspaceSnapshot = {
+       sessionId: id,
+       savedAt: new Date().toISOString(),
+       totalTokens: this._totalTokens,
+       chunkCount: this.entries.size,
+       debug: includeContent,
+       entries: Array.from(this.entries.values()).map(e => {
+         const persisted: PersistedEntry = {
+           chunkId: e.chunkId,
+           path: e.path,
+           tokens: e.tokens,
+           chunkIndex: e.chunkIndex,
+           role: e.role,
+           attachedAt: e.attachedAt,
+           attachedBy: e.attachedBy,
+           score: e.score,
+           metadata: e.metadata,
+           contentHash: e.contentHash,
+         }
+         if (includeContent) {
+           persisted.content = e.content
+         }
+         return persisted
+       }),
+     }
+
+     try {
+       await fs.mkdir(dir, { recursive: true })
+
+       // Save session-specific file
+       const sessionFile = path.join(dir, `${id}.json`)
+       await fs.writeFile(sessionFile, JSON.stringify(snapshot, null, 2), "utf-8")
+
+       // Also save as latest.json (always keep current state accessible)
+       const latestFile = path.join(dir, "latest.json")
+       await fs.writeFile(latestFile, JSON.stringify(snapshot, null, 2), "utf-8")
+     } catch (error) {
+       console.error("[workspace] Failed to save:", error)
+     }
+   }
+
+   /**
+    * Restore workspace from disk.
+    * Chunks are keyed by chunkId.
+    * 
+    * For chunks: uses saved content if available (debug mode).
+    * Cannot re-read chunks from disk since chunk boundaries aren't stored.
+    * Chunks without saved content are skipped.
+    *
+    * Returns true if snapshot was found and loaded.
+    */
+   async restore(snapshotId?: string): Promise<boolean> {
+     const dir = this.getWorkspaceDir()
+     if (!dir || !this.projectRoot) return false
+
+     const id = snapshotId || this.sessionId || "latest"
+     const snapshotFile = path.join(dir, `${id}.json`)
+
+     let snapshot: WorkspaceSnapshot
+     try {
+       const raw = await fs.readFile(snapshotFile, "utf-8")
+       snapshot = JSON.parse(raw)
+     } catch {
+       return false // No snapshot found
+     }
+
+     // Clear current state
+     this.entries.clear()
+     this._totalTokens = 0
+
+     // Restore chunks from snapshot
+     // Note: Chunks can only be restored if content was saved (debug mode)
+     let loaded = 0
+     let skipped = 0
+
+     for (const entry of snapshot.entries) {
+       // Chunks require saved content — cannot re-read from disk
+       if (!entry.content) {
+         skipped++
+         continue
+       }
+
+       const content = entry.content
+       const tokens = this.countTokens(content)
+
+       this.entries.set(entry.chunkId, {
+         chunkId: entry.chunkId,
+         path: entry.path,
+         content,
+         tokens,
+         chunkIndex: entry.chunkIndex,
+         contentHash: entry.contentHash || this.hashContent(content),
+         role: entry.role,
+         attachedAt: entry.attachedAt,
+         attachedBy: entry.attachedBy,
+         score: entry.score,
+         metadata: entry.metadata,
+       })
+       this._totalTokens += tokens
+       loaded++
+     }
+
+     if (skipped > 0) {
+       console.log(`[workspace] Restore: ${loaded} chunks loaded, ${skipped} skipped (no saved content)`)
+     }
+
+     return loaded > 0
+   }
+
+   /**
+    * List all saved workspace snapshots.
+    */
+   async listSnapshots(): Promise<{ id: string; savedAt: string; chunkCount: number; totalTokens: number }[]> {
+     const dir = this.getWorkspaceDir()
+     if (!dir) return []
+
+     try {
+       const files = await fs.readdir(dir)
+       const snapshots: { id: string; savedAt: string; chunkCount: number; totalTokens: number }[] = []
+
+       for (const file of files) {
+         if (!file.endsWith(".json") || file === "latest.json") continue
+
+         try {
+           const raw = await fs.readFile(path.join(dir, file), "utf-8")
+           const snap: WorkspaceSnapshot = JSON.parse(raw)
+           snapshots.push({
+             id: snap.sessionId,
+             savedAt: snap.savedAt,
+             chunkCount: snap.chunkCount || snap.fileCount || 0,
+             totalTokens: snap.totalTokens,
+           })
+         } catch {
+           // Corrupt file — skip
+         }
+       }
+
+       // Sort by savedAt descending
+       snapshots.sort((a, b) => b.savedAt.localeCompare(a.savedAt))
+       return snapshots
+     } catch {
+       return []
+     }
+   }
 
   /**
    * Delete a saved snapshot.
@@ -443,145 +465,170 @@ class WorkspaceCache {
     }
   }
 
-  // ── Core operations ─────────────────────────────────────────────────────
-
-  /**
-   * Attach a file to workspace.
-   * If file already exists, updates it (replaces content/score).
-   * Auto-saves to disk (debounced).
-   */
-  attach(entry: Omit<WorkspaceEntry, "tokens" | "contentHash">): void {
-    const tokens = this.countTokens(entry.content)
-    const contentHash = this.hashContent(entry.content)
-
-    // Update existing — subtract old tokens first
-    const existing = this.entries.get(entry.path)
-    if (existing) {
-      this._totalTokens -= existing.tokens
-    }
-
-    this.entries.set(entry.path, { ...entry, tokens, contentHash })
-    this._totalTokens += tokens
-
-    // Auto-evict if over budget
-    this.ensureBudget()
-
-    // Auto-save (debounced)
-    this.scheduleSave()
-  }
-
-  /**
-   * Remove a single file from workspace.
-   * Returns true if file was found and removed.
-   */
-  detach(filePath: string): boolean {
-    const entry = this.entries.get(filePath)
-    if (!entry) return false
-
-    this.entries.delete(filePath)
-    this._totalTokens -= entry.tokens
-
-    // Auto-save (debounced)
-    this.scheduleSave()
-    return true
-  }
-
-  /**
-   * Remove all files older than `ms` milliseconds.
-   * Returns number of files removed.
-   */
-  detachOlderThan(ms: number): number {
-    const cutoff = Date.now() - ms
-    let removed = 0
-
-    for (const [filePath, entry] of this.entries) {
-      if (entry.attachedAt < cutoff) {
-        this.entries.delete(filePath)
-        this._totalTokens -= entry.tokens
-        removed++
-      }
-    }
-
-    if (removed > 0) this.scheduleSave()
-    return removed
-  }
-
-  /**
-   * Remove all files that were attached by a specific search query.
-   * Returns number of files removed.
-   */
-  detachByQuery(query: string): number {
-    let removed = 0
-
-    for (const [filePath, entry] of this.entries) {
-      if (entry.attachedBy === query || entry.attachedBy.startsWith(`${query} (`)) {
-        this.entries.delete(filePath)
-        this._totalTokens -= entry.tokens
-        removed++
-      }
-    }
-
-    if (removed > 0) this.scheduleSave()
-    return removed
-  }
-
-  /**
-   * Get all entries sorted by: search-main first (by score desc), then search-graph, then manual.
-   */
-  getAll(): WorkspaceEntry[] {
-    return Array.from(this.entries.values()).sort((a, b) => {
-      // Main files first
-      const roleOrder = { "search-main": 0, "search-graph": 1, manual: 2 }
-      const ra = roleOrder[a.role] ?? 2
-      const rb = roleOrder[b.role] ?? 2
-      if (ra !== rb) return ra - rb
-
-      // Within same role: higher score first
-      if (a.score !== undefined && b.score !== undefined) {
-        return b.score - a.score
-      }
-
-      // Fallback: alphabetical
-      return a.path.localeCompare(b.path)
-    })
-  }
-
-  /**
-   * Check if a file is in workspace.
-   */
-  has(filePath: string): boolean {
-    return this.entries.has(filePath)
-  }
-
-  /**
-   * Get a single entry by path.
-   */
-  get(filePath: string): WorkspaceEntry | undefined {
-    return this.entries.get(filePath)
-  }
-
-  /**
-   * Remove all files from workspace.
-   */
-  clear(): void {
-    this.entries.clear()
-    this._totalTokens = 0
-    this.scheduleSave()
-  }
-
-  /**
-   * Total tokens across all cached files.
-   */
-  get totalTokens(): number {
-    return this._totalTokens
-  }
-
-  /**
-   * Number of files in workspace.
-   */
-  get size(): number {
-    return this.entries.size
-  }
+   // ── Core operations ─────────────────────────────────────────────────────
+
+   /**
+    * Attach a chunk to workspace.
+    * If chunk with same chunkId already exists, updates it (replaces content/score).
+    * Auto-saves to disk (debounced).
+    */
+   attach(entry: Omit<WorkspaceEntry, "tokens" | "contentHash">): void {
+     const tokens = this.countTokens(entry.content)
+     const contentHash = this.hashContent(entry.content)
+
+     // Update existing chunk — subtract old tokens first
+     const existing = this.entries.get(entry.chunkId)
+     if (existing) {
+       this._totalTokens -= existing.tokens
+     }
+
+     this.entries.set(entry.chunkId, { ...entry, tokens, contentHash })
+     this._totalTokens += tokens
+
+     // Auto-evict if over budget
+     this.ensureBudget()
+
+     // Auto-save (debounced)
+     this.scheduleSave()
+   }
+
+   /**
+    * Remove a single chunk from workspace by chunkId.
+    * Returns true if chunk was found and removed.
+    */
+   detach(chunkId: string): boolean {
+     const entry = this.entries.get(chunkId)
+     if (!entry) return false
+
+     this.entries.delete(chunkId)
+     this._totalTokens -= entry.tokens
+
+     // Auto-save (debounced)
+     this.scheduleSave()
+     return true
+   }
+
+   /**
+    * Remove all chunks older than `ms` milliseconds.
+    * Returns number of chunks removed.
+    */
+   detachOlderThan(ms: number): number {
+     const cutoff = Date.now() - ms
+     let removed = 0
+
+     for (const [chunkId, entry] of this.entries) {
+       if (entry.attachedAt < cutoff) {
+         this.entries.delete(chunkId)
+         this._totalTokens -= entry.tokens
+         removed++
+       }
+     }
+
+     if (removed > 0) this.scheduleSave()
+     return removed
+   }
+
+   /**
+    * Remove all chunks that were attached by a specific search query.
+    * Returns number of chunks removed.
+    */
+   detachByQuery(query: string): number {
+     let removed = 0
+
+     for (const [chunkId, entry] of this.entries) {
+       if (entry.attachedBy === query || entry.attachedBy.startsWith(`${query} (`)) {
+         this.entries.delete(chunkId)
+         this._totalTokens -= entry.tokens
+         removed++
+       }
+     }
+
+     if (removed > 0) this.scheduleSave()
+     return removed
+   }
+
+   /**
+    * Get all chunks sorted by: search-main first (by score desc), then search-graph, then manual.
+    */
+   getAll(): WorkspaceEntry[] {
+     return Array.from(this.entries.values()).sort((a, b) => {
+       // Main chunks first
+       const roleOrder = { "search-main": 0, "search-graph": 1, manual: 2 }
+       const ra = roleOrder[a.role] ?? 2
+       const rb = roleOrder[b.role] ?? 2
+       if (ra !== rb) return ra - rb
+
+       // Within same role: higher score first
+       if (a.score !== undefined && b.score !== undefined) {
+         return b.score - a.score
+       }
+
+       // Fallback: alphabetical by chunkId
+       return a.chunkId.localeCompare(b.chunkId)
+     })
+   }
+
+   /**
+    * Check if a chunk is in workspace by chunkId.
+    * If path is given instead, checks if ANY chunks with that path exist.
+    */
+   has(chunkIdOrPath: string): boolean {
+     // If it looks like a chunkId (contains ":chunk-"), check directly
+     if (chunkIdOrPath.includes(":chunk-")) {
+       return this.entries.has(chunkIdOrPath)
+     }
+     // Otherwise treat as path — check if any chunks have this path
+     for (const entry of this.entries.values()) {
+       if (entry.path === chunkIdOrPath) return true
+     }
+     return false
+   }
+
+   /**
+    * Get a single chunk by chunkId.
+    */
+   get(chunkId: string): WorkspaceEntry | undefined {
+     return this.entries.get(chunkId)
+   }
+
+   /**
+    * Get all chunks for a given file path.
+    * Returns chunks sorted by chunkIndex (ascending).
+    */
+   getChunksByPath(filePath: string): WorkspaceEntry[] {
+     const chunks: WorkspaceEntry[] = []
+     for (const entry of this.entries.values()) {
+       if (entry.path === filePath) {
+         chunks.push(entry)
+       }
+     }
+     // Sort by chunk index to maintain order
+     chunks.sort((a, b) => a.chunkIndex - b.chunkIndex)
+     return chunks
+   }
+
+   /**
+    * Remove all chunks from workspace.
+    */
+   clear(): void {
+     this.entries.clear()
+     this._totalTokens = 0
+     this.scheduleSave()
+   }
+
+   /**
+    * Total tokens across all cached chunks.
+    */
+   get totalTokens(): number {
+     return this._totalTokens
+   }
+
+   /**
+    * Number of chunks in workspace.
+    */
+   get size(): number {
+     return this.entries.size
+   }
 
   /**
    * Current session ID.
@@ -605,127 +652,140 @@ class WorkspaceCache {
     this.ensureBudget()
   }
 
-  /**
-   * Mark file as dirty (modified by edit/write tool).
-   * Dirty files bypass read() substitution until next freshen().
-   */
-  markDirty(filePath: string): void {
-    this.dirtyFiles.add(filePath)
-  }
-
-  /**
-   * Check if file is dirty (modified since last freshen).
-   */
-  isDirty(filePath: string): boolean {
-    return this.dirtyFiles.has(filePath)
-  }
-
-  /**
-   * Clear all dirty flags (called by freshen after re-reading files).
-   */
-  clearDirty(): void {
-    this.dirtyFiles.clear()
-  }
+   /**
+    * Mark file as dirty (modified by edit/write tool).
+    * Dirty files bypass read() substitution until next freshen().
+    * Note: Marks by path, not chunkId (all chunks in file are dirty).
+    */
+   markDirty(filePath: string): void {
+     this.dirtyFiles.add(filePath)
+   }
+
+   /**
+    * Check if file is dirty (modified since last freshen).
+    */
+   isDirty(filePath: string): boolean {
+     return this.dirtyFiles.has(filePath)
+   }
+
+   /**
+    * Clear all dirty flags (called by freshen after re-reading files).
+    */
+   clearDirty(): void {
+     this.dirtyFiles.clear()
+   }
 
   // ── Freshness ────────────────────────────────────────────────────────────
 
-  /**
-   * Re-read workspace files from disk if they changed.
-   * Compares stored contentHash with current file hash.
-   * Removes entries whose files no longer exist on disk.
-   *
-   * Called by message.before hook — ensures AI always sees fresh content.
-   * Cost: ~2ms for 30 files (stat + optional readFile).
-   *
-   * Returns { updated, removed } counts.
-   */
-  async freshen(): Promise<{ updated: number; removed: number }> {
-    if (!this.projectRoot) return { updated: 0, removed: 0 }
-
-    let updated = 0
-    let removed = 0
-
-    for (const [filePath, entry] of this.entries) {
-      try {
-        const fullPath = path.join(this.projectRoot, filePath)
-        const content = await fs.readFile(fullPath, "utf-8")
-        const newHash = this.hashContent(content)
-
-        if (newHash !== entry.contentHash) {
-          // File changed on disk — update in-memory
-          const oldTokens = entry.tokens
-          const newTokens = this.countTokens(content)
-
-          entry.content = content
-          entry.contentHash = newHash
-          entry.tokens = newTokens
-          this._totalTokens += newTokens - oldTokens
-
-          updated++
-        }
-      } catch {
-        // File no longer exists — remove from workspace
-        this.entries.delete(filePath)
-        this._totalTokens -= entry.tokens
-        removed++
-      }
-    }
-
-    if (updated > 0 || removed > 0) {
-      this.scheduleSave()
-    }
-
-    // Clear dirty flags — all files are now fresh from disk
-    this.clearDirty()
-
-    return { updated, removed }
-  }
+   /**
+    * Mark chunks as needing refresh if their source file changed on disk.
+    * Removes chunks whose source files no longer exist.
+    *
+    * NOTE: Chunks cannot be re-read from disk (chunk boundaries not stored).
+    * This method only detects changes and removes orphaned chunks.
+    * For full content refresh, chunks must be re-attached from search.
+    *
+    * Called by message.before hook — ensures AI sees fresh file status.
+    * Cost: ~2ms for 30 files (stat only, no readFile).
+    *
+    * Returns { updated, removed } counts.
+    */
+   async freshen(): Promise<{ updated: number; removed: number }> {
+     if (!this.projectRoot) return { updated: 0, removed: 0 }
+
+     let stale = 0
+     let removed = 0
+
+     // Group chunks by path for efficient checking
+     const pathToChunks = new Map<string, WorkspaceEntry[]>()
+     for (const entry of this.entries.values()) {
+       if (!pathToChunks.has(entry.path)) {
+         pathToChunks.set(entry.path, [])
+       }
+       pathToChunks.get(entry.path)!.push(entry)
+     }
+
+     // Check each unique file path
+     for (const [filePath, chunks] of pathToChunks) {
+       try {
+         const fullPath = path.join(this.projectRoot, filePath)
+         const content = await fs.readFile(fullPath, "utf-8")
+         const newHash = this.hashContent(content)
+
+         // Check if file changed
+         const fileChanged = chunks.some(c => c.contentHash !== newHash)
+         if (fileChanged) {
+           // Mark all chunks from this file as stale
+           // (they need re-attachment from search to get fresh content)
+           stale += chunks.length
+           // TODO(chunk-7): Implement stale flag on WorkspaceEntry
+           // For now, chunks remain in cache but are marked as needing refresh
+         }
+       } catch {
+         // File no longer exists — remove all chunks from this file
+         for (const chunk of chunks) {
+           this.entries.delete(chunk.chunkId)
+           this._totalTokens -= chunk.tokens
+           removed++
+         }
+       }
+     }
+
+     if (stale > 0 || removed > 0) {
+       this.scheduleSave()
+     }
+
+     // Clear dirty flags — all files are now checked
+     this.clearDirty()
+
+     return { updated: stale, removed }
+   }
 
   // ── Budget management ───────────────────────────────────────────────────
 
-  /**
-   * Evict oldest / lowest-score files until within budget.
-   * Priority: evict search-graph first, then search-main, then manual.
-   * Within same role: lowest score first, then oldest first.
-   */
-  private ensureBudget(): void {
-    // Check both token and file count limits
-    if (
-      this._totalTokens <= this.config.maxTokens &&
-      this.entries.size <= this.config.maxFiles
-    ) {
-      return
-    }
-
-    // Build eviction priority list
-    const candidates = Array.from(this.entries.values()).sort((a, b) => {
-      // Evict graph files before main files before manual files
-      const roleOrder = { "search-graph": 0, "search-main": 1, manual: 2 }
-      const ra = roleOrder[a.role] ?? 2
-      const rb = roleOrder[b.role] ?? 2
-      if (ra !== rb) return ra - rb
-
-      // Within same role: lowest score first
-      const sa = a.score ?? 0
-      const sb = b.score ?? 0
-      if (sa !== sb) return sa - sb
-
-      // Then oldest first
-      return a.attachedAt - b.attachedAt
-    })
-
-    for (const entry of candidates) {
-      if (
-        this._totalTokens <= this.config.maxTokens &&
-        this.entries.size <= this.config.maxFiles
-      ) {
-        break
-      }
-
-      this.entries.delete(entry.path)
-      this._totalTokens -= entry.tokens
-    }
-  }
+   /**
+    * Evict oldest / lowest-score chunks until within budget.
+    * Priority: evict search-graph first, then search-main, then manual.
+    * Within same role: lowest score first, then oldest first.
+    */
+   private ensureBudget(): void {
+     // Check both token and chunk count limits
+     if (
+       this._totalTokens <= this.config.maxTokens &&
+       this.entries.size <= this.config.maxChunks
+     ) {
+       return
+     }
+
+     // Build eviction priority list
+     const candidates = Array.from(this.entries.values()).sort((a, b) => {
+       // Evict graph chunks before main chunks before manual chunks
+       const roleOrder = { "search-graph": 0, "search-main": 1, manual: 2 }
+       const ra = roleOrder[a.role] ?? 2
+       const rb = roleOrder[b.role] ?? 2
+       if (ra !== rb) return ra - rb
+
+       // Within same role: lowest score first
+       const sa = a.score ?? 0
+       const sb = b.score ?? 0
+       if (sa !== sb) return sa - sb
+
+       // Then oldest first
+       return a.attachedAt - b.attachedAt
+     })
+
+     for (const entry of candidates) {
+       if (
+         this._totalTokens <= this.config.maxTokens &&
+         this.entries.size <= this.config.maxChunks
+       ) {
+         break
+       }
+
+       this.entries.delete(entry.chunkId)
+       this._totalTokens -= entry.tokens
+     }
+   }
 
   // ── Helpers ─────────────────────────────────────────────────────────────