@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/host.js

@@ -1,866 +1,884 @@
-// DSH host wiring: deep hooks into session lifecycle, agent pre-step, LLM, and
-// subprocess. This is the only module that touches DSH services directly.
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { BlockAssembler, ReasoningEffortId, createUserMessage } from '@deepseek-ai/dsh-llm'
-import { captureSession, pendingDigests, pruneDigests } from './capture.js'
-import { runConsolidation } from './consolidate-run.js'
-import { runRefresh } from './refresh.js'
-import { buildInjectionText } from './inject.js'
-import { parseModelRef } from './defaults.js'
-import { ingestHistory } from './history.js'
-import { rerankHits } from './rerank.js'
-import { isSubagentSession } from './session.js'
-import { buildModelLadder, createModelMemory, runLadder } from './models.js'
-import { due, problems, readQueue, reapStalled, REASONS, STATES, summarize as summarizeQueue, transition } from './queue.js'
-import { planRecovery, recoverOne } from './recover.js'
-import { logRun, noteActivity, readMetrics, record } from './telemetry.js'
-import { GitRunner, SyncScheduler, classifyGitResult, commitMessage } from './git.js'
-import { buildMap } from './map.js'
-import { backupTasks, defaultSchedulePath, planRestore, readScheduleStore } from './tasks.js'
-import { autoAssociateSession } from './session.js'
-import { readAssociations } from './workspace.js'
-
-const PLUGIN = 'dsh-memory'
-
-/** How often the idle ticker checks whether a cadence is due (the cadences self-throttle). */
-const MAP_PUBLISH_MS = 60 * 1000
-const TASKS_BACKUP_MS = 30 * 60 * 1000
-const IDLE_TICK_MS = 60_000
-
-function makeGitRunner(ctx) {
-  const subprocess = ctx.get('subprocess')
-  if (!subprocess || typeof subprocess.resolveExecutable !== 'function' || typeof subprocess.spawn !== 'function') return null
-  let executablePromise
-  const run = async (argv, opts = {}) => {
-    if (!executablePromise) executablePromise = subprocess.resolveExecutable('git', undefined, undefined).catch(() => null)
-    const executable = await executablePromise
-    if (!executable) return { exitCode: 127, stdout: '', stderr: 'git unavailable' }
-    try {
-      const handle = subprocess.spawn({
-        argv: [executable, ...argv],
-        cwd: opts.cwd,
-        stdio: { stdin: 'ignore', stdout: { maxBytes: 4 * 1024 * 1024 }, stderr: { maxBytes: 16 * 1024 } },
-        graceMs: 2000,
-        env: { GIT_CONFIG_COUNT: '0', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C' },
-      })
-      const outcome = await handle.done
-      const stdout = handle.collected?.stdout?.readFrom?.(0)?.text ?? ''
-      const stderr = handle.collected?.stderr?.readFrom?.(0)?.text ?? ''
-      return { exitCode: outcome?.exitCode ?? null, stdout, stderr }
-    } catch (error) {
-      return { exitCode: 1, stdout: '', stderr: String(error) }
-    }
-  }
-  return new GitRunner(run)
-}
-
-function resolveTarget(agent) {
-  const h = agent?.session?.requestHeader?.()?.config
-  if (h && h.provider && h.model) return { provider: h.provider, model: h.model }
-  const o = agent?.options
-  if (o && o.provider && o.model) return { provider: o.provider, model: o.model }
-  return undefined
-}
-
-export function wireHost(ctx, store, cfg) {
-  const keyBySession = new Map()
-  const scheduler = new SyncScheduler({ commitDebounceMs: cfg.commitDebounceMs, syncIntervalMs: cfg.autoSyncIntervalMs })
-  const captureThrottle = new Map()
-  const injectionThrottle = new Map()
-  let lastConsolidateAttempt = 0
-  let lastRefreshAttempt = 0
-  let lastTasksBackupAttempt = 0
-  let restoreAttempted = false
-  const lastMapPublish = new Map()
-  const lastMapSignature = new Map()
-  let lastHistoryAttempt = 0
-  let syncInFlight = false
-
-  const git = makeGitRunner(ctx)
-  const llmService = ctx.get('llm')
-
-  /** Which model last worked, and which recently returned nothing. Learned, not configured. */
-  const modelMemory = createModelMemory()
-  let memoryPreferred
-  let availableCache
-
-  /**
-   * Every model this deployment can actually route to right now.
-   *
-   * Read from the live registry rather than a constant: providers appear and disappear, a
-   * subscription lapses, and role-model routing changes what is reachable. A short cache keeps
-   * a burst of memory writes from re-enumerating providers on every call, and a failure to
-   * enumerate is not fatal - the ladder still has the configured and session routes.
-   */
-  async function listAvailableModels({ maxAgeMs = 60000 } = {}) {
-    const now = Date.now()
-    if (availableCache && now - availableCache.at < maxAgeMs) return availableCache.models
-    const models = []
-    try {
-      const providers = llmService.listProviders()
-      for (const provider of providers ?? []) {
-        try {
-          const list = await llmService.listModels(provider.id)
-          for (const model of list ?? []) models.push({ provider: provider.id, model: model.id })
-        } catch { /* one unroutable provider must not empty the ladder */ }
-      }
-    } catch { /* fall through with whatever was collected */ }
-    availableCache = { at: now, models }
-    return models
-  }
-
-
-  const runLlm = async (target, prompt, purpose = 'memory-consolidation', maxTokens = 4000) => {
-    if (!llmService) throw new Error('llm service unavailable')
-
-    /** One attempt against ONE model, with the reasoning-effort recovery. */
-    const attemptOn = async (model, controls, called) => {
-      called.push({ provider: model.provider, model: model.model })
-      record(store.root, 'model-call', { modelCalls: 1, purpose, detail: { provider: model.provider, model: model.model } })
-      const assembler = new BlockAssembler()
-      const messages = [{ role: 'user', content: [{ type: 'text', text: prompt }] }]
-      for await (const chunk of llmService.stream({
-        provider: model.provider, model: model.model, messages, maxTokens, purpose, ...controls,
-      })) assembler.push(chunk)
-      // Text blocks only. A reasoning model streams its thinking as `reasoning` blocks;
-      // folding those into the reply prepends prose to the answer, which makes any
-      // "parse the JSON reply" step match the wrong braces and fail. Worse, a model that
-      // spends its whole budget reasoning returns NO text block at all - which is exactly
-      // the failure the ladder exists to route around.
-      return assembler.blocks().filter((b) => b && b.type === 'text').map((b) => b.text || '').join('\n').trim()
-    }
-
-    /**
-     * One model, tried at the memory reasoning effort and then with reasoning off.
-     * Memory work is extraction: it must not run at the session's reasoning budget, and a
-     * model that rejects the effort outright is retried without the control rather than
-     * failing every memory write.
-     */
-    const attemptModel = async (model) => {
-      const called = []
-      const effort = cfg.memoryReasoningEffort
-      if (effort) {
-        let text = ''
-        try {
-          text = await attemptOn(model, { reasoningEffort: ReasoningEffortId(effort) }, called)
-        } catch (error) {
-          const message = String((error && error.message) || error)
-          if (!/UNSUPPORTED_REASONING_EFFORT|does not support reasoning effort/i.test(message)) {
-            modelCalls.push(...called)
-            throw error
-          }
-          ctx.logger.debug('dsh-memory: ' + model.model + ' does not support reasoning effort "' + effort + '"; retrying without it')
-          const plain = await attemptOn(model, {}, called)
-          modelCalls.push(...called)
-          return plain
-        }
-        if (text !== '') { modelCalls.push(...called); return text }
-        ctx.logger.debug('dsh-memory: ' + model.model + ' returned no text at effort "' + effort + '"; retrying with reasoning off')
-        const off = await attemptOn(model, { reasoningEffort: ReasoningEffortId('off') }, called)
-        modelCalls.push(...called)
-        return off
-      }
-      const plain = await attemptOn(model, {}, called)
-      modelCalls.push(...called)
-      return plain
-    }
-
-    // Resolve the ladder from the LIVE registry: the configured memory model, then the
-    // session's route, then everything else routable. The model list is deployment state,
-    // not a constant, so it is read per call and the winner is remembered.
-    const available = await listAvailableModels()
-    const ladder = buildModelLadder({
-      preferred: memoryPreferred ?? parseModelRef(cfg.summaryModel),
-      session: target,
-      available,
-    })
-    if (ladder.length === 0) throw new Error('dsh-memory: no routable model for memory work')
-    const modelCalls = []
-    const outcome = await runLadder({
-      ladder,
-      memory: modelMemory,
-      attempt: attemptModel,
-      onAttempt: (model, text, error) => {
-        if (error) record(store.root, 'model-failed', { detail: { provider: model.provider, model: model.model, error: String(error.message || error).slice(0, 120) } })
-        else if (text === '') record(store.root, 'model-empty', { detail: { provider: model.provider, model: model.model } })
-      },
-    })
-    if (outcome.text !== '') {
-      if (outcome.tried.length > 1) {
-        logRun(store.root, 'model-fallback', {
-          purpose,
-          used: outcome.target.provider + '/' + outcome.target.model,
-          skipped: outcome.tried.slice(0, -1).map((x) => x.target.provider + '/' + x.target.model).join(','),
-        })
-      }
-      memoryPreferred = outcome.target
-      return outcome.text
-    }
-    // Every model returned nothing. That is a deployment problem, not a verdict about the
-    // material, and it is reported as an error so the session is retried rather than settled.
-    throw new Error('dsh-memory: no model returned text (' + outcome.tried.map((x) => x.target.model + (x.error ? ':' + x.error : ':empty')).join(', ') + ')')
-  }
-/** Summarizer bound to the session's own model; undefined when the session is unrouted. */
-  /** Model for memory writes: the configured memory model, else the agent's route. */
-  function memoryTarget(agent) {
-    return parseModelRef(cfg.summaryModel) ?? resolveTarget(agent)
-  }
-
-  /** The configured memory model wins; otherwise the session's own model. */
-  function summaryLlm(session) {
-    const configured = parseModelRef(cfg.summaryModel)
-    if (configured) return (prompt) => runLlm(configured, prompt, 'memory-summary', 1200)
-    const header = session?.requestHeader?.()?.config
-    if (!header || !header.provider || !header.model) return undefined
-    return (prompt) => runLlm({ provider: header.provider, model: header.model }, prompt, 'memory-summary', 1200)
-  }
-
-  async function resolveKey(session) {
-    const cached = keyBySession.get(session.id)
-    if (cached) return cached
-    const key = await autoAssociateSession(store, ctx, session).catch(() => 'global')
-    keyBySession.set(session.id, key)
-    return key
-  }
-
-  /**
-   * Record the repository commit history for an agent's workspace. The workspace key comes
-   * from the session; the repository path comes from the device-local association, so the
-   * plugin never has to guess where the checkout lives.
-   */
-  async function historyOf(agent, { limit } = {}) {
-    const workspace = await workspaceOf(agent)
-    if (!workspace) return { ok: false, reason: 'no workspace for this session', added: 0 }
-    const path = readAssociations(store.root)[workspace]?.path
-    if (!path) return { ok: false, reason: 'no local folder associated with ' + workspace, added: 0 }
-    return ingestHistory(store.root, workspace, path, (argv, opts) => git.run(argv, opts), { limit })
-  }
-
-  /** The workspace key for an agent's session, or undefined when it has none. */
-  async function workspaceOf(agent) {
-    const session = agent && agent.session
-    if (!session) return undefined
-    const key = await resolveKey(session).catch(() => 'global')
-    return key === 'global' ? undefined : key
-  }
-
-  function maybeCapture(session) {
-    // Memory belongs to the MAIN agent. A subagent's work is already described in the parent
-    // transcript that delegated it, so capturing the child duplicates that work and buries the
-    // parent's account of it.
-    if (isSubagentSession(session)) return
-    const id = session.id
-    const now = Date.now()
-    if (now - (captureThrottle.get(id) ?? 0) < cfg.autoCaptureIntervalMs) return
-    captureThrottle.set(id, now)
-    const sessionQuery = ctx.get('sessionQuery')
-    if (!sessionQuery) return
-    const options = {
-      maxUserTurns: cfg.digestMaxUserTurns,
-      maxAssistantGists: cfg.digestMaxAssistantGists,
-      maxMessageChars: cfg.digestMaxMessageChars,
-      maxBytes: cfg.digestMaxBytes,
-      maxBullets: cfg.summaryMaxBullets,
-    }
-    void captureSession(store, { sessionQuery, llm: summaryLlm(session) }, session, options)
-      .then((r) => {
-        if (r && r.changed) scheduler.markDirty()
-        if (r && r.summarySource === 'thin') record(store.root, 'summary-skipped', { saved: 'thin', detail: { sessionId: r.sessionId } })
-        if (r && r.summarySource === 'skipped') record(store.root, 'summary-skipped', { saved: 'trivial', detail: { sessionId: r.sessionId } })
-        if (r && r.summarySource) logRun(store.root, 'capture', { sessionId: r.sessionId, summarySource: r.summarySource, fresh: r.fresh, bullets: r.bullets })
-      })
-      .catch((error) => ctx.logger.warn('dsh-memory: capture failed: ' + (error && error.message)))
-  }
-
-  /**
-   * What the consolidation cadence should act on now.
-   *
-   * The watchdog runs FIRST, because an entry stranded mid-stage by a crash is invisible to every
-   * other query: it is neither pending nor failed, so nothing would ever move it.
-   *
-   * Failures whose backoff has expired come back here automatically, which is what makes 'we
-   * cannot let things stay failed' true in the running system rather than only in the model.
-   * Entries that have spent their budget are abandoned explicitly, so the queue drains instead of
-   * accumulating work that can never succeed.
-   */
-  /**
-   * Recovery, exposed to the tool and to the cadence's parking decision.
-   *
-   * The cadence can PARK a large recovery but can never PERFORM one: approval.request() throws
-   * outside an open turn, and the idle ticker has no turn. That is a hard boundary rather than a
-   * limitation to route around, so the cadence's job is to make the work visible and a live tool
-   * call is the only path.
-   */
-  const recoverNow = {
-    plan() {
-      const p = planRecovery(store.root, { thresholdBytes: cfg.recoverApprovalThresholdBytes })
-      return { total: p.total, recoverable: p.recoverable, oversized: p.oversized, missing: p.missing, thresholdBytes: p.threshold }
-    },
-    async run(args, exec) {
-      const p = planRecovery(store.root, { thresholdBytes: cfg.recoverApprovalThresholdBytes })
-      const candidates = args.id
-        ? p.entries.filter((e) => e.id === args.id)
-        : p.entries.filter((e) => !e.needsApproval).sort((a, b) => (a.bytes ?? 0) - (b.bytes ?? 0)).slice(0, args.limit ?? 1)
-      const recovered = []
-      const declined = []
-      for (const target of candidates) {
-        if (target.needsApproval) {
-          const approval = ctx.get('approval')
-          if (!approval) { declined.push({ id: target.id, why: 'no approval service' }); continue }
-          let outcome
-          try {
-            outcome = await approval.request({
-              agent: exec?.agent,
-              toolName: 'memory_recover',
-              reason: 'Rebuild a ' + (target.bytes ? Math.round(target.bytes / 1048576) + 'MB' : 'large') + ' session digest',
-            })
-          } catch (error) {
-            // Outside an open turn. Refusing is the whole point: an unapproved large recovery must
-            // not proceed on the grounds that asking was impossible.
-            declined.push({ id: target.id, why: 'cannot ask outside a turn' })
-            continue
-          }
-          // ONLY an explicit once-grant proceeds. 'unavailable' FAILS CLOSED, by design.
-          if (outcome !== 'allowed-once') { declined.push({ id: target.id, why: String(outcome) }); continue }
-        }
-        try {
-          await recoverOne(store, services, target.id, { cfg, now: () => Date.now() })
-          recovered.push({ id: target.id, bytes: target.bytes })
-          logRun(store.root, 'recover', { count: 1, detail: { id: target.id } })
-        } catch (error) {
-          declined.push({ id: target.id, why: 'recovery failed', error: String((error && error.message) || error).slice(0, 140) })
-        }
-      }
-      return { mode: 'run', ...this.plan(), recovered, declined }
-    },
-  }
-
-  function dueWork(now = Date.now()) {
-    const recovered = reapStalled(store.root, now)
-    if (recovered.length) logRun(store.root, 'queue-reaped', { count: recovered.length, detail: { ids: recovered.slice(0, 10).join(',') } })
-    // An orphan too large to rebuild unasked is PARKED, not left looking like ordinary waiting
-    // work. Parked is visible and costs nothing; the tool is the only thing that can proceed, and
-    // it has to be able to find them.
-    for (const target of planRecovery(store.root, { thresholdBytes: cfg.recoverApprovalThresholdBytes }).entries) {
-      if (!target.needsApproval) continue
-      const parked = readQueue(store.root).get(target.id)
-      if (!parked || parked.state !== STATES.ORPHANED) continue
-      transition(store.root, target.id, STATES.HELD, { reason: REASONS.NEEDS_APPROVAL, detail: { sourceBytes: target.bytes ?? null } })
-    }
-    const work = due(store.root, now)
-    const abandon = []
-    const digests = []
-    for (const item of work) {
-      if (item.action === 'abandon') { abandon.push(item.entry); continue }
-      // A recovery is not a digest: consolidating it would spend a call on material that is known
-      // to be missing. The parking loop above has already handled the ones that need approval.
-      if (item.action === 'recover') continue
-      digests.push({ id: item.entry.id, tier: item.entry.detail?.tier })
-    }
-    for (const entry of abandon) {
-      // Out of the retry loop, but never hidden: problems() reports it and status counts it.
-      transition(store.root, entry.id, STATES.ABANDONED, { reason: entry.reason ?? 'attempts-exhausted' })
-    }
-    if (abandon.length) logRun(store.root, 'queue-abandoned', { count: abandon.length })
-    return digests
-  }
-
-  function maybeConsolidate(agent) {
-    const now = Date.now()
-    if (now - lastConsolidateAttempt < cfg.autoConsolidateIntervalMs) return
-    lastConsolidateAttempt = now
-    // The queue decides what is due: waiting work, plus failures whose backoff expired. A count of
-    // pending digests would miss exactly the work this phase exists to bring back.
-    const work = dueWork(now)
-    if (work.length < cfg.autoConsolidateMinPending) return
-    const target = memoryTarget(agent)
-    if (!target) return
-    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
-    void runConsolidation(store, {
-      llm, digests: work, batchSize: cfg.autoConsolidateBatchSize,
-      maxPromptBytes: cfg.consolidateMaxPromptBytes, maxDigestBytes: cfg.consolidateMaxDigestBytes,
-    })
-      .then((r) => { scheduler.markDirty(); logRun(store.root, 'consolidate', r ?? {}) })
-      .catch((error) => { logRun(store.root, 'consolidate-error', { error: String(error) }); ctx.logger.warn('dsh-memory: consolidate failed: ' + (error && error.message)) })
-  }
-
-  /** On-demand freshness pass: the same work the daily cadence does, triggered explicitly. */
-  async function refreshNow(agent, { limit } = {}) {
-    const target = memoryTarget(agent)
-    if (!target) throw new Error('memory_refresh needs a routed provider/model: send a message first or set summaryModel')
-    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
-    const result = await runRefresh(store.root === undefined ? store : store, { llm, limit: limit ?? 3 })
-    if (result.updated || result.superseded) scheduler.markDirty()
-    return result
-  }
-
-  /**
-   * Drop captured digests that have already been consolidated and are beyond the newest N.
-   * Digests are raw session material: gitignored, but one file per session accumulates forever.
-   * A pending digest is never touched - it is the only copy of work not yet in the store.
-   */
-  function maybePrune() {
-    try {
-      const result = pruneDigests(store, { keep: cfg.digestKeepCount })
-      if (result.removed > 0) { record(store.root, 'digest-prune', { count: result.removed }); ctx.logger.debug('dsh-memory: pruned ' + result.removed + ' consolidated digest(s)') }
-    } catch (error) {
-      ctx.logger.debug('dsh-memory: digest prune skipped: ' + (error && error.message))
-    }
-  }
-
-  /**
-   * A snapshot for the agent: what the store holds and what needs attention.
-   *
-   * The queue's states are reported individually rather than as one 'pending' number, because the
-   * states mean different things and only some of them are work. 'abandoned' and 'orphaned' in
-   * particular are the answers to 'did anything quietly give up', which nothing could answer before.
-   */
-  function statusNow(agent) {
-    const base = store.status()
-    const states = summarizeQueue(store.root)
-    const counts = {}
-    for (const [state, n] of Object.entries(states)) if (n > 0) counts[state] = n
-    // Parked work is separated by WHY it is parked: waiting for a person is a different situation
-    // from waiting for material to be rebuilt, and they need different actions.
-    const parked = {}
-    for (const entry of readQueue(store.root).values()) {
-      if (entry.state !== STATES.HELD) continue
-      const key = entry.reason ?? 'unspecified'
-      parked[key] = (parked[key] ?? 0) + 1
-    }
-    // Grouped by what is wrong, not listed per entry. The first version listed every problem and
-    // produced 79 rows, 78 of them identical 'orphaned/digest-missing' - which is noise wearing the
-    // costume of visibility. A reader needs the SHAPE of the problem first (one class of 78, one of
-    // 1), then a sample of ids to act on. The full list is one query away for anyone who wants it.
-    const attention = groupProblems(problems(store.root))
-    const work = due(store.root)
-    return {
-      root: base.root,
-      pendingDigests: pendingDigests(store).length,
-      queue: {
-        states: counts,
-        ...(Object.keys(parked).length ? { parked } : {}),
-        waiting: work.filter((w) => w.action === 'work').length,
-        retrying: work.filter((w) => w.action === 'retry').length,
-        recoverable: work.filter((w) => w.action === 'recover').length,
-        // Named rather than counted: a count of problems tells a reader something is wrong, and a
-        // list tells them WHAT, which is the difference between a warning and something actionable.
-        ...(attention.length ? { attention } : {}),
-      },
-      conflicted: Boolean(base.sync && base.sync.conflicted),
-      lastSync: base.sync && base.sync.last ? base.sync.last : null,
-      metrics: readMetrics(store.root),
-      ...(agent ? {} : {}),
-    }
-  }
-
-  /**
-   * Collapse problems into classes a reader can act on: one row per kind, with a sample of ids.
-   * Sorted by how much of the problem each class accounts for, so the biggest comes first.
-   */
-  function groupProblems(entries) {
-    const groups = new Map()
-    for (const entry of entries) {
-      const key = entry.state + ':' + (entry.reason ?? 'unspecified')
-      const g = groups.get(key) ?? { state: entry.state, reason: entry.reason ?? null, count: 0, oldestHours: 0, sample: [] }
-      g.count += 1
-      const ms = Date.now() - Date.parse(entry.at)
-      const hours = Number.isFinite(ms) ? Math.round(ms / 3600000) : 0
-      if (hours > g.oldestHours) g.oldestHours = hours
-      if (g.sample.length < 3) g.sample.push(entry.id)
-      if (entry.attempts !== undefined && g.attempts === undefined) g.attempts = entry.attempts
-      groups.set(key, g)
-    }
-    return [...groups.values()].sort((a, b) => b.count - a.count)
-  }
-  /** On-demand consolidation: the same pass the cadence runs, triggered explicitly. */
-  async function consolidateNow(agent, { batchSize } = {}) {
-    const target = memoryTarget(agent)
-    if (!target) throw new Error('memory_consolidate needs a routed provider/model: send a message first or set the agent model')
-    const work = dueWork()
-    if (work.length === 0) return { consolidated: 0, written: 0, pending: 0 }
-    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
-    const result = await runConsolidation(store, {
-      llm, digests: work, batchSize: batchSize ?? cfg.autoConsolidateBatchSize,
-      maxPromptBytes: cfg.consolidateMaxPromptBytes, maxDigestBytes: cfg.consolidateMaxDigestBytes,
-    })
-    if (result.consolidated > 0) scheduler.markDirty()
-    return {
-      consolidated: result.consolidated ?? 0,
-      written: result.written ?? 0,
-      pending: due(store.root).length,
-      ...(result.parseFailed ? { parseFailed: true } : {}),
-    }
-  }
-
-  /**
-   * Record new commits for the agent's workspace. Silent by design: a repository that is
-   * absent, not a repo, or has no new commits must never interrupt a turn.
-   */
-  function maybeHistory(agent) {
-    const now = Date.now()
-    if (now - lastHistoryAttempt < cfg.autoHistoryIntervalMs) return
-    lastHistoryAttempt = now
-    void historyOf(agent, { limit: cfg.autoHistoryLimit })
-      .then((r) => {
-        // Record the ATTEMPT, not only a success. Logging solely on added > 0 makes an
-        // unexercised hook indistinguishable from a satisfied one.
-        record(store.root, 'history-check', { count: r && r.added ? r.added : 0, detail: { added: (r && r.added) || 0, ok: Boolean(r && r.ok), reason: (r && r.reason) || '' } })
-        if (r && r.added > 0) { scheduler.markDirty(); record(store.root, 'history-ingest', { count: r.added, detail: { workspace: r.repoPath } }); ctx.logger.debug('dsh-memory: recorded ' + r.added + ' commit(s) for ' + r.repoPath) }
-      })
-      .catch((error) => {
-        // The catch path left no trace, so a history attempt that THREW was indistinguishable
-        // from one that never ran - the same blind spot the success-only logging had.
-        record(store.root, 'history-check', { detail: { ok: false, error: String((error && error.message) || error).slice(0, 120) } })
-        ctx.logger.debug('dsh-memory: history ingest skipped: ' + (error && error.message))
-      })
-  }
-
-  function maybeRefresh(agent) {
-    const now = Date.now()
-    if (now - lastRefreshAttempt < cfg.autoRefreshIntervalMs) return
-    lastRefreshAttempt = now
-    const target = memoryTarget(agent)
-    if (!target) return
-    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
-    void runRefresh(store, { llm, limit: 3 })
-      .then((r) => { scheduler.markDirty(); logRun(store.root, 'refresh', r ?? {}) })
-      .catch((error) => { logRun(store.root, 'refresh-error', { error: String(error) }); ctx.logger.warn('dsh-memory: refresh failed: ' + (error && error.message)) })
-  }
-
-  /** Persist the last sync outcome so status() can report it after the fact. */
-  function recordSync(value) {
-    try {
-      mkdirSync(join(store.root, 'state'), { recursive: true })
-      writeFileSync(join(store.root, 'state', 'sync.json'), JSON.stringify(value, null, 2) + '\n')
-    } catch {}
-  }
-
-  /** Record a failed sync: a visible marker file, a log line, and a status record. */
-  function failSync(stage, verdict, committed) {
-    const reason = verdict.reason || 'unknown git failure'
-    ctx.logger.warn('dsh-memory: git ' + stage + ' failed: ' + reason)
-    try {
-      mkdirSync(join(store.root, 'state'), { recursive: true })
-      writeFileSync(join(store.root, 'state', 'CONFLICT.md'), [
-        '# dsh-memory: git ' + stage + ' failed',
-        '',
-        'When: ' + new Date().toISOString(),
-        'Store: ' + store.root,
-        'Remote: ' + (cfg.gitRemote || '(none)'),
-        'Conflicted: ' + String(Boolean(verdict.conflicted)),
-        '',
-        'Reason:',
-        reason,
-        '',
-        'Resolve the repository by hand (git status / git rebase --continue), then run memory_sync.',
-        'This marker is cleared automatically by the next successful sync.',
-        '',
-      ].join('\n'))
-    } catch {}
-    recordSync({ at: new Date().toISOString(), ok: false, stage, error: reason, conflicted: Boolean(verdict.conflicted), remote: cfg.gitRemote })
-    return { initialized: false, committed, synced: false, conflict: true, stage, error: reason }
-  }
-
-  /** Clear the conflict marker after a clean sync. */
-  function clearSyncProblem() {
-    try { rmSync(join(store.root, 'state', 'CONFLICT.md'), { force: true }) } catch {}
-  }
-
-  async function runSync(force = false) {
-    const branch = cfg.gitBranch || 'main'
-    const hasGit = existsSync(join(store.root, '.git'))
-    if (!hasGit) {
-      await git.init(store.root)
-      if (cfg.gitRemote) {
-        await git.remoteAdd(store.root, cfg.gitRemote).catch(() => {})
-        await git.push(store.root, branch).catch(() => {})
-      } else {
-        await git.commit(store.root, commitMessage('store', 'init')).catch(() => {})
-      }
-      scheduler.synced()
-      return { initialized: true, committed: false, synced: Boolean(cfg.gitRemote) }
-    }
-    let committed = false
-    let synced = false
-    if (force || scheduler.shouldCommit()) {
-      try { await git.addAll(store.root); await git.commit(store.root, commitMessage('store', 'update')); scheduler.committed(); committed = true }
-      catch (error) { ctx.logger.warn('dsh-memory: commit failed: ' + (error && error.message)) }
-    }
-    if (cfg.gitRemote && (force || scheduler.shouldSync())) {
-      const pulled = await git.pull(store.root, branch).catch((error) => ({ code: -1, stderr: String((error && error.message) || error) }))
-      const pullVerdict = classifyGitResult(pulled)
-      if (!pullVerdict.ok) return failSync('pull', pullVerdict, committed)
-      const pushed = await git.push(store.root, branch).catch((error) => ({ code: -1, stderr: String((error && error.message) || error) }))
-      const pushVerdict = classifyGitResult(pushed)
-      if (!pushVerdict.ok) return failSync('push', pushVerdict, committed)
-      clearSyncProblem()
-      scheduler.synced()
-      synced = true
-      recordSync({ at: new Date().toISOString(), ok: true, remote: cfg.gitRemote })
-    }
-    return { initialized: false, committed, synced }
-  }
-
-  /**
-   * Back up the scheduled tasks on the sync cadence.
-   *
-   * This rides a cadence rather than an event because the thing it protects against is not an
-   * event: the host DELETES a task when its session stops (schedule index.ts:421), so a task can
-   * vanish between two turns with nothing to observe. Only a periodic pass notices.
-   *
-   * Throttled like the other cadences, and it reports through the run log the same way: a backup
-   * that silently stopped working would be indistinguishable from a machine with no tasks.
-   */
-  function maybeBackupTasks() {
-    const now = Date.now()
-    if (now - lastTasksBackupAttempt < TASKS_BACKUP_MS) return
-    lastTasksBackupAttempt = now
-    try {
-      // `||`, not `??`: the config default is an empty string, and `??` passes that straight
-      // through, so the pass would read a path of '' , find no store, and report a clean run that
-      // backed up nothing. A silent no-op is the failure this whole layer exists to prevent.
-      const result = backupTasks(store.root, { schedulePath: cfg.schedulePath || defaultSchedulePath() })
-      logRun(store.root, 'tasks-backup', {
-        ok: result.error === null,
-        written: result.written,
-        refreshed: result.refreshed,
-        stopped: result.stopped,
-        skipped: result.skipped.length,
-        error: result.error ?? '',
-      })
-    } catch (error) {
-      logRun(store.root, 'tasks-backup', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
-    }
-  }
-
-  /**
-   * Restore backed-up tasks into the live schedule store, once per process.
-   *
-   * WHY IT WAITS FOR A SESSION. The schedule runtime resolves an agent from the task's sessionId
-   * before every delivery and throws when it cannot (schedule runtime.ts:101). At boot there is no
-   * session, so a task restored then would be armed against an owner that does not exist and would
-   * fail on every due scan. The first real session is therefore the earliest moment a restore can
-   * produce a task that actually fires.
-   *
-   * The OWNER IS CHOSEN, NEVER ASKED FOR. That session becomes the task's owner, and the report
-   * says so: the host deletes a task when its owning session stops (schedule index.ts:421), so a
-   * reader needs to know which session holds them.
-   *
-   * ADDITIVE. It only ever creates; nothing here deletes or updates. A task already in the live
-   * store is left exactly as it is, matched by CONTENT because create() mints a fresh id
-   * (schedule index.ts:256) and ids therefore cannot identify anything across a restore.
-   */
-  async function maybeRestoreTasks(agent, { force = false } = {}) {
-    // EVERY early return REPORTS WHY. These used to return silently, and the tool that calls this
-    // reported success regardless - so a manual restore after the boot pass returned immediately at
-    // the once-per-process guard while telling the caller it had restored. An action that does
-    // nothing and says it worked is worse than one that fails.
-    if (restoreAttempted && !force) return { ran: false, reason: 'already restored in this process; pass force to run it again' }
-    if (!agent || isSubagentSession(agent.session)) return { ran: false, reason: 'a restored task needs a main session to own it' }
-    const sessionId = agent.session && agent.session.id
-    if (!sessionId) return { ran: false, reason: 'the session has no id to bind the task to' }
-    const schedule = ctx.get('schedule')
-    if (!schedule || typeof schedule.create !== 'function') return { ran: false, reason: 'the schedule service is unavailable' }
-    restoreAttempted = true
-    try {
-      const path = cfg.schedulePath || defaultSchedulePath()
-      const live = readScheduleStore(path)
-      if (live.error !== null) {
-        logRun(store.root, 'tasks-restore', { ok: false, error: live.error })
-        return { ran: true, owner: sessionId, error: live.error }
-      }
-      const plan = planRestore(store.root, { liveTasks: live.tasks })
-      const added = []
-      const failed = []
-      for (const entry of plan.add) {
-        try {
-          const record = await schedule.create(sessionId, entry.request)
-          added.push({ id: record && record.id, title: entry.request.title })
-        } catch (error) {
-          failed.push({ title: entry.request.title, error: String((error && error.message) || error).slice(0, 120) })
-        }
-      }
-      logRun(store.root, 'tasks-restore', {
-        ok: failed.length === 0,
-        owner: sessionId,
-        added: added.length,
-        present: plan.present.length,
-        paused: plan.paused.length,
-        refused: plan.refused.length,
-        failed: failed.length,
-        detail: failed.length ? failed : undefined,
-      })
-      return { ran: true, owner: sessionId, added: added.length, present: plan.present.length, paused: plan.paused.length, refused: plan.refused.length, failed: failed.length }
-    } catch (error) {
-      logRun(store.root, 'tasks-restore', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
-      return { ran: true, owner: sessionId, error: String((error && error.message) || error).slice(0, 160) }
-    }
-  }
-
-  /**
-   * Publish the memory map into the session log, so a UI can draw it without anyone calling a tool.
-   *
-   * WHY AN EVENT AND NOT A TOOL CALL. The Memory tab used to read the newest memory_map TOOL RESULT
-   * out of the session, which meant it stayed empty until an agent happened to call the tool - the
-   * reader had to be shown the data before the tab could show it back. That is backwards for a view
-   * whose whole job is to report state nobody asked about. Session.append is the harness's own
-   * answer: SessionEventMap is documented as "the merge-extensible, append-only source of truth",
-   * plugins add their own event types (session/title does exactly this), and a log-only event never
-   * reaches the model surface or the derived history. So the map is published BY the host, INTO the
-   * log, and the client reads it from the same event window it already subscribes to.
-   *
-   * TWO GUARDS, both about not making the log grow without limit:
-   *   - a time throttle, because building the map walks the ledger;
-   *   - a signature comparison that ignores generatedAt, so an unchanged store appends nothing.
-   * The signature is the point. Without it every turn would add an identical snapshot to a log that
-   * is the durable record of the conversation.
-   */
-  function publishMemoryMap(session, { agent, force = false } = {}) {
-    try {
-      if (!session || typeof session.append !== 'function' || !session.id) return
-      if (isSubagentSession(session)) return
-      const now = Date.now()
-      if (!force && now - (lastMapPublish.get(session.id) ?? 0) < MAP_PUBLISH_MS) return
-      lastMapPublish.set(session.id, now)
-      const key = keyBySession.get(session.id) ?? 'global'
-      const scope = key === 'global' ? 'global' : 'workspace'
-      // goals.get() takes an AGENT, not a session (goal/src/index.ts:277), so the goal is only
-      // available on the pre-step path. Elsewhere the map is published without it, which is honest:
-      // it describes what it can see.
-      const goal = agent ? ctx.get('goals')?.get(agent)?.objective : undefined
-      const map = buildMap(store, { scope: 'all', sessionId: session.id, memoryScope: scope, key, goal, now, maxChars: cfg.injectionMaxChars })
-      // JSON round-trip is not decoration: append() REJECTS data containing undefined, and the
-      // round-trip is what guarantees we hand it lossless JSON.
-      const payload = JSON.parse(JSON.stringify(map))
-      const signature = JSON.stringify({ ...payload, generatedAt: '' })
-      if (!force && lastMapSignature.get(session.id) === signature) return
-      lastMapSignature.set(session.id, signature)
-      session.append('memory/map', payload)
-      logRun(store.root, 'map-publish', { ok: true, scope, key: key ?? '', bytes: signature.length })
-    } catch (error) {
-      // Never let a view break the conversation it is describing.
-      logRun(store.root, 'map-publish', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
-    }
-  }
-
-  function maybeSync() {
-    if (syncInFlight || !git) return
-    if (!scheduler.shouldCommit() && !scheduler.shouldSync()) return
-    syncInFlight = true
-    // Sync wrote its outcome only to state/sync.json, so the log could not answer whether the
-    // hook ran. Both outcomes are recorded now.
-    void runSync()
-      .then((r) => logRun(store.root, 'sync', { ok: (r && r.ok) !== false, committed: (r && r.committed) || 0, synced: Boolean(r && r.synced) }))
-      .catch((error) => logRun(store.root, 'sync', { ok: false, error: String((error && error.message) || error).slice(0, 160) }))
-      .finally(() => { syncInFlight = false })
-  }
-
-  // session lifecycle: associate workspace + capture on turn end
-  ctx.on('session/event', (session, event) => {
-    // DEFERRED, and it has to be. This handler runs INSIDE an append - the harness sets a reentrancy
-    // flag for the duration of the session/event emission - and Session.append refuses to reenter:
-    // "session append cannot reenter while another append is being published". Measured in the live
-    // log, exactly half the publishes failed with that message while the pre-step ones succeeded.
-    // A macrotask lands after the append has settled, so the guard is satisfied.
-    if (event.type === 'turn/start') {
-      void resolveKey(session).then(() => setTimeout(() => publishMemoryMap(session), 0))
-    } else if (event.type === 'turn/end') {
-      maybeCapture(session)
-      setTimeout(() => publishMemoryMap(session), 0)
-    }
-  })
-
-  // Disposal is the LAST chance to capture a session, so it bypasses the throttle.
-  //
-  // The throttle exists to bound cost, and on a long session it works: turn ends arrive every
-  // few minutes and each one that clears the window captures the new material. But a SHORT
-  // session inverts it - the first turn consumes the window, and every later turn is skipped.
-  // A one-shot subagent that does its whole job in its second turn was therefore captured from
-  // its trivial first turn and never again, which is how 300+ sessions ended up with no memory
-  // while their logs held 11k-35k characters of real material each.
-  ctx.on('session/disposed', (session) => {
-    if (!session || !session.id) return
-    captureThrottle.delete(session.id)
-    maybeCapture(session)
-  })
-
-  // agent pre-step: cadence + session-start injection (+ mid-session refresh interval)
-  ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
-    const decision = await next()
-    if (decision.kind === 'reject' || signal.aborted) return decision
-    maybeConsolidate(agent)
-    maybeRefresh(agent)
-    maybeHistory(agent)
-    maybeSync()
-    maybeBackupTasks()
-    // Only a real session can own a restored task, so the restore waits for this hook.
-    void maybeRestoreTasks(agent)
-    const now = Date.now()
-    if (step !== 1 && now - (injectionThrottle.get(agent.id) ?? 0) < cfg.injectionRefreshMs) return decision
-    injectionThrottle.set(agent.id, now)
-    const cwd = agent.session?.header?.cwd
-    if (cwd && cwd === store.root) return decision // never inject into the memory store itself
-    const key = await resolveKey(agent.session)
-    const goal = ctx.get('goals')?.get(agent)?.objective
-    const subagent = isSubagentSession(agent.session)
-    const scope = key === 'global' ? 'global' : 'workspace'
-    const text = buildInjectionText(store, { scope, key, goal, maxChars: cfg.injectionMaxChars, subagent })
-    // Injection writes nothing, so without this it is invisible: the one hook whose effect is
-    // entirely in the conversation could break and leave no trace anywhere on disk.
-    record(store.root, 'inject', { detail: { scope, key: key ?? '', subagent, step, chars: text.length } })
-    // Published here as well as on turn boundaries, because this is the only place the AGENT (and
-    // so the session's goal) is in reach - and the received panel is supposed to describe what was
-    // actually injected, goal included.
-    publishMemoryMap(agent.session, { agent })
-    return {
-      ...decision,
-      messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text }], source: { kind: PLUGIN, form: 'memory-context', version: 1 } })],
-    }
-  })
-
-  /**
-   * Idle ticker. Every cadence used to hang off `agent/pre-step`, so a host where
-   * nobody was chatting never consolidated, refreshed, or synced anything. The
-   * ticker is a cheap no-op unless a cadence is actually due, and it needs no agent:
-   * with `summaryModel` configured the model resolves from config.
-   */
-  ctx.effect(() => {
-    const timer = setInterval(() => {
-      try {
-        maybeConsolidate(null)
-        maybeRefresh(null)
-        maybePrune()
-        // The ticker has no agent, so history ingest waits for the next step in a session.
-        maybeSync()
-        maybeBackupTasks()
-      } catch (error) {
-        ctx.logger.warn('dsh-memory: idle tick failed: ' + (error && error.message))
-      }
-    }, IDLE_TICK_MS)
-    if (typeof timer.unref === 'function') timer.unref()
-    return () => clearInterval(timer)
-  }, 'dsh-memory: idle ticker')
-
-  /**
-   * Rerank search hits with the session model. Advisory by contract: rerankHits returns the
-   * original order whenever anything is missing or unparseable, so search never depends on it.
-   */
-  async function rerankSearch(agent, query, hits, options = {}) {
-    const enabled = options.enabled ?? cfg.rerankSearch
-    if (!enabled) return { hits, reranked: false, reason: 'disabled' }
-    const target = memoryTarget(agent)
-    return rerankHits(query, hits, {
-      ...options, enabled: true,
-      llm: (prompt) => runLlm(target, prompt, 'memory-rerank', 500),
-    })
-  }
-
-  // injectionMaxChars travels with the host so memory_map can describe the card that was
-  // ACTUALLY built: the cap is configuration, and a snapshot built with a different cap would
-  // report a size the session never saw.
-  // Resolved once, here, where the config lives: tools.js has no access to cfg and a tool that
-  // reached for it would throw at call time (which is how memory_tasks first failed).
-  return { scheduler, schedulePath: cfg.schedulePath || defaultSchedulePath(), tasksNow: maybeBackupTasks, tasksRestore: maybeRestoreTasks, syncNow: () => runSync(true), consolidate: consolidateNow, refresh: refreshNow, status: statusNow, recover: recoverNow, rerankSearch, workspaceOf, historyOf, injectionMaxChars: cfg.injectionMaxChars }
-}
+// DSH host wiring: deep hooks into session lifecycle, agent pre-step, LLM, and
+// subprocess. This is the only module that touches DSH services directly.
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { BlockAssembler, ReasoningEffortId, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { captureSession, pendingDigests, pruneDigests } from './capture.js'
+import { runConsolidation } from './consolidate-run.js'
+import { runRefresh } from './refresh.js'
+import { buildInjectionText } from './inject.js'
+import { parseModelRef } from './defaults.js'
+import { ingestHistory } from './history.js'
+import { rerankHits } from './rerank.js'
+import { isSubagentSession } from './session.js'
+import { buildModelLadder, createModelMemory, runLadder } from './models.js'
+import { due, problems, readQueue, reapStalled, REASONS, STATES, summarize as summarizeQueue, transition } from './queue.js'
+import { planRecovery, recoverOne } from './recover.js'
+import { logRun, noteActivity, readMetrics, record } from './telemetry.js'
+import { GitRunner, SyncScheduler, classifyGitResult, commitMessage } from './git.js'
+import { buildMap } from './map.js'
+import { backupTasks, defaultSchedulePath, planRestore, readScheduleStore } from './tasks.js'
+import { autoAssociateSession } from './session.js'
+import { readAssociations } from './workspace.js'
+
+const PLUGIN = 'dsh-memory'
+
+/** How often the idle ticker checks whether a cadence is due (the cadences self-throttle). */
+const MAP_PUBLISH_MS = 60 * 1000
+const TASKS_BACKUP_MS = 30 * 60 * 1000
+const IDLE_TICK_MS = 60_000
+
+function makeGitRunner(ctx) {
+  const subprocess = ctx.get('subprocess')
+  if (!subprocess || typeof subprocess.resolveExecutable !== 'function' || typeof subprocess.spawn !== 'function') return null
+  let executablePromise
+  const run = async (argv, opts = {}) => {
+    if (!executablePromise) executablePromise = subprocess.resolveExecutable('git', undefined, undefined).catch(() => null)
+    const executable = await executablePromise
+    if (!executable) return { exitCode: 127, stdout: '', stderr: 'git unavailable' }
+    try {
+      const handle = subprocess.spawn({
+        argv: [executable, ...argv],
+        cwd: opts.cwd,
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 4 * 1024 * 1024 }, stderr: { maxBytes: 16 * 1024 } },
+        graceMs: 2000,
+        env: { GIT_CONFIG_COUNT: '0', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C' },
+      })
+      const outcome = await handle.done
+      const stdout = handle.collected?.stdout?.readFrom?.(0)?.text ?? ''
+      const stderr = handle.collected?.stderr?.readFrom?.(0)?.text ?? ''
+      return { exitCode: outcome?.exitCode ?? null, stdout, stderr }
+    } catch (error) {
+      return { exitCode: 1, stdout: '', stderr: String(error) }
+    }
+  }
+  return new GitRunner(run)
+}
+
+function resolveTarget(agent) {
+  const h = agent?.session?.requestHeader?.()?.config
+  if (h && h.provider && h.model) return { provider: h.provider, model: h.model }
+  const o = agent?.options
+  if (o && o.provider && o.model) return { provider: o.provider, model: o.model }
+  return undefined
+}
+
+export function wireHost(ctx, store, cfg) {
+  const keyBySession = new Map()
+  const scheduler = new SyncScheduler({ commitDebounceMs: cfg.commitDebounceMs, syncIntervalMs: cfg.autoSyncIntervalMs })
+  const captureThrottle = new Map()
+  const injectionThrottle = new Map()
+  let lastConsolidateAttempt = 0
+  let lastRefreshAttempt = 0
+  let lastTasksBackupAttempt = 0
+  let restoreAttempted = false
+  const lastMapPublish = new Map()
+  const lastMapSignature = new Map()
+  const mapPublishSuppressed = new Set()
+  let lastHistoryAttempt = 0
+  let syncInFlight = false
+
+  const git = makeGitRunner(ctx)
+  const llmService = ctx.get('llm')
+
+  /** Which model last worked, and which recently returned nothing. Learned, not configured. */
+  const modelMemory = createModelMemory()
+  let memoryPreferred
+  let availableCache
+
+  /**
+   * Every model this deployment can actually route to right now.
+   *
+   * Read from the live registry rather than a constant: providers appear and disappear, a
+   * subscription lapses, and role-model routing changes what is reachable. A short cache keeps
+   * a burst of memory writes from re-enumerating providers on every call, and a failure to
+   * enumerate is not fatal - the ladder still has the configured and session routes.
+   */
+  async function listAvailableModels({ maxAgeMs = 60000 } = {}) {
+    const now = Date.now()
+    if (availableCache && now - availableCache.at < maxAgeMs) return availableCache.models
+    const models = []
+    try {
+      const providers = llmService.listProviders()
+      for (const provider of providers ?? []) {
+        try {
+          const list = await llmService.listModels(provider.id)
+          for (const model of list ?? []) models.push({ provider: provider.id, model: model.id })
+        } catch { /* one unroutable provider must not empty the ladder */ }
+      }
+    } catch { /* fall through with whatever was collected */ }
+    availableCache = { at: now, models }
+    return models
+  }
+
+
+  const runLlm = async (target, prompt, purpose = 'memory-consolidation', maxTokens = 4000) => {
+    if (!llmService) throw new Error('llm service unavailable')
+
+    /** One attempt against ONE model, with the reasoning-effort recovery. */
+    const attemptOn = async (model, controls, called) => {
+      called.push({ provider: model.provider, model: model.model })
+      record(store.root, 'model-call', { modelCalls: 1, purpose, detail: { provider: model.provider, model: model.model } })
+      const assembler = new BlockAssembler()
+      const messages = [{ role: 'user', content: [{ type: 'text', text: prompt }] }]
+      for await (const chunk of llmService.stream({
+        provider: model.provider, model: model.model, messages, maxTokens, purpose, ...controls,
+      })) assembler.push(chunk)
+      // Text blocks only. A reasoning model streams its thinking as `reasoning` blocks;
+      // folding those into the reply prepends prose to the answer, which makes any
+      // "parse the JSON reply" step match the wrong braces and fail. Worse, a model that
+      // spends its whole budget reasoning returns NO text block at all - which is exactly
+      // the failure the ladder exists to route around.
+      return assembler.blocks().filter((b) => b && b.type === 'text').map((b) => b.text || '').join('\n').trim()
+    }
+
+    /**
+     * One model, tried at the memory reasoning effort and then with reasoning off.
+     * Memory work is extraction: it must not run at the session's reasoning budget, and a
+     * model that rejects the effort outright is retried without the control rather than
+     * failing every memory write.
+     */
+    const attemptModel = async (model) => {
+      const called = []
+      const effort = cfg.memoryReasoningEffort
+      if (effort) {
+        let text = ''
+        try {
+          text = await attemptOn(model, { reasoningEffort: ReasoningEffortId(effort) }, called)
+        } catch (error) {
+          const message = String((error && error.message) || error)
+          if (!/UNSUPPORTED_REASONING_EFFORT|does not support reasoning effort/i.test(message)) {
+            modelCalls.push(...called)
+            throw error
+          }
+          ctx.logger.debug('dsh-memory: ' + model.model + ' does not support reasoning effort "' + effort + '"; retrying without it')
+          const plain = await attemptOn(model, {}, called)
+          modelCalls.push(...called)
+          return plain
+        }
+        if (text !== '') { modelCalls.push(...called); return text }
+        ctx.logger.debug('dsh-memory: ' + model.model + ' returned no text at effort "' + effort + '"; retrying with reasoning off')
+        const off = await attemptOn(model, { reasoningEffort: ReasoningEffortId('off') }, called)
+        modelCalls.push(...called)
+        return off
+      }
+      const plain = await attemptOn(model, {}, called)
+      modelCalls.push(...called)
+      return plain
+    }
+
+    // Resolve the ladder from the LIVE registry: the configured memory model, then the
+    // session's route, then everything else routable. The model list is deployment state,
+    // not a constant, so it is read per call and the winner is remembered.
+    const available = await listAvailableModels()
+    const ladder = buildModelLadder({
+      preferred: memoryPreferred ?? parseModelRef(cfg.summaryModel),
+      session: target,
+      available,
+    })
+    if (ladder.length === 0) throw new Error('dsh-memory: no routable model for memory work')
+    const modelCalls = []
+    const outcome = await runLadder({
+      ladder,
+      memory: modelMemory,
+      attempt: attemptModel,
+      onAttempt: (model, text, error) => {
+        if (error) record(store.root, 'model-failed', { detail: { provider: model.provider, model: model.model, error: String(error.message || error).slice(0, 120) } })
+        else if (text === '') record(store.root, 'model-empty', { detail: { provider: model.provider, model: model.model } })
+      },
+    })
+    if (outcome.text !== '') {
+      if (outcome.tried.length > 1) {
+        logRun(store.root, 'model-fallback', {
+          purpose,
+          used: outcome.target.provider + '/' + outcome.target.model,
+          skipped: outcome.tried.slice(0, -1).map((x) => x.target.provider + '/' + x.target.model).join(','),
+        })
+      }
+      memoryPreferred = outcome.target
+      return outcome.text
+    }
+    // Every model returned nothing. That is a deployment problem, not a verdict about the
+    // material, and it is reported as an error so the session is retried rather than settled.
+    throw new Error('dsh-memory: no model returned text (' + outcome.tried.map((x) => x.target.model + (x.error ? ':' + x.error : ':empty')).join(', ') + ')')
+  }
+/** Summarizer bound to the session's own model; undefined when the session is unrouted. */
+  /** Model for memory writes: the configured memory model, else the agent's route. */
+  function memoryTarget(agent) {
+    return parseModelRef(cfg.summaryModel) ?? resolveTarget(agent)
+  }
+
+  /** The configured memory model wins; otherwise the session's own model. */
+  function summaryLlm(session) {
+    const configured = parseModelRef(cfg.summaryModel)
+    if (configured) return (prompt) => runLlm(configured, prompt, 'memory-summary', 1200)
+    const header = session?.requestHeader?.()?.config
+    if (!header || !header.provider || !header.model) return undefined
+    return (prompt) => runLlm({ provider: header.provider, model: header.model }, prompt, 'memory-summary', 1200)
+  }
+
+  async function resolveKey(session) {
+    const cached = keyBySession.get(session.id)
+    if (cached) return cached
+    const key = await autoAssociateSession(store, ctx, session).catch(() => 'global')
+    keyBySession.set(session.id, key)
+    return key
+  }
+
+  /**
+   * Record the repository commit history for an agent's workspace. The workspace key comes
+   * from the session; the repository path comes from the device-local association, so the
+   * plugin never has to guess where the checkout lives.
+   */
+  async function historyOf(agent, { limit } = {}) {
+    const workspace = await workspaceOf(agent)
+    if (!workspace) return { ok: false, reason: 'no workspace for this session', added: 0 }
+    const path = readAssociations(store.root)[workspace]?.path
+    if (!path) return { ok: false, reason: 'no local folder associated with ' + workspace, added: 0 }
+    return ingestHistory(store.root, workspace, path, (argv, opts) => git.run(argv, opts), { limit })
+  }
+
+  /** The workspace key for an agent's session, or undefined when it has none. */
+  async function workspaceOf(agent) {
+    const session = agent && agent.session
+    if (!session) return undefined
+    const key = await resolveKey(session).catch(() => 'global')
+    return key === 'global' ? undefined : key
+  }
+
+  function maybeCapture(session) {
+    // Memory belongs to the MAIN agent. A subagent's work is already described in the parent
+    // transcript that delegated it, so capturing the child duplicates that work and buries the
+    // parent's account of it.
+    if (isSubagentSession(session)) return
+    const id = session.id
+    const now = Date.now()
+    if (now - (captureThrottle.get(id) ?? 0) < cfg.autoCaptureIntervalMs) return
+    captureThrottle.set(id, now)
+    const sessionQuery = ctx.get('sessionQuery')
+    if (!sessionQuery) return
+    const options = {
+      maxUserTurns: cfg.digestMaxUserTurns,
+      maxAssistantGists: cfg.digestMaxAssistantGists,
+      maxMessageChars: cfg.digestMaxMessageChars,
+      maxBytes: cfg.digestMaxBytes,
+      maxBullets: cfg.summaryMaxBullets,
+    }
+    void captureSession(store, { sessionQuery, llm: summaryLlm(session) }, session, options)
+      .then((r) => {
+        if (r && r.changed) scheduler.markDirty()
+        if (r && r.summarySource === 'thin') record(store.root, 'summary-skipped', { saved: 'thin', detail: { sessionId: r.sessionId } })
+        if (r && r.summarySource === 'skipped') record(store.root, 'summary-skipped', { saved: 'trivial', detail: { sessionId: r.sessionId } })
+        if (r && r.summarySource) logRun(store.root, 'capture', { sessionId: r.sessionId, summarySource: r.summarySource, fresh: r.fresh, bullets: r.bullets })
+      })
+      .catch((error) => ctx.logger.warn('dsh-memory: capture failed: ' + (error && error.message)))
+  }
+
+  /**
+   * What the consolidation cadence should act on now.
+   *
+   * The watchdog runs FIRST, because an entry stranded mid-stage by a crash is invisible to every
+   * other query: it is neither pending nor failed, so nothing would ever move it.
+   *
+   * Failures whose backoff has expired come back here automatically, which is what makes 'we
+   * cannot let things stay failed' true in the running system rather than only in the model.
+   * Entries that have spent their budget are abandoned explicitly, so the queue drains instead of
+   * accumulating work that can never succeed.
+   */
+  /**
+   * Recovery, exposed to the tool and to the cadence's parking decision.
+   *
+   * The cadence can PARK a large recovery but can never PERFORM one: approval.request() throws
+   * outside an open turn, and the idle ticker has no turn. That is a hard boundary rather than a
+   * limitation to route around, so the cadence's job is to make the work visible and a live tool
+   * call is the only path.
+   */
+  const recoverNow = {
+    plan() {
+      const p = planRecovery(store.root, { thresholdBytes: cfg.recoverApprovalThresholdBytes })
+      return { total: p.total, recoverable: p.recoverable, oversized: p.oversized, missing: p.missing, thresholdBytes: p.threshold }
+    },
+    async run(args, exec) {
+      const p = planRecovery(store.root, { thresholdBytes: cfg.recoverApprovalThresholdBytes })
+      const candidates = args.id
+        ? p.entries.filter((e) => e.id === args.id)
+        : p.entries.filter((e) => !e.needsApproval).sort((a, b) => (a.bytes ?? 0) - (b.bytes ?? 0)).slice(0, args.limit ?? 1)
+      const recovered = []
+      const declined = []
+      for (const target of candidates) {
+        if (target.needsApproval) {
+          const approval = ctx.get('approval')
+          if (!approval) { declined.push({ id: target.id, why: 'no approval service' }); continue }
+          let outcome
+          try {
+            outcome = await approval.request({
+              agent: exec?.agent,
+              toolName: 'memory_recover',
+              reason: 'Rebuild a ' + (target.bytes ? Math.round(target.bytes / 1048576) + 'MB' : 'large') + ' session digest',
+            })
+          } catch (error) {
+            // Outside an open turn. Refusing is the whole point: an unapproved large recovery must
+            // not proceed on the grounds that asking was impossible.
+            declined.push({ id: target.id, why: 'cannot ask outside a turn' })
+            continue
+          }
+          // ONLY an explicit once-grant proceeds. 'unavailable' FAILS CLOSED, by design.
+          if (outcome !== 'allowed-once') { declined.push({ id: target.id, why: String(outcome) }); continue }
+        }
+        try {
+          await recoverOne(store, services, target.id, { cfg, now: () => Date.now() })
+          recovered.push({ id: target.id, bytes: target.bytes })
+          logRun(store.root, 'recover', { count: 1, detail: { id: target.id } })
+        } catch (error) {
+          declined.push({ id: target.id, why: 'recovery failed', error: String((error && error.message) || error).slice(0, 140) })
+        }
+      }
+      return { mode: 'run', ...this.plan(), recovered, declined }
+    },
+  }
+
+  function dueWork(now = Date.now()) {
+    const recovered = reapStalled(store.root, now)
+    if (recovered.length) logRun(store.root, 'queue-reaped', { count: recovered.length, detail: { ids: recovered.slice(0, 10).join(',') } })
+    // An orphan too large to rebuild unasked is PARKED, not left looking like ordinary waiting
+    // work. Parked is visible and costs nothing; the tool is the only thing that can proceed, and
+    // it has to be able to find them.
+    for (const target of planRecovery(store.root, { thresholdBytes: cfg.recoverApprovalThresholdBytes }).entries) {
+      if (!target.needsApproval) continue
+      const parked = readQueue(store.root).get(target.id)
+      if (!parked || parked.state !== STATES.ORPHANED) continue
+      transition(store.root, target.id, STATES.HELD, { reason: REASONS.NEEDS_APPROVAL, detail: { sourceBytes: target.bytes ?? null } })
+    }
+    const work = due(store.root, now)
+    const abandon = []
+    const digests = []
+    for (const item of work) {
+      if (item.action === 'abandon') { abandon.push(item.entry); continue }
+      // A recovery is not a digest: consolidating it would spend a call on material that is known
+      // to be missing. The parking loop above has already handled the ones that need approval.
+      if (item.action === 'recover') continue
+      digests.push({ id: item.entry.id, tier: item.entry.detail?.tier })
+    }
+    for (const entry of abandon) {
+      // Out of the retry loop, but never hidden: problems() reports it and status counts it.
+      transition(store.root, entry.id, STATES.ABANDONED, { reason: entry.reason ?? 'attempts-exhausted' })
+    }
+    if (abandon.length) logRun(store.root, 'queue-abandoned', { count: abandon.length })
+    return digests
+  }
+
+  function maybeConsolidate(agent) {
+    const now = Date.now()
+    if (now - lastConsolidateAttempt < cfg.autoConsolidateIntervalMs) return
+    lastConsolidateAttempt = now
+    // The queue decides what is due: waiting work, plus failures whose backoff expired. A count of
+    // pending digests would miss exactly the work this phase exists to bring back.
+    const work = dueWork(now)
+    if (work.length < cfg.autoConsolidateMinPending) return
+    const target = memoryTarget(agent)
+    if (!target) return
+    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
+    void runConsolidation(store, {
+      llm, digests: work, batchSize: cfg.autoConsolidateBatchSize,
+      maxPromptBytes: cfg.consolidateMaxPromptBytes, maxDigestBytes: cfg.consolidateMaxDigestBytes,
+    })
+      .then((r) => { scheduler.markDirty(); logRun(store.root, 'consolidate', r ?? {}) })
+      .catch((error) => { logRun(store.root, 'consolidate-error', { error: String(error) }); ctx.logger.warn('dsh-memory: consolidate failed: ' + (error && error.message)) })
+  }
+
+  /** On-demand freshness pass: the same work the daily cadence does, triggered explicitly. */
+  async function refreshNow(agent, { limit } = {}) {
+    const target = memoryTarget(agent)
+    if (!target) throw new Error('memory_refresh needs a routed provider/model: send a message first or set summaryModel')
+    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
+    const result = await runRefresh(store.root === undefined ? store : store, { llm, limit: limit ?? 3 })
+    if (result.updated || result.superseded) scheduler.markDirty()
+    return result
+  }
+
+  /**
+   * Drop captured digests that have already been consolidated and are beyond the newest N.
+   * Digests are raw session material: gitignored, but one file per session accumulates forever.
+   * A pending digest is never touched - it is the only copy of work not yet in the store.
+   */
+  function maybePrune() {
+    try {
+      const result = pruneDigests(store, { keep: cfg.digestKeepCount })
+      if (result.removed > 0) { record(store.root, 'digest-prune', { count: result.removed }); ctx.logger.debug('dsh-memory: pruned ' + result.removed + ' consolidated digest(s)') }
+    } catch (error) {
+      ctx.logger.debug('dsh-memory: digest prune skipped: ' + (error && error.message))
+    }
+  }
+
+  /**
+   * A snapshot for the agent: what the store holds and what needs attention.
+   *
+   * The queue's states are reported individually rather than as one 'pending' number, because the
+   * states mean different things and only some of them are work. 'abandoned' and 'orphaned' in
+   * particular are the answers to 'did anything quietly give up', which nothing could answer before.
+   */
+  function statusNow(agent) {
+    const base = store.status()
+    const states = summarizeQueue(store.root)
+    const counts = {}
+    for (const [state, n] of Object.entries(states)) if (n > 0) counts[state] = n
+    // Parked work is separated by WHY it is parked: waiting for a person is a different situation
+    // from waiting for material to be rebuilt, and they need different actions.
+    const parked = {}
+    for (const entry of readQueue(store.root).values()) {
+      if (entry.state !== STATES.HELD) continue
+      const key = entry.reason ?? 'unspecified'
+      parked[key] = (parked[key] ?? 0) + 1
+    }
+    // Grouped by what is wrong, not listed per entry. The first version listed every problem and
+    // produced 79 rows, 78 of them identical 'orphaned/digest-missing' - which is noise wearing the
+    // costume of visibility. A reader needs the SHAPE of the problem first (one class of 78, one of
+    // 1), then a sample of ids to act on. The full list is one query away for anyone who wants it.
+    const attention = groupProblems(problems(store.root))
+    const work = due(store.root)
+    return {
+      root: base.root,
+      pendingDigests: pendingDigests(store).length,
+      queue: {
+        states: counts,
+        ...(Object.keys(parked).length ? { parked } : {}),
+        waiting: work.filter((w) => w.action === 'work').length,
+        retrying: work.filter((w) => w.action === 'retry').length,
+        recoverable: work.filter((w) => w.action === 'recover').length,
+        // Named rather than counted: a count of problems tells a reader something is wrong, and a
+        // list tells them WHAT, which is the difference between a warning and something actionable.
+        ...(attention.length ? { attention } : {}),
+      },
+      conflicted: Boolean(base.sync && base.sync.conflicted),
+      lastSync: base.sync && base.sync.last ? base.sync.last : null,
+      metrics: readMetrics(store.root),
+      ...(agent ? {} : {}),
+    }
+  }
+
+  /**
+   * Collapse problems into classes a reader can act on: one row per kind, with a sample of ids.
+   * Sorted by how much of the problem each class accounts for, so the biggest comes first.
+   */
+  function groupProblems(entries) {
+    const groups = new Map()
+    for (const entry of entries) {
+      const key = entry.state + ':' + (entry.reason ?? 'unspecified')
+      const g = groups.get(key) ?? { state: entry.state, reason: entry.reason ?? null, count: 0, oldestHours: 0, sample: [] }
+      g.count += 1
+      const ms = Date.now() - Date.parse(entry.at)
+      const hours = Number.isFinite(ms) ? Math.round(ms / 3600000) : 0
+      if (hours > g.oldestHours) g.oldestHours = hours
+      if (g.sample.length < 3) g.sample.push(entry.id)
+      if (entry.attempts !== undefined && g.attempts === undefined) g.attempts = entry.attempts
+      groups.set(key, g)
+    }
+    return [...groups.values()].sort((a, b) => b.count - a.count)
+  }
+  /** On-demand consolidation: the same pass the cadence runs, triggered explicitly. */
+  async function consolidateNow(agent, { batchSize } = {}) {
+    const target = memoryTarget(agent)
+    if (!target) throw new Error('memory_consolidate needs a routed provider/model: send a message first or set the agent model')
+    const work = dueWork()
+    if (work.length === 0) return { consolidated: 0, written: 0, pending: 0 }
+    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
+    const result = await runConsolidation(store, {
+      llm, digests: work, batchSize: batchSize ?? cfg.autoConsolidateBatchSize,
+      maxPromptBytes: cfg.consolidateMaxPromptBytes, maxDigestBytes: cfg.consolidateMaxDigestBytes,
+    })
+    if (result.consolidated > 0) scheduler.markDirty()
+    return {
+      consolidated: result.consolidated ?? 0,
+      written: result.written ?? 0,
+      pending: due(store.root).length,
+      ...(result.parseFailed ? { parseFailed: true } : {}),
+    }
+  }
+
+  /**
+   * Record new commits for the agent's workspace. Silent by design: a repository that is
+   * absent, not a repo, or has no new commits must never interrupt a turn.
+   */
+  function maybeHistory(agent) {
+    const now = Date.now()
+    if (now - lastHistoryAttempt < cfg.autoHistoryIntervalMs) return
+    lastHistoryAttempt = now
+    void historyOf(agent, { limit: cfg.autoHistoryLimit })
+      .then((r) => {
+        // Record the ATTEMPT, not only a success. Logging solely on added > 0 makes an
+        // unexercised hook indistinguishable from a satisfied one.
+        record(store.root, 'history-check', { count: r && r.added ? r.added : 0, detail: { added: (r && r.added) || 0, ok: Boolean(r && r.ok), reason: (r && r.reason) || '' } })
+        if (r && r.added > 0) { scheduler.markDirty(); record(store.root, 'history-ingest', { count: r.added, detail: { workspace: r.repoPath } }); ctx.logger.debug('dsh-memory: recorded ' + r.added + ' commit(s) for ' + r.repoPath) }
+      })
+      .catch((error) => {
+        // The catch path left no trace, so a history attempt that THREW was indistinguishable
+        // from one that never ran - the same blind spot the success-only logging had.
+        record(store.root, 'history-check', { detail: { ok: false, error: String((error && error.message) || error).slice(0, 120) } })
+        ctx.logger.debug('dsh-memory: history ingest skipped: ' + (error && error.message))
+      })
+  }
+
+  function maybeRefresh(agent) {
+    const now = Date.now()
+    if (now - lastRefreshAttempt < cfg.autoRefreshIntervalMs) return
+    lastRefreshAttempt = now
+    const target = memoryTarget(agent)
+    if (!target) return
+    const llm = (prompt) => runLlm(target, prompt, 'memory-consolidation', 8000)
+    void runRefresh(store, { llm, limit: 3 })
+      .then((r) => { scheduler.markDirty(); logRun(store.root, 'refresh', r ?? {}) })
+      .catch((error) => { logRun(store.root, 'refresh-error', { error: String(error) }); ctx.logger.warn('dsh-memory: refresh failed: ' + (error && error.message)) })
+  }
+
+  /** Persist the last sync outcome so status() can report it after the fact. */
+  function recordSync(value) {
+    try {
+      mkdirSync(join(store.root, 'state'), { recursive: true })
+      writeFileSync(join(store.root, 'state', 'sync.json'), JSON.stringify(value, null, 2) + '\n')
+    } catch {}
+  }
+
+  /** Record a failed sync: a visible marker file, a log line, and a status record. */
+  function failSync(stage, verdict, committed) {
+    const reason = verdict.reason || 'unknown git failure'
+    ctx.logger.warn('dsh-memory: git ' + stage + ' failed: ' + reason)
+    try {
+      mkdirSync(join(store.root, 'state'), { recursive: true })
+      writeFileSync(join(store.root, 'state', 'CONFLICT.md'), [
+        '# dsh-memory: git ' + stage + ' failed',
+        '',
+        'When: ' + new Date().toISOString(),
+        'Store: ' + store.root,
+        'Remote: ' + (cfg.gitRemote || '(none)'),
+        'Conflicted: ' + String(Boolean(verdict.conflicted)),
+        '',
+        'Reason:',
+        reason,
+        '',
+        'Resolve the repository by hand (git status / git rebase --continue), then run memory_sync.',
+        'This marker is cleared automatically by the next successful sync.',
+        '',
+      ].join('\n'))
+    } catch {}
+    recordSync({ at: new Date().toISOString(), ok: false, stage, error: reason, conflicted: Boolean(verdict.conflicted), remote: cfg.gitRemote })
+    return { initialized: false, committed, synced: false, conflict: true, stage, error: reason }
+  }
+
+  /** Clear the conflict marker after a clean sync. */
+  function clearSyncProblem() {
+    try { rmSync(join(store.root, 'state', 'CONFLICT.md'), { force: true }) } catch {}
+  }
+
+  async function runSync(force = false) {
+    const branch = cfg.gitBranch || 'main'
+    const hasGit = existsSync(join(store.root, '.git'))
+    if (!hasGit) {
+      await git.init(store.root)
+      if (cfg.gitRemote) {
+        await git.remoteAdd(store.root, cfg.gitRemote).catch(() => {})
+        await git.push(store.root, branch).catch(() => {})
+      } else {
+        await git.commit(store.root, commitMessage('store', 'init')).catch(() => {})
+      }
+      scheduler.synced()
+      return { initialized: true, committed: false, synced: Boolean(cfg.gitRemote) }
+    }
+    let committed = false
+    let synced = false
+    if (force || scheduler.shouldCommit()) {
+      try { await git.addAll(store.root); await git.commit(store.root, commitMessage('store', 'update')); scheduler.committed(); committed = true }
+      catch (error) { ctx.logger.warn('dsh-memory: commit failed: ' + (error && error.message)) }
+    }
+    if (cfg.gitRemote && (force || scheduler.shouldSync())) {
+      const pulled = await git.pull(store.root, branch).catch((error) => ({ code: -1, stderr: String((error && error.message) || error) }))
+      const pullVerdict = classifyGitResult(pulled)
+      if (!pullVerdict.ok) return failSync('pull', pullVerdict, committed)
+      const pushed = await git.push(store.root, branch).catch((error) => ({ code: -1, stderr: String((error && error.message) || error) }))
+      const pushVerdict = classifyGitResult(pushed)
+      if (!pushVerdict.ok) return failSync('push', pushVerdict, committed)
+      clearSyncProblem()
+      scheduler.synced()
+      synced = true
+      recordSync({ at: new Date().toISOString(), ok: true, remote: cfg.gitRemote })
+    }
+    return { initialized: false, committed, synced }
+  }
+
+  /**
+   * Back up the scheduled tasks on the sync cadence.
+   *
+   * This rides a cadence rather than an event because the thing it protects against is not an
+   * event: the host DELETES a task when its session stops (schedule index.ts:421), so a task can
+   * vanish between two turns with nothing to observe. Only a periodic pass notices.
+   *
+   * Throttled like the other cadences, and it reports through the run log the same way: a backup
+   * that silently stopped working would be indistinguishable from a machine with no tasks.
+   */
+  function maybeBackupTasks() {
+    const now = Date.now()
+    if (now - lastTasksBackupAttempt < TASKS_BACKUP_MS) return
+    lastTasksBackupAttempt = now
+    try {
+      // `||`, not `??`: the config default is an empty string, and `??` passes that straight
+      // through, so the pass would read a path of '' , find no store, and report a clean run that
+      // backed up nothing. A silent no-op is the failure this whole layer exists to prevent.
+      const result = backupTasks(store.root, { schedulePath: cfg.schedulePath || defaultSchedulePath() })
+      logRun(store.root, 'tasks-backup', {
+        ok: result.error === null,
+        written: result.written,
+        refreshed: result.refreshed,
+        stopped: result.stopped,
+        skipped: result.skipped.length,
+        error: result.error ?? '',
+      })
+    } catch (error) {
+      logRun(store.root, 'tasks-backup', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
+    }
+  }
+
+  /**
+   * Restore backed-up tasks into the live schedule store, once per process.
+   *
+   * WHY IT WAITS FOR A SESSION. The schedule runtime resolves an agent from the task's sessionId
+   * before every delivery and throws when it cannot (schedule runtime.ts:101). At boot there is no
+   * session, so a task restored then would be armed against an owner that does not exist and would
+   * fail on every due scan. The first real session is therefore the earliest moment a restore can
+   * produce a task that actually fires.
+   *
+   * The OWNER IS CHOSEN, NEVER ASKED FOR. That session becomes the task's owner, and the report
+   * says so: the host deletes a task when its owning session stops (schedule index.ts:421), so a
+   * reader needs to know which session holds them.
+   *
+   * ADDITIVE. It only ever creates; nothing here deletes or updates. A task already in the live
+   * store is left exactly as it is, matched by CONTENT because create() mints a fresh id
+   * (schedule index.ts:256) and ids therefore cannot identify anything across a restore.
+   */
+  async function maybeRestoreTasks(agent, { force = false } = {}) {
+    // EVERY early return REPORTS WHY. These used to return silently, and the tool that calls this
+    // reported success regardless - so a manual restore after the boot pass returned immediately at
+    // the once-per-process guard while telling the caller it had restored. An action that does
+    // nothing and says it worked is worse than one that fails.
+    if (restoreAttempted && !force) return { ran: false, reason: 'already restored in this process; pass force to run it again' }
+    if (!agent || isSubagentSession(agent.session)) return { ran: false, reason: 'a restored task needs a main session to own it' }
+    const sessionId = agent.session && agent.session.id
+    if (!sessionId) return { ran: false, reason: 'the session has no id to bind the task to' }
+    const schedule = ctx.get('schedule')
+    if (!schedule || typeof schedule.create !== 'function') return { ran: false, reason: 'the schedule service is unavailable' }
+    restoreAttempted = true
+    try {
+      const path = cfg.schedulePath || defaultSchedulePath()
+      const live = readScheduleStore(path)
+      if (live.error !== null) {
+        logRun(store.root, 'tasks-restore', { ok: false, error: live.error })
+        return { ran: true, owner: sessionId, error: live.error }
+      }
+      const plan = planRestore(store.root, { liveTasks: live.tasks })
+      const added = []
+      const failed = []
+      for (const entry of plan.add) {
+        try {
+          const record = await schedule.create(sessionId, entry.request)
+          added.push({ id: record && record.id, title: entry.request.title })
+        } catch (error) {
+          failed.push({ title: entry.request.title, error: String((error && error.message) || error).slice(0, 120) })
+        }
+      }
+      logRun(store.root, 'tasks-restore', {
+        ok: failed.length === 0,
+        owner: sessionId,
+        added: added.length,
+        present: plan.present.length,
+        paused: plan.paused.length,
+        refused: plan.refused.length,
+        failed: failed.length,
+        detail: failed.length ? failed : undefined,
+      })
+      return { ran: true, owner: sessionId, added: added.length, present: plan.present.length, paused: plan.paused.length, refused: plan.refused.length, failed: failed.length }
+    } catch (error) {
+      logRun(store.root, 'tasks-restore', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
+      return { ran: true, owner: sessionId, error: String((error && error.message) || error).slice(0, 160) }
+    }
+  }
+
+  /**
+   * Publish the memory map into the session log, so a UI can draw it without anyone calling a tool.
+   *
+   * WHY AN EVENT AND NOT A TOOL CALL. The Memory tab used to read the newest memory_map TOOL RESULT
+   * out of the session, which meant it stayed empty until an agent happened to call the tool - the
+   * reader had to be shown the data before the tab could show it back. That is backwards for a view
+   * whose whole job is to report state nobody asked about. Session.append is the harness's own
+   * answer: SessionEventMap is documented as "the merge-extensible, append-only source of truth",
+   * plugins add their own event types (session/title does exactly this), and a log-only event never
+   * reaches the model surface or the derived history. So the map is published BY the host, INTO the
+   * log, and the client reads it from the same event window it already subscribes to.
+   *
+   * TWO GUARDS, both about not making the log grow without limit:
+   *   - a time throttle, because building the map walks the ledger;
+   *   - a signature comparison that ignores generatedAt, so an unchanged store appends nothing.
+   * The signature is the point. Without it every turn would add an identical snapshot to a log that
+   * is the durable record of the conversation.
+   */
+  function publishMemoryMap(session, { agent, force = false } = {}) {
+    try {
+      if (!session || typeof session.append !== 'function' || !session.id) return
+      if (isSubagentSession(session)) return
+      // A session whose harness did not honor ignorable is poisoned by every further append;
+      // the decision to stop is made once, below, and honored on every later attempt.
+      if (mapPublishSuppressed.has(session.id)) return
+      const now = Date.now()
+      if (!force && now - (lastMapPublish.get(session.id) ?? 0) < MAP_PUBLISH_MS) return
+      lastMapPublish.set(session.id, now)
+      const key = keyBySession.get(session.id) ?? 'global'
+      const scope = key === 'global' ? 'global' : 'workspace'
+      // goals.get() takes an AGENT, not a session (goal/src/index.ts:277), so the goal is only
+      // available on the pre-step path. Elsewhere the map is published without it, which is honest:
+      // it describes what it can see.
+      const goal = agent ? ctx.get('goals')?.get(agent)?.objective : undefined
+      const map = buildMap(store, { scope: 'all', sessionId: session.id, memoryScope: scope, key, goal, now, maxChars: cfg.injectionMaxChars })
+      // JSON round-trip is not decoration: append() REJECTS data containing undefined, and the
+      // round-trip is what guarantees we hand it lossless JSON.
+      const payload = JSON.parse(JSON.stringify(map))
+      const signature = JSON.stringify({ ...payload, generatedAt: '' })
+      if (!force && lastMapSignature.get(session.id) === signature) return
+      lastMapSignature.set(session.id, signature)
+      // Out-of-repo event types are absent from KNOWN_SESSION_EVENT_TYPES; without
+      // ignorable:true the persistence read path refuses the whole session log.
+      // The append returns the logged event: if the harness did NOT stamp
+      // ignorable onto it (a harness older than the option), the very next load
+      // of this session would fail with "unknown to this harness and not marked
+      // ignorable". Detecting that from the return value lets us stop before a
+      // log is poisoned, instead of discovering it when history fails to load.
+      const logged = session.append('memory/map', payload, { ignorable: true })
+      if (logged?.ignorable !== true) {
+        if (!mapPublishSuppressed.has(session.id)) {
+          mapPublishSuppressed.add(session.id)
+          logRun(store.root, 'map-publish', { ok: false, error: 'harness did not stamp ignorable; publishing suppressed for this session' })
+        }
+        return
+      }
+      logRun(store.root, 'map-publish', { ok: true, scope, key: key ?? '', bytes: signature.length })
+    } catch (error) {
+      // Never let a view break the conversation it is describing.
+      logRun(store.root, 'map-publish', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
+    }
+  }
+
+  function maybeSync() {
+    if (syncInFlight || !git) return
+    if (!scheduler.shouldCommit() && !scheduler.shouldSync()) return
+    syncInFlight = true
+    // Sync wrote its outcome only to state/sync.json, so the log could not answer whether the
+    // hook ran. Both outcomes are recorded now.
+    void runSync()
+      .then((r) => logRun(store.root, 'sync', { ok: (r && r.ok) !== false, committed: (r && r.committed) || 0, synced: Boolean(r && r.synced) }))
+      .catch((error) => logRun(store.root, 'sync', { ok: false, error: String((error && error.message) || error).slice(0, 160) }))
+      .finally(() => { syncInFlight = false })
+  }
+
+  // session lifecycle: associate workspace + capture on turn end
+  ctx.on('session/event', (session, event) => {
+    // DEFERRED, and it has to be. This handler runs INSIDE an append - the harness sets a reentrancy
+    // flag for the duration of the session/event emission - and Session.append refuses to reenter:
+    // "session append cannot reenter while another append is being published". Measured in the live
+    // log, exactly half the publishes failed with that message while the pre-step ones succeeded.
+    // A macrotask lands after the append has settled, so the guard is satisfied.
+    if (event.type === 'turn/start') {
+      void resolveKey(session).then(() => setTimeout(() => publishMemoryMap(session), 0))
+    } else if (event.type === 'turn/end') {
+      maybeCapture(session)
+      setTimeout(() => publishMemoryMap(session), 0)
+    }
+  })
+
+  // Disposal is the LAST chance to capture a session, so it bypasses the throttle.
+  //
+  // The throttle exists to bound cost, and on a long session it works: turn ends arrive every
+  // few minutes and each one that clears the window captures the new material. But a SHORT
+  // session inverts it - the first turn consumes the window, and every later turn is skipped.
+  // A one-shot subagent that does its whole job in its second turn was therefore captured from
+  // its trivial first turn and never again, which is how 300+ sessions ended up with no memory
+  // while their logs held 11k-35k characters of real material each.
+  ctx.on('session/disposed', (session) => {
+    if (!session || !session.id) return
+    captureThrottle.delete(session.id)
+    maybeCapture(session)
+  })
+
+  // agent pre-step: cadence + session-start injection (+ mid-session refresh interval)
+  ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
+    const decision = await next()
+    if (decision.kind === 'reject' || signal.aborted) return decision
+    maybeConsolidate(agent)
+    maybeRefresh(agent)
+    maybeHistory(agent)
+    maybeSync()
+    maybeBackupTasks()
+    // Only a real session can own a restored task, so the restore waits for this hook.
+    void maybeRestoreTasks(agent)
+    const now = Date.now()
+    if (step !== 1 && now - (injectionThrottle.get(agent.id) ?? 0) < cfg.injectionRefreshMs) return decision
+    injectionThrottle.set(agent.id, now)
+    const cwd = agent.session?.header?.cwd
+    if (cwd && cwd === store.root) return decision // never inject into the memory store itself
+    const key = await resolveKey(agent.session)
+    const goal = ctx.get('goals')?.get(agent)?.objective
+    const subagent = isSubagentSession(agent.session)
+    const scope = key === 'global' ? 'global' : 'workspace'
+    const text = buildInjectionText(store, { scope, key, goal, maxChars: cfg.injectionMaxChars, subagent })
+    // Injection writes nothing, so without this it is invisible: the one hook whose effect is
+    // entirely in the conversation could break and leave no trace anywhere on disk.
+    record(store.root, 'inject', { detail: { scope, key: key ?? '', subagent, step, chars: text.length } })
+    // Published here as well as on turn boundaries, because this is the only place the AGENT (and
+    // so the session's goal) is in reach - and the received panel is supposed to describe what was
+    // actually injected, goal included.
+    publishMemoryMap(agent.session, { agent })
+    return {
+      ...decision,
+      messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text }], source: { kind: PLUGIN, form: 'memory-context', version: 1 } })],
+    }
+  })
+
+  /**
+   * Idle ticker. Every cadence used to hang off `agent/pre-step`, so a host where
+   * nobody was chatting never consolidated, refreshed, or synced anything. The
+   * ticker is a cheap no-op unless a cadence is actually due, and it needs no agent:
+   * with `summaryModel` configured the model resolves from config.
+   */
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      try {
+        maybeConsolidate(null)
+        maybeRefresh(null)
+        maybePrune()
+        // The ticker has no agent, so history ingest waits for the next step in a session.
+        maybeSync()
+        maybeBackupTasks()
+      } catch (error) {
+        ctx.logger.warn('dsh-memory: idle tick failed: ' + (error && error.message))
+      }
+    }, IDLE_TICK_MS)
+    if (typeof timer.unref === 'function') timer.unref()
+    return () => clearInterval(timer)
+  }, 'dsh-memory: idle ticker')
+
+  /**
+   * Rerank search hits with the session model. Advisory by contract: rerankHits returns the
+   * original order whenever anything is missing or unparseable, so search never depends on it.
+   */
+  async function rerankSearch(agent, query, hits, options = {}) {
+    const enabled = options.enabled ?? cfg.rerankSearch
+    if (!enabled) return { hits, reranked: false, reason: 'disabled' }
+    const target = memoryTarget(agent)
+    return rerankHits(query, hits, {
+      ...options, enabled: true,
+      llm: (prompt) => runLlm(target, prompt, 'memory-rerank', 500),
+    })
+  }
+
+  // injectionMaxChars travels with the host so memory_map can describe the card that was
+  // ACTUALLY built: the cap is configuration, and a snapshot built with a different cap would
+  // report a size the session never saw.
+  // Resolved once, here, where the config lives: tools.js has no access to cfg and a tool that
+  // reached for it would throw at call time (which is how memory_tasks first failed).
+  return { scheduler, schedulePath: cfg.schedulePath || defaultSchedulePath(), tasksNow: maybeBackupTasks, tasksRestore: maybeRestoreTasks, syncNow: () => runSync(true), consolidate: consolidateNow, refresh: refreshNow, status: statusNow, recover: recoverNow, rerankSearch, workspaceOf, historyOf, injectionMaxChars: cfg.injectionMaxChars }
+}