@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/rerank.js

@@ -1,90 +1,90 @@
-// Optional LLM rerank over search candidates.
-//
-// The lexical score cannot tell that a snippet mentioning a word in passing is less relevant
-// than one about it. A model can. This is OFF by default because it costs a call per search,
-// and it is strictly advisory: any failure - no model, unparseable reply, nonsense ordering -
-// leaves the deterministic ranking untouched. Memory search must never depend on a model.
-//
-// The reply protocol is deliberately trivial: a list of candidate NUMBERS in the wanted order.
-// An earlier nested-JSON contract failed repeatedly in practice, and an ordering is exactly the
-// kind of answer a short line of digits expresses perfectly.
-
-/** Only rerank when there is a real choice to make. */
-export const RERANK_MIN_CANDIDATES = 4
-/** Candidates sent to the model; more is slower with little gain. */
-export const RERANK_MAX_CANDIDATES = 20
-/** Characters of each snippet shown to the model. */
-export const RERANK_SNIPPET_CHARS = 220
-
-/** Instructions for the rerank model. */
-export const RERANK_INSTRUCTIONS = [
-  'You are reranking memory search results for relevance to a query.',
-  'You receive the query and a numbered list of candidate snippets from a durable memory store.',
-  '',
-  'Reply with the candidate NUMBERS in order of usefulness to the query, most useful first.',
-  '- One line, numbers separated by spaces or commas. Example: 3 1 4 2',
-  '- Include every number exactly once. Do not explain, do not add prose, do not omit any.',
-  '- Judge by what would actually help someone act on the query, not by keyword overlap.',
-  '- Prefer concrete facts, decisions and procedures over passing mentions.',
-].join('\n')
-
-/** Build the rerank prompt. Snippets are clipped so the prompt stays bounded. */
-export function buildRerankPrompt(query, candidates, options = {}) {
-  const limit = options.maxCandidates ?? RERANK_MAX_CANDIDATES
-  const chars = options.snippetChars ?? RERANK_SNIPPET_CHARS
-  const lines = [RERANK_INSTRUCTIONS, '', '--- QUERY ---', String(query ?? '').trim(), '', '--- CANDIDATES ---']
-  candidates.slice(0, limit).forEach((candidate, index) => {
-    const where = candidate.file ? candidate.file + ':' + candidate.line : ''
-    const text = String(candidate.snippet ?? '').replace(/\s+/g, ' ').trim().slice(0, chars)
-    lines.push((index + 1) + '. [' + where + '] ' + text)
-  })
-  lines.push('', 'Reply with the numbers in order. Nothing else.')
-  return lines.join('\n')
-}
-
-/**
- * Parse an ordering out of a model reply.
- * @param text - the reply.
- * @param count - how many candidates exist.
- * @returns a complete, duplicate-free 0-based ordering, or undefined when the reply is unusable.
- */
-export function parseRerankOrder(text, count) {
-  if (!Number.isFinite(count) || count < 2) return undefined
-  const numbers = (String(text ?? '').match(/\d+/g) ?? []).map(Number)
-  const order = []
-  const seen = new Set()
-  for (const n of numbers) {
-    if (n < 1 || n > count || seen.has(n)) continue
-    seen.add(n)
-    order.push(n - 1)
-  }
-  // Require a genuinely useful signal, not a token gesture. "1 2" out of four is agreement with
-  // the existing order, not a reranking, and accepting it would silently no-op every call.
-  const minimum = Math.max(2, Math.ceil(count * 0.75))
-  if (order.length < minimum) return undefined
-  // Anything the model left out keeps its original relative position, at the end.
-  for (let i = 0; i < count; i += 1) if (!seen.has(i + 1)) order.push(i)
-  return order
-}
-
-/**
- * Reorder hits by a model's judgement.
- * @param options.llm - (prompt) => Promise<string>; absent or throwing leaves the order alone.
- * @param options.enabled - master switch (default false).
- * @returns {Promise<{hits: object[], reranked: boolean, reason?: string}>}
- */
-export async function rerankHits(query, hits, options = {}) {
-  const list = Array.isArray(hits) ? hits : []
-  if (!options.enabled) return { hits: list, reranked: false, reason: 'disabled' }
-  if (list.length < (options.minCandidates ?? RERANK_MIN_CANDIDATES)) return { hits: list, reranked: false, reason: 'too-few' }
-  if (typeof options.llm !== 'function') return { hits: list, reranked: false, reason: 'no-model' }
-  let reply
-  try {
-    reply = await options.llm(buildRerankPrompt(query, list, options))
-  } catch (error) {
-    return { hits: list, reranked: false, reason: 'error: ' + String((error && error.message) || error).slice(0, 120) }
-  }
-  const order = parseRerankOrder(reply, list.length)
-  if (!order) return { hits: list, reranked: false, reason: 'unparseable' }
-  return { hits: order.map((i) => list[i]), reranked: true }
-}
+// Optional LLM rerank over search candidates.
+//
+// The lexical score cannot tell that a snippet mentioning a word in passing is less relevant
+// than one about it. A model can. This is OFF by default because it costs a call per search,
+// and it is strictly advisory: any failure - no model, unparseable reply, nonsense ordering -
+// leaves the deterministic ranking untouched. Memory search must never depend on a model.
+//
+// The reply protocol is deliberately trivial: a list of candidate NUMBERS in the wanted order.
+// An earlier nested-JSON contract failed repeatedly in practice, and an ordering is exactly the
+// kind of answer a short line of digits expresses perfectly.
+
+/** Only rerank when there is a real choice to make. */
+export const RERANK_MIN_CANDIDATES = 4
+/** Candidates sent to the model; more is slower with little gain. */
+export const RERANK_MAX_CANDIDATES = 20
+/** Characters of each snippet shown to the model. */
+export const RERANK_SNIPPET_CHARS = 220
+
+/** Instructions for the rerank model. */
+export const RERANK_INSTRUCTIONS = [
+  'You are reranking memory search results for relevance to a query.',
+  'You receive the query and a numbered list of candidate snippets from a durable memory store.',
+  '',
+  'Reply with the candidate NUMBERS in order of usefulness to the query, most useful first.',
+  '- One line, numbers separated by spaces or commas. Example: 3 1 4 2',
+  '- Include every number exactly once. Do not explain, do not add prose, do not omit any.',
+  '- Judge by what would actually help someone act on the query, not by keyword overlap.',
+  '- Prefer concrete facts, decisions and procedures over passing mentions.',
+].join('\n')
+
+/** Build the rerank prompt. Snippets are clipped so the prompt stays bounded. */
+export function buildRerankPrompt(query, candidates, options = {}) {
+  const limit = options.maxCandidates ?? RERANK_MAX_CANDIDATES
+  const chars = options.snippetChars ?? RERANK_SNIPPET_CHARS
+  const lines = [RERANK_INSTRUCTIONS, '', '--- QUERY ---', String(query ?? '').trim(), '', '--- CANDIDATES ---']
+  candidates.slice(0, limit).forEach((candidate, index) => {
+    const where = candidate.file ? candidate.file + ':' + candidate.line : ''
+    const text = String(candidate.snippet ?? '').replace(/\s+/g, ' ').trim().slice(0, chars)
+    lines.push((index + 1) + '. [' + where + '] ' + text)
+  })
+  lines.push('', 'Reply with the numbers in order. Nothing else.')
+  return lines.join('\n')
+}
+
+/**
+ * Parse an ordering out of a model reply.
+ * @param text - the reply.
+ * @param count - how many candidates exist.
+ * @returns a complete, duplicate-free 0-based ordering, or undefined when the reply is unusable.
+ */
+export function parseRerankOrder(text, count) {
+  if (!Number.isFinite(count) || count < 2) return undefined
+  const numbers = (String(text ?? '').match(/\d+/g) ?? []).map(Number)
+  const order = []
+  const seen = new Set()
+  for (const n of numbers) {
+    if (n < 1 || n > count || seen.has(n)) continue
+    seen.add(n)
+    order.push(n - 1)
+  }
+  // Require a genuinely useful signal, not a token gesture. "1 2" out of four is agreement with
+  // the existing order, not a reranking, and accepting it would silently no-op every call.
+  const minimum = Math.max(2, Math.ceil(count * 0.75))
+  if (order.length < minimum) return undefined
+  // Anything the model left out keeps its original relative position, at the end.
+  for (let i = 0; i < count; i += 1) if (!seen.has(i + 1)) order.push(i)
+  return order
+}
+
+/**
+ * Reorder hits by a model's judgement.
+ * @param options.llm - (prompt) => Promise<string>; absent or throwing leaves the order alone.
+ * @param options.enabled - master switch (default false).
+ * @returns {Promise<{hits: object[], reranked: boolean, reason?: string}>}
+ */
+export async function rerankHits(query, hits, options = {}) {
+  const list = Array.isArray(hits) ? hits : []
+  if (!options.enabled) return { hits: list, reranked: false, reason: 'disabled' }
+  if (list.length < (options.minCandidates ?? RERANK_MIN_CANDIDATES)) return { hits: list, reranked: false, reason: 'too-few' }
+  if (typeof options.llm !== 'function') return { hits: list, reranked: false, reason: 'no-model' }
+  let reply
+  try {
+    reply = await options.llm(buildRerankPrompt(query, list, options))
+  } catch (error) {
+    return { hits: list, reranked: false, reason: 'error: ' + String((error && error.message) || error).slice(0, 120) }
+  }
+  const order = parseRerankOrder(reply, list.length)
+  if (!order) return { hits: list, reranked: false, reason: 'unparseable' }
+  return { hits: order.map((i) => list[i]), reranked: true }
+}

package/src/search.js

@@ -1,75 +1,75 @@
-// Search: FTS match -> scope filter -> rankBlend -> citations. In-process, read-only.
-//
-// Two indexes back it. The word index (unicode61) serves normal queries and ranks by bm25. The
-// trigram index serves SUBSTRING queries - scripts written without spaces, which the word
-// tokenizer cannot express at all. A word query that finds nothing also retries as a substring,
-// so a partial word still matches without paying for the trigram scan on every search.
-import { existsSync } from 'node:fs'
-import { DatabaseSync } from 'node:sqlite'
-import { buildFtsQuery, buildIndex, buildLikeQuery, buildTrigramQuery, indexPath, needsSubstring, SUBSTRING_TABLE } from './fts.js'
-import { buildLedger } from './ledger.js'
-import { rankBlend } from './rank.js'
-
-/** Rows pulled from the word index before ranking. */
-const CANDIDATES = 200
-
-/**
- * A LIKE scan over the indexed lines. Used only when a MATCH cannot express the query: a
- * no-space script shorter than the trigram minimum. Bounded by the same candidate cap.
- */
-function likeRows(db, pattern, table) {
-  try {
-    return db.prepare(
-      'SELECT file, line, section, content, 0 AS rank FROM ' + table + ' WHERE content LIKE ? ESCAPE \'\\\' LIMIT ?'
-    ).all(pattern, CANDIDATES)
-  } catch { return [] }
-}
-
-/** One MATCH against one table; returns [] when the table or expression is unusable. */
-function matchRows(db, expression, table) {
-  try {
-    return db.prepare(
-      'SELECT file, line, section, content, bm25(' + table + ') AS rank FROM ' + table + ' WHERE ' + table + ' MATCH ? ORDER BY rank LIMIT ?'
-    ).all(expression, CANDIDATES)
-  } catch { return [] }
-}
-
-export function search(store, query, { limit = 10, scope, key } = {}) {
-  const dbPath = indexPath(store.root)
-  if (!existsSync(dbPath)) buildIndex(store.root)
-  const db = new DatabaseSync(dbPath, { readOnly: true })
-  try {
-    let rows = []
-    if (needsSubstring(query)) {
-      // No-space script: only the substring index can match it.
-      const expression = buildTrigramQuery(String(query).trim())
-      if (expression) rows = matchRows(db, expression, SUBSTRING_TABLE)
-      // Too short for trigram (common for two-character CJK words): scan instead.
-      if (rows.length === 0) {
-        const pattern = buildLikeQuery(query)
-        if (pattern) rows = likeRows(db, pattern, SUBSTRING_TABLE)
-      }
-    } else {
-      const match = buildFtsQuery(query)
-      if (match) rows = matchRows(db, match, 'mem_fts')
-      if (rows.length === 0) {
-        // A word query that matched nothing may still be a partial word: retry as substring.
-        const expression = buildTrigramQuery(String(query).trim())
-        if (expression) rows = matchRows(db, expression, SUBSTRING_TABLE)
-        if (rows.length === 0) {
-          const pattern = buildLikeQuery(query)
-          if (pattern) rows = likeRows(db, pattern, SUBSTRING_TABLE)
-        }
-      }
-    }
-    if (rows.length === 0) return []
-    let filtered = rows
-    if (scope === 'global') filtered = rows.filter((r) => r.file.startsWith('global/'))
-    else if (scope === 'workspace') filtered = rows.filter((r) => r.file.startsWith('workspaces/' + (key ?? '') + '/'))
-    const hits = filtered.map((r) => ({ file: r.file, line: r.line, section: r.section, snippet: String(r.content).trim() }))
-    return rankBlend(hits, buildLedger(store.root)).slice(0, limit)
-      .map((h) => ({ file: h.file, line: h.line, section: h.section ?? '', snippet: h.snippet, id: h.id ?? '', score: Math.round(h.score * 1000) / 1000 }))
-  } finally {
-    db.close()
-  }
-}
+// Search: FTS match -> scope filter -> rankBlend -> citations. In-process, read-only.
+//
+// Two indexes back it. The word index (unicode61) serves normal queries and ranks by bm25. The
+// trigram index serves SUBSTRING queries - scripts written without spaces, which the word
+// tokenizer cannot express at all. A word query that finds nothing also retries as a substring,
+// so a partial word still matches without paying for the trigram scan on every search.
+import { existsSync } from 'node:fs'
+import { DatabaseSync } from 'node:sqlite'
+import { buildFtsQuery, buildIndex, buildLikeQuery, buildTrigramQuery, indexPath, needsSubstring, SUBSTRING_TABLE } from './fts.js'
+import { buildLedger } from './ledger.js'
+import { rankBlend } from './rank.js'
+
+/** Rows pulled from the word index before ranking. */
+const CANDIDATES = 200
+
+/**
+ * A LIKE scan over the indexed lines. Used only when a MATCH cannot express the query: a
+ * no-space script shorter than the trigram minimum. Bounded by the same candidate cap.
+ */
+function likeRows(db, pattern, table) {
+  try {
+    return db.prepare(
+      'SELECT file, line, section, content, 0 AS rank FROM ' + table + ' WHERE content LIKE ? ESCAPE \'\\\' LIMIT ?'
+    ).all(pattern, CANDIDATES)
+  } catch { return [] }
+}
+
+/** One MATCH against one table; returns [] when the table or expression is unusable. */
+function matchRows(db, expression, table) {
+  try {
+    return db.prepare(
+      'SELECT file, line, section, content, bm25(' + table + ') AS rank FROM ' + table + ' WHERE ' + table + ' MATCH ? ORDER BY rank LIMIT ?'
+    ).all(expression, CANDIDATES)
+  } catch { return [] }
+}
+
+export function search(store, query, { limit = 10, scope, key } = {}) {
+  const dbPath = indexPath(store.root)
+  if (!existsSync(dbPath)) buildIndex(store.root)
+  const db = new DatabaseSync(dbPath, { readOnly: true })
+  try {
+    let rows = []
+    if (needsSubstring(query)) {
+      // No-space script: only the substring index can match it.
+      const expression = buildTrigramQuery(String(query).trim())
+      if (expression) rows = matchRows(db, expression, SUBSTRING_TABLE)
+      // Too short for trigram (common for two-character CJK words): scan instead.
+      if (rows.length === 0) {
+        const pattern = buildLikeQuery(query)
+        if (pattern) rows = likeRows(db, pattern, SUBSTRING_TABLE)
+      }
+    } else {
+      const match = buildFtsQuery(query)
+      if (match) rows = matchRows(db, match, 'mem_fts')
+      if (rows.length === 0) {
+        // A word query that matched nothing may still be a partial word: retry as substring.
+        const expression = buildTrigramQuery(String(query).trim())
+        if (expression) rows = matchRows(db, expression, SUBSTRING_TABLE)
+        if (rows.length === 0) {
+          const pattern = buildLikeQuery(query)
+          if (pattern) rows = likeRows(db, pattern, SUBSTRING_TABLE)
+        }
+      }
+    }
+    if (rows.length === 0) return []
+    let filtered = rows
+    if (scope === 'global') filtered = rows.filter((r) => r.file.startsWith('global/'))
+    else if (scope === 'workspace') filtered = rows.filter((r) => r.file.startsWith('workspaces/' + (key ?? '') + '/'))
+    const hits = filtered.map((r) => ({ file: r.file, line: r.line, section: r.section, snippet: String(r.content).trim() }))
+    return rankBlend(hits, buildLedger(store.root)).slice(0, limit)
+      .map((h) => ({ file: h.file, line: h.line, section: h.section ?? '', snippet: h.snippet, id: h.id ?? '', score: Math.round(h.score * 1000) / 1000 }))
+  } finally {
+    db.close()
+  }
+}

package/src/select.js

@@ -1,57 +1,57 @@
-// Which memory goes in front of the agent.
-//
-// This used to be `.slice(-5)`: the last five entries in file order, whatever the turn was
-// about. Measured, that meant the SAME five learnings arrived every turn through an entire
-// queue-rewrite session, while the entries that actually described the work - the orphaned-as-
-// retries bug, the state list, the queue design decisions - were never shown at all. A fixed
-// dump is worse than no memory, because it looks like recall.
-//
-// The index that answers this already existed. Selection now asks it a question.
-import { search } from './search.js'
-
-/**
- * The question to ask the index.
- *
- * The live TASK outranks the session GOAL, because a goal is set once and then ages: a goal
- * recorded at the start of a long session describes what the session began as, not what the
- * agent is doing now. The goal is kept as a fallback for a turn with no task recorded.
- */
-export function relevanceQuery(workingMemory, goal) {
-  const task = (workingMemory?.sections ?? []).find((s) => /^task$/i.test(s.name))?.content ?? ''
-  const next = (workingMemory?.sections ?? []).find((s) => /^next steps$/i.test(s.name))?.content ?? ''
-  const parts = [task, next, goal].map((s) => String(s ?? '').trim()).filter(Boolean)
-  return parts.join(' ').slice(0, 400)
-}
-
-/**
- * Choose the entries to show, preferring RELEVANCE and falling back to recency.
- *
- * The fallback is not decoration. With no query, an unbuilt index, or nothing matching, the
- * previous behaviour is exactly what should happen - a turn should never get LESS context
- * because a ranking attempt found nothing.
- * @returns { entries, relevant } - relevant says which rule actually ran, so a caller can say so.
- */
-export function selectEntries(store, pool, query, limit, options = {}) {
-  const fallback = { entries: pool.slice(-limit), relevant: false }
-  if (!query || pool.length <= limit) return fallback;
-  try {
-    // A hit is LINE-level; the pool is entry-level, so hits are mapped onto files and each file
-    // keeps its BEST rank. One strongly matching line should lift its entry, not be diluted by
-    // the other lines of the same file.
-    const best = new Map()
-    for (const hit of search(store, query, { limit: limit * 8, scope: options.scope, key: options.key })) {
-      const file = String(hit.file ?? '').split('\\').join('/')
-      const rank = Number(hit.rank ?? 0)
-      if (!best.has(file) || rank > best.get(file)) best.set(file, rank)
-    }
-    if (best.size === 0) return fallback
-    const ranked = pool
-      .filter((entry) => best.has(String(entry.file ?? '').split('\\').join('/')))
-      .sort((a, b) => (best.get(b.file) ?? 0) - (best.get(a.file) ?? 0))
-    if (ranked.length === 0) return fallback
-    return { entries: ranked.slice(0, limit), relevant: true }
-  } catch {
-    // An index that is missing or mid-rebuild must not cost the agent its context.
-    return fallback
-  }
-}
+// Which memory goes in front of the agent.
+//
+// This used to be `.slice(-5)`: the last five entries in file order, whatever the turn was
+// about. Measured, that meant the SAME five learnings arrived every turn through an entire
+// queue-rewrite session, while the entries that actually described the work - the orphaned-as-
+// retries bug, the state list, the queue design decisions - were never shown at all. A fixed
+// dump is worse than no memory, because it looks like recall.
+//
+// The index that answers this already existed. Selection now asks it a question.
+import { search } from './search.js'
+
+/**
+ * The question to ask the index.
+ *
+ * The live TASK outranks the session GOAL, because a goal is set once and then ages: a goal
+ * recorded at the start of a long session describes what the session began as, not what the
+ * agent is doing now. The goal is kept as a fallback for a turn with no task recorded.
+ */
+export function relevanceQuery(workingMemory, goal) {
+  const task = (workingMemory?.sections ?? []).find((s) => /^task$/i.test(s.name))?.content ?? ''
+  const next = (workingMemory?.sections ?? []).find((s) => /^next steps$/i.test(s.name))?.content ?? ''
+  const parts = [task, next, goal].map((s) => String(s ?? '').trim()).filter(Boolean)
+  return parts.join(' ').slice(0, 400)
+}
+
+/**
+ * Choose the entries to show, preferring RELEVANCE and falling back to recency.
+ *
+ * The fallback is not decoration. With no query, an unbuilt index, or nothing matching, the
+ * previous behaviour is exactly what should happen - a turn should never get LESS context
+ * because a ranking attempt found nothing.
+ * @returns { entries, relevant } - relevant says which rule actually ran, so a caller can say so.
+ */
+export function selectEntries(store, pool, query, limit, options = {}) {
+  const fallback = { entries: pool.slice(-limit), relevant: false }
+  if (!query || pool.length <= limit) return fallback;
+  try {
+    // A hit is LINE-level; the pool is entry-level, so hits are mapped onto files and each file
+    // keeps its BEST rank. One strongly matching line should lift its entry, not be diluted by
+    // the other lines of the same file.
+    const best = new Map()
+    for (const hit of search(store, query, { limit: limit * 8, scope: options.scope, key: options.key })) {
+      const file = String(hit.file ?? '').split('\\').join('/')
+      const rank = Number(hit.rank ?? 0)
+      if (!best.has(file) || rank > best.get(file)) best.set(file, rank)
+    }
+    if (best.size === 0) return fallback
+    const ranked = pool
+      .filter((entry) => best.has(String(entry.file ?? '').split('\\').join('/')))
+      .sort((a, b) => (best.get(b.file) ?? 0) - (best.get(a.file) ?? 0))
+    if (ranked.length === 0) return fallback
+    return { entries: ranked.slice(0, limit), relevant: true }
+  } catch {
+    // An index that is missing or mid-rebuild must not cost the agent its context.
+    return fallback
+  }
+}

package/src/session.js

@@ -1,60 +1,60 @@
-// Resolve a session's working directory to a memory workspace key.
-// A session belongs to a workspace only when DSH's own workspaceRegistry resolves its
-// cwd to a registered workspace; otherwise it falls back to the global layer.
-import { basename } from 'node:path'
-import { associate, listWorkspaces, resolveKeyFor } from './workspace.js'
-
-/**
- * True when a session was created as a subagent child.
- *
- * Memory belongs to the MAIN agent. A subagent is a short-lived delegate working inside a task
- * the parent already owns, and the parent's own transcript carries the delegation and its
- * result, so recording the child as well duplicates the same work and buries the parent's
- * account of it. Measured here: of 306 sessions with no memory, every one sampled from the
- * post-install group was a subagent.
- *
- * Both fields are checked because they are set independently: `delegationDepth` is the recursion
- * budget (absent on a resumed top-level session, parent+1 on a child), and `origin` is the
- * product classification. Either one being present means the session is not the main agent.
- */
-export function isSubagentSession(session) {
-  const header = session?.header
-  if (!header) return false
-  if (header.origin === 'subagent') return true
-  return typeof header.delegationDepth === 'number' && header.delegationDepth > 0
-}
-
-/**
- * The main-agent predicate, phrased for the call sites that guard a WRITE.
- * Reads are harmless from anywhere; only recording is restricted.
- */
-export function isMainAgentSession(session) { return !isSubagentSession(session) }
-
-/** Sync fallback (no workspaceRegistry): basename-derived key, or 'global'. */
-export function workspaceFromSession(store, session) {
-  const cwd = session?.header?.cwd
-  if (!cwd) return 'global'
-  return resolveKeyFor(store.root, { cwd, basename: basename(cwd) }) ?? 'global'
-}
-
-/**
- * Resolve + lazily associate a session's workspace. Only a DSH-registered workspace
- * (resolveByPath hit) triggers association; everything else stays global.
- */
-export async function autoAssociateSession(store, ctx, session) {
-  const cwd = session?.header?.cwd
-  if (!cwd) return 'global'
-  const registry = ctx?.get('workspaceRegistry')
-  if (!registry || typeof registry.resolveByPath !== 'function') return 'global'
-  let ws
-  try { ws = await registry.resolveByPath(cwd) } catch { ws = undefined }
-  if (!ws) return 'global'
-  const key = resolveKeyFor(store.root, { cwd: ws.path, basename: basename(ws.path) })
-  if (!key) return 'global'
-  const known = listWorkspaces(store).some((w) => w.key === key)
-  if (!known) {
-    try { associate(store, { key, title: ws.title ?? key, cwd: ws.path, workspaceId: ws.id }) }
-    catch { /* keep going; the key is still usable */ }
-  }
-  return key
-}
+// Resolve a session's working directory to a memory workspace key.
+// A session belongs to a workspace only when DSH's own workspaceRegistry resolves its
+// cwd to a registered workspace; otherwise it falls back to the global layer.
+import { basename } from 'node:path'
+import { associate, listWorkspaces, resolveKeyFor } from './workspace.js'
+
+/**
+ * True when a session was created as a subagent child.
+ *
+ * Memory belongs to the MAIN agent. A subagent is a short-lived delegate working inside a task
+ * the parent already owns, and the parent's own transcript carries the delegation and its
+ * result, so recording the child as well duplicates the same work and buries the parent's
+ * account of it. Measured here: of 306 sessions with no memory, every one sampled from the
+ * post-install group was a subagent.
+ *
+ * Both fields are checked because they are set independently: `delegationDepth` is the recursion
+ * budget (absent on a resumed top-level session, parent+1 on a child), and `origin` is the
+ * product classification. Either one being present means the session is not the main agent.
+ */
+export function isSubagentSession(session) {
+  const header = session?.header
+  if (!header) return false
+  if (header.origin === 'subagent') return true
+  return typeof header.delegationDepth === 'number' && header.delegationDepth > 0
+}
+
+/**
+ * The main-agent predicate, phrased for the call sites that guard a WRITE.
+ * Reads are harmless from anywhere; only recording is restricted.
+ */
+export function isMainAgentSession(session) { return !isSubagentSession(session) }
+
+/** Sync fallback (no workspaceRegistry): basename-derived key, or 'global'. */
+export function workspaceFromSession(store, session) {
+  const cwd = session?.header?.cwd
+  if (!cwd) return 'global'
+  return resolveKeyFor(store.root, { cwd, basename: basename(cwd) }) ?? 'global'
+}
+
+/**
+ * Resolve + lazily associate a session's workspace. Only a DSH-registered workspace
+ * (resolveByPath hit) triggers association; everything else stays global.
+ */
+export async function autoAssociateSession(store, ctx, session) {
+  const cwd = session?.header?.cwd
+  if (!cwd) return 'global'
+  const registry = ctx?.get('workspaceRegistry')
+  if (!registry || typeof registry.resolveByPath !== 'function') return 'global'
+  let ws
+  try { ws = await registry.resolveByPath(cwd) } catch { ws = undefined }
+  if (!ws) return 'global'
+  const key = resolveKeyFor(store.root, { cwd: ws.path, basename: basename(ws.path) })
+  if (!key) return 'global'
+  const known = listWorkspaces(store).some((w) => w.key === key)
+  if (!known) {
+    try { associate(store, { key, title: ws.title ?? key, cwd: ws.path, workspaceId: ws.id }) }
+    catch { /* keep going; the key is still usable */ }
+  }
+  return key
+}