dsh-hypatia-auto-memory 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hypatia-auto-memory",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Event-driven Hypatia memory for DSH: automatic conversation logging via session events, queued background consolidation (span summaries + work-unit extraction) with a dedicated model route, and recall injection — zero per-call model work in the main session.",
   "type": "module",
   "main": "src/index.js",
@@ -53,6 +53,7 @@
     "@deepseek-ai/dsh": ">=0.1.7-rc.1",
     "@deepseek-ai/dsh-llm": "^0.1.7-rc.1",
     "@deepseek-ai/dsh-storage-domain": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.1",
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {

package/skills/hypatia-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hypatia-memory
-description: Long-term memory for DSH via hypatia. Conversation logging and background consolidation run automatically; retrieval is yours to drive. Use when the task touches past decisions, project conventions, prior bugs, or anything the user expects you to already know — and whenever the user says "read hypatia", "查一下 hypatia", "记住", "忘记".
+description: Long-term memory for DSH via hypatia. Conversation logging and background consolidation run automatically; retrieval is yours to drive. Use when the task touches past decisions, project conventions, prior bugs, or anything the user expects you to already know — and whenever the user says "read hypatia", "查一下 hypatia", "记住", "忘记". Also use when the user explicitly asks to summarise or consolidate a session now ("整理一下这个会话", "summarise this session").
 user-invocable: false
 allowed-tools: Bash, Read, Grep, Glob
 ---
@@ -198,6 +198,39 @@ cascade-deleted; remove them with `hypatia statement-delete <head> <relation>
 <tail>` when they would otherwise dangle. Deleted memories stay deleted — the
 collector's watermark has already moved past them.
 
+## Manual consolidation on request
+
+The automatic layer cuts spans on turn and token thresholds. Those thresholds
+pace an ongoing conversation; they are not a promise about *when* a summary
+exists. When the user asks for one **now** — "summarise this session", "整理一下
+这个会话", "把这段对话总结一下" — there is an action for it:
+
+```
+hypatia_summarize                              # the session you are running in
+hypatia_summarize {"sessionId": "<session-id>"} # or one the user names
+```
+
+It enqueues the span that is currently unsummarised, for the plugin's own
+background writer, on its dedicated model route. It returns immediately, so tell
+the user it is **queued**, not that a summary exists; the Memory tab's
+summarisation row catches up on its next poll.
+
+- **Trigger only on an explicit request.** Never call it because the session
+  feels long, because a turn just ended, or because you judge a summary would be
+  useful. The premise of this plugin is that a model left to decide when to
+  write memory does not write it: on the manual protocol, one of fifteen measured
+  sessions followed it, and only because the user asked directly. A
+  self-initiated call is that same failure with an extra model call attached.
+- **Do not** write `sum-*` entries yourself, and **do not** run the cascade by
+  hand. The plugin's writer is idempotent by name and owns the watermark — the
+  session-log `seq` range, which you cannot see. A hand-written summary gets a
+  different name, so the automatic layer later writes its own over the same
+  messages and the shelf carries both; and a batch the plugin did not choose
+  leaves an archive entry with a partial member set.
+- **Say that the composer has a command.** `/hypatia-summarize` queues exactly
+  the same work from the UI, without a model turn and without spending this
+  session's context. For a user who just wants it done, that is the cheaper path.
+
 ## Known gaps in the automatic layer
 
 Say so plainly if a user's expectation depends on one of these:
@@ -207,7 +240,18 @@ Say so plainly if a user's expectation depends on one of these:
   unrelated topics summarises them together.
 - **No `session-<id>` node** unless the host produced a session title or a
   compaction summary to build it from.
-- **Summary names are mechanical** (`sum-<session>-<from>-<to>`), not descriptive.
-  The descriptive title is the first heading inside the entry.
+- **Summary names are mechanical** (`sum-<session>-<from>-<to>` at tier 1,
+  `sum<level>-<digest>` above it), not descriptive. The descriptive title is the
+  first heading inside the entry.
+- **The summary layer is a cascade, not a flat list.** `summary 1` entries each
+  condense a span of messages. Once `cascade.batchSize` of one tier (16 by
+  default) have no `summary` edge archiving them, they are condensed into one
+  entry a tier up, tagged `summary 2`, and so on; the plugin stops creating tiers
+  past `summary 8`, a ceiling rather than an expected depth. `sum` is the
+  operational prefix for that whole layer (alongside `msg-`, `session-` and
+  `hypatia-dream-run-`), which is why every exclusion list skips it. What makes
+  an entry a cascade *member* is not its name but the pair "tagged `summary <N>`
+  and carrying no incoming `summary` edge" — the plugin's batches come from
+  hypatia's `$not-summaried`, which anti-joins on the edge.
 - **Work-unit dedup is best-effort** and degrades to "no relationship" whenever
   the shelf has no embedding model.

package/src/client/MemoryView.module.css

@@ -82,7 +82,8 @@
 
 .status,
 .hint,
-.error {
+.error,
+.notice {
   margin: 0;
   font-size: 12px;
   line-height: 1.6;
@@ -97,6 +98,10 @@
   color: var(--dsw-alias-label-error);
 }
 
+.notice {
+  color: var(--dsw-alias-label-secondary);
+}
+
 .group {
   display: flex;
   flex-direction: column;
@@ -177,6 +182,38 @@
   background: var(--dsw-alias-bg-layer-3);
 }
 
+/* Sits on the "consolidation" row, beside the gap it acts on. Disabled — not
+   hidden — once the session is caught up, so the control stays where the user
+   already found it. */
+.summarize {
+  appearance: none;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 6px;
+  background: none;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  font: inherit;
+  font-size: 11px;
+  padding: 1px 8px;
+  white-space: nowrap;
+}
+
+.summarize:hover:enabled {
+  border-color: var(--dsw-alias-label-dimmed);
+  color: var(--dsw-alias-label-primary);
+}
+
+.summarize:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: 1px;
+}
+
+.summarize:disabled {
+  border-color: var(--dsw-alias-border-l2);
+  color: var(--dsw-alias-label-dimmed);
+  cursor: default;
+}
+
 .failures {
   display: grid;
   gap: 6px;

package/src/client/MemoryView.tsx

@@ -22,11 +22,15 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import {
+  SUMMARIZE_REASON,
+  canSummarize,
   consolidationGap,
   mergeMemory,
   type FetchMemory,
   type MemoryEntry,
   type MemoryPayload,
+  type SummarizeMemory,
+  type SummarizeResult,
 } from './memory-client'
 import { NS } from './locales'
 import css from './MemoryView.module.css'
@@ -39,8 +43,43 @@ export type MemoryViewProps = {
   /** The session this tab is bound to; supplied by the session-scoped slot. */
   sessionId: string
   fetch: FetchMemory
+  /** Queues an explicit consolidation of one session; never runs the model here. */
+  summarize: SummarizeMemory
 } & PropsLocale<typeof NS>
 
+/** One line of feedback from an explicit consolidation request. */
+type Notice = { kind: 'ok' | 'error'; text: string }
+
+/**
+ * Render the Host's answer to one request.
+ *
+ * "Nothing to do" and "already queued" are not failures and do not read as one:
+ * the request was answered truthfully. Only a refusal — the feature is off, the
+ * route is missing, the session is gone — is shown as an error.
+ */
+function noticeFor(result: SummarizeResult, t: MemoryViewProps['t']): Notice {
+  if (result.queued) {
+    return {
+      kind: 'ok',
+      text: t('memorySummarizeQueued', { from: String(result.fromSeq), to: String(result.toSeq) }),
+    }
+  }
+  switch (result.reason) {
+    case SUMMARIZE_REASON.empty:
+      return { kind: 'ok', text: t('memorySummarizeEmpty') }
+    case SUMMARIZE_REASON.busy:
+      return { kind: 'ok', text: t('memorySummarizeBusy') }
+    case SUMMARIZE_REASON.disabled:
+      return { kind: 'error', text: t('memorySummarizeDisabled') }
+    case SUMMARIZE_REASON.unavailable:
+      return { kind: 'error', text: t('memorySummarizeUnavailable') }
+    case SUMMARIZE_REASON.unknownSession:
+      return { kind: 'error', text: t('memorySummarizeUnknown') }
+    default:
+      return { kind: 'error', text: t('memorySummarizeUnknownReason', { reason: result.reason }) }
+  }
+}
+
 /** Local wall-clock stamp for the freshness line. */
 function formatTime(epochMs: number): string {
   if (!Number.isFinite(epochMs) || epochMs <= 0) return '—'
@@ -98,10 +137,14 @@ function Entry({ entry, badge, open, onToggle, labels, t }: {
   )
 }
 
-export function MemoryView({ sessionId, fetch, t }: MemoryViewProps) {
+export function MemoryView({ sessionId, fetch, summarize, t }: MemoryViewProps) {
   const [payload, setPayload] = useState<MemoryPayload | undefined>(undefined)
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState('')
+  /** True while the Host is being asked to queue a consolidation. */
+  const [summarizing, setSummarizing] = useState(false)
+  /** The last explicit request's answer, cleared when the session switches. */
+  const [notice, setNotice] = useState<Notice | undefined>(undefined)
   /**
    * The entries the reader opened, by name. Absent means closed, which is the
    * default: a toggle survives the poll that replaces the payload, and an entry
@@ -153,6 +196,7 @@ export function MemoryView({ sessionId, fetch, t }: MemoryViewProps) {
     setPayload(undefined)
     setOverrides({})
     setContentAt(undefined)
+    setNotice(undefined)
     setLoading(true)
     void load(true)
   }, [load, sessionId])
@@ -178,6 +222,37 @@ export function MemoryView({ sessionId, fetch, t }: MemoryViewProps) {
     setOverrides((current) => ({ ...current, [name]: !open }))
   }, [])
 
+  /**
+   * Ask the Host to consolidate this session now.
+   *
+   * Only queues: the summary is written in the background, so the answer says
+   * what was accepted rather than what was written. A queued request refreshes
+   * the status so the "behind" figure catches up with the next poll; the
+   * watermark watch above then re-reads the shelf when consolidation lands.
+   */
+  const onSummarize = useCallback(() => {
+    setSummarizing(true)
+    setNotice(undefined)
+    void (async () => {
+      try {
+        const result = await summarize(sessionId)
+        if (activeSession.current !== sessionId) return
+        setNotice(noticeFor(result, t))
+        if (result.queued) void load(false)
+      } catch (failure) {
+        if (activeSession.current !== sessionId) return
+        setNotice({
+          kind: 'error',
+          text: t('memorySummarizeFailed', {
+            message: failure instanceof Error ? failure.message : String(failure),
+          }),
+        })
+      } finally {
+        if (activeSession.current === sessionId) setSummarizing(false)
+      }
+    })()
+  }, [load, sessionId, summarize, t])
+
   const session = payload?.session
   const content = payload?.content
   const summaries = content?.summaries ?? []
@@ -225,6 +300,10 @@ export function MemoryView({ sessionId, fetch, t }: MemoryViewProps) {
 
         {error !== '' ? <p className={css.error} role="status">{t('memoryLoadFailed', { message: error })}</p> : null}
 
+        {notice !== undefined
+          ? <p className={notice.kind === 'ok' ? css.notice : css.error} role="status">{notice.text}</p>
+          : null}
+
         {loading && payload === undefined
           ? <p className={css.status}>{t('memoryLoading')}</p>
           : session === undefined
@@ -249,6 +328,20 @@ export function MemoryView({ sessionId, fetch, t }: MemoryViewProps) {
                             ? t('memoryCaughtUp')
                             : t('memoryBehind', { behind: String(consolidationGap(session)) })}
                         </span>
+                        {/* Disabled rather than hidden once caught up: hiding it
+                            would make the user rediscover it the next time the
+                            session falls behind, which is exactly when they look
+                            for it. It sits on the row that states the gap, so it
+                            appears at the moment the gap does. */}
+                        <button
+                          type="button"
+                          className={css.summarize}
+                          disabled={summarizing || !canSummarize(session)}
+                          title={t('memorySummarizeHint')}
+                          onClick={onSummarize}
+                        >
+                          {summarizing ? t('memorySummarizing') : t('memorySummarize')}
+                        </button>
                       </dd>
                     </div>
                     <div className={css.row}>

package/src/client/index.tsx

@@ -29,7 +29,7 @@ import { SettingsCard } from './SettingsCard'
 import type { ConfigShape } from './SettingsCard'
 import type { LoadConsolidationModelCatalog } from './consolidation-models'
 import { MemoryView } from './MemoryView'
-import { fetchMemory, fetchShelves } from './memory-client'
+import { fetchMemory, fetchShelves, summarizeMemory } from './memory-client'
 import type { LoadShelfInventory } from './shelves'
 import { BUNDLE_CONFIG_SEAT, SETTINGS_TAB_SEAT, installPluginCard } from './plugin-card-seat'
 import { en, NS, zh } from './locales'
@@ -131,7 +131,7 @@ export function apply(ctx: Context): void {
         order: 20,
         locale: NS,
         label: () => t('viewMemory'),
-        inject: () => ({ fetch: fetchMemory }),
+        inject: () => ({ fetch: fetchMemory, summarize: summarizeMemory }),
       },
       MemoryView,
     ),

package/src/client/locales.ts

@@ -77,6 +77,17 @@ export const zh = {
   memoryConsolidated: '摘要整合',
   memoryCaughtUp: '已结清',
   memoryBehind: '较记录落后 {behind} 条',
+  memorySummarize: '立即整理',
+  memorySummarizing: '整理中…',
+  memorySummarizeHint: '不等阈值，立刻把这段尚未摘要的对话交给后台整合。已结清时按钮禁用但保留在原位，下次落后时不必重新找它。',
+  memorySummarizeQueued: '已入队：将整理第 {from} – {to} 条事件；摘要在后台由插件的专用模型路由写入，不会占用本会话的上下文。',
+  memorySummarizeEmpty: '已结清，没有需要整理的内容。',
+  memorySummarizeBusy: '同样的区间已有一次整合在队列中，无需重复触发。',
+  memorySummarizeDisabled: '整合功能已在设置中关闭。',
+  memorySummarizeUnavailable: '整合不可用：当前组合没有挂载模型路由。',
+  memorySummarizeUnknown: '这个会话已经不在内存中，无法整理。',
+  memorySummarizeUnknownReason: '未能整理：{reason}',
+  memorySummarizeFailed: '无法触发整理：{message}',
   memoryPending: '待整合内容',
   memoryPendingValue: '约 {tokens} token',
   memorySessionNode: '会话节点',
@@ -183,6 +194,17 @@ export const en = {
   memoryConsolidated: 'Summarisation',
   memoryCaughtUp: 'caught up',
   memoryBehind: '{behind} events behind the log',
+  memorySummarize: 'Summarise now',
+  memorySummarizing: 'Summarising…',
+  memorySummarizeHint: 'Consolidate the part of this conversation that has not been summarised yet, without waiting for the thresholds. Once caught up the button is disabled but stays in place, so it need not be rediscovered the next time the session falls behind.',
+  memorySummarizeQueued: 'Queued: events {from}–{to} will be summarised. The summary is written in the background on the plugin\'s own model route and costs this session no context.',
+  memorySummarizeEmpty: 'Nothing to summarise: the log is already consolidated.',
+  memorySummarizeBusy: 'A consolidation covering the same span is already queued.',
+  memorySummarizeDisabled: 'Consolidation is turned off in the settings.',
+  memorySummarizeUnavailable: 'Consolidation is unavailable: this composition mounted no model route for it.',
+  memorySummarizeUnknown: 'That session is no longer in memory, so it cannot be consolidated.',
+  memorySummarizeUnknownReason: 'Could not consolidate: {reason}',
+  memorySummarizeFailed: 'Could not start consolidation: {message}',
   memoryPending: 'Waiting to summarise',
   memoryPendingValue: '~{tokens} tokens',
   memorySessionNode: 'Session node',

package/src/client/memory-client.ts

@@ -15,6 +15,19 @@ import type { LoadShelfInventory, ShelfInfo, ShelfInventory } from './shelves'
 /** Route prefix the Host claims; the tab appends `/session`. */
 export const MEMORY_API_PREFIX = '/api/dsh-hypatia-auto-memory'
 
+/**
+ * Why an explicit consolidation request queued nothing, matching the Host's
+ * `SUMMARIZE_REASON` vocabulary (src/consolidator.js). Kept as named constants
+ * so the view's switch and the Host's answers cannot drift apart on a typo.
+ */
+export const SUMMARIZE_REASON = {
+  disabled: 'disabled',
+  empty: 'empty',
+  busy: 'busy',
+  unknownSession: 'unknown-session',
+  unavailable: 'unavailable',
+} as const
+
 /** One task that exhausted its attempts. */
 export interface FailedMemoryTask {
   kind: string
@@ -83,6 +96,33 @@ export interface MemoryPayload {
 /** Read one session's memory. `content` also asks the Host to read the shelf. */
 export type FetchMemory = (sessionId: string, options: { content: boolean }) => Promise<MemoryPayload>
 
+/** One explicit consolidation request's outcome, as the Host reports it. */
+export interface SummarizeResult {
+  sessionId: string
+  /** True when the Host accepted a span; false when there was nothing to do. */
+  queued: boolean
+  /** Empty when queued; otherwise one of {@link SUMMARIZE_REASON}. */
+  reason: string
+  /** The half-open span the Host cut, in session-log events. */
+  fromSeq: number
+  toSeq: number
+}
+
+/**
+ * Ask the Host to consolidate one session now.
+ *
+ * This only queues the same task the automatic trigger queues — the summary is
+ * written in the background on the plugin's dedicated model route — so the
+ * promise settles long before anything appears in the shelf. The tab's normal
+ * watermark poll is what shows the result.
+ */
+export type SummarizeMemory = (sessionId: string) => Promise<SummarizeResult>
+
+/** Whether "summarise now" has work to do for this session. */
+export function canSummarize(session: SessionMemoryStatus): boolean {
+  return session.known && !session.caughtUp
+}
+
 /**
  * The URL one refresh reads.
  * @param sessionId - the session the tab is bound to.
@@ -112,6 +152,62 @@ export const fetchMemory: FetchMemory = async (sessionId, { content }) => {
   return payload
 }
 
+/**
+ * The URL one explicit consolidation request POSTs to.
+ * @param sessionId - the session to consolidate.
+ * @returns a same-origin path with its query.
+ */
+export function summarizeUrl(sessionId: string): string {
+  const query = new URLSearchParams({ session: sessionId })
+  return `${MEMORY_API_PREFIX}/consolidate?${query.toString()}`
+}
+
+/**
+ * Ask the Host to consolidate one session now.
+ *
+ * `POST`, never `GET`: a write must not be reachable from a link or an image
+ * tag. The Host keeps the same self-authentication on this route as on the read
+ * ones (loopback socket, loopback `Host`, same-origin), and the body is empty —
+ * everything the request means is in the URL.
+ */
+export const summarizeMemory: SummarizeMemory = async (sessionId) => {
+  const response = await fetch(summarizeUrl(sessionId), {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { accept: 'application/json' },
+  })
+  const body: unknown = await response.json().catch(() => undefined)
+  if (!response.ok) {
+    const message = isRecord(body) && typeof body.error === 'string' ? body.error : `HTTP ${String(response.status)}`
+    throw new Error(message)
+  }
+  const result = parseSummarizeResult(body, sessionId)
+  if (result === undefined) throw new Error('the Host returned an unreadable consolidation answer')
+  return result
+}
+
+/**
+ * Read the Host's consolidation answer, defensively.
+ *
+ * A body without a boolean `queued` is unreadable rather than "not queued": the
+ * whole point of the answer is to distinguish "accepted" from "nothing to do",
+ * and guessing would put a wrong sentence in front of the user.
+ *
+ * @param value - the parsed response body.
+ * @param sessionId - the session that was asked for.
+ * @returns the result, or undefined when the body is not one.
+ */
+export function parseSummarizeResult(value: unknown, sessionId: string): SummarizeResult | undefined {
+  if (!isRecord(value) || typeof value.queued !== 'boolean') return undefined
+  return {
+    sessionId: str(value.sessionId) || sessionId,
+    queued: value.queued,
+    reason: str(value.reason),
+    fromSeq: num(value.fromSeq),
+    toSeq: num(value.toSeq),
+  }
+}
+
 /**
  * Fetch the shelf listing for the settings card.
  *

package/src/consolidator.js

@@ -84,6 +84,29 @@ export function budgetForEffort(baseTokens, effort) {
   return outputBudget(baseTokens, effort === THINKING_OFF_EFFORT)
 }
 
+/** The one queue kind explicit requests and the automatic triggers both use. */
+const CONSOLIDATE_KIND = 'consolidate'
+
+/**
+ * Why an explicit "summarise this session now" request queued nothing.
+ *
+ * The three faces (slash command, Memory tab button, agent tool) all report
+ * from this vocabulary rather than inventing their own wording, because they
+ * all call the same host action and must tell the user the same truth.
+ */
+export const SUMMARIZE_REASON = Object.freeze({
+  /** The plugin or its consolidation half is switched off in the config. */
+  Disabled: 'disabled',
+  /** Everything logged is already consolidated: there is no span to cut. */
+  Empty: 'empty',
+  /** A queued or running task already covers the whole requested span. */
+  Busy: 'busy',
+  /** No session with that id is live or reachable through persistence. */
+  Unknown: 'unknown-session',
+  /** No consolidation half is mounted, so nothing can run (no model route). */
+  Unavailable: 'unavailable',
+})
+
 /** Distinguishes permanent failures (no retry value) from transient ones. */
 export class PermanentConsolidationError extends Error {
   constructor(message) {
@@ -398,7 +421,6 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
     if ((state.pendingTokens ?? 0) < tokenFloor) {
       return { resetTokens: false, advanceCheckpoint: false }
     }
-    const current = progress.get(sessionId) ?? EMPTY_PROGRESS
     // Awaited: the resolver falls back to persistence for a session the store
     // will never publish again (see persisted-session.js).
     const session = await sessions.get(sessionId)
@@ -406,24 +428,11 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
       status.warn(`consolidation deferred for ${sessionId}: session not live`)
       return { resetTokens: false, advanceCheckpoint: false }
     }
-    const fromSeq = consolidationStart(current, session)
-    const toSeq = Math.min(session.seq ?? 0, current.lastLoggedSeq)
-    if (toSeq <= fromSeq) {
+    const span = await enqueueSpan(sessionId, session)
+    if (span === undefined) {
       return { resetTokens: false, advanceCheckpoint: false }
     }
-    const project = await projectFor(session)
-    // Immediate: the thresholds already decided this span is ready. Riding the
-    // flush window only delayed it by `flushWindowMs` (two minutes by default),
-    // and a restart inside that window left the task persisted but unscheduled.
-    await queue.enqueue({
-      kind: 'consolidate',
-      sessionId,
-      fromSeq,
-      toSeq,
-      project,
-      immediate: true,
-    })
-    status.info(`consolidation scheduled: ${sessionId} [${fromSeq}, ${toSeq})`)
+    status.info(`consolidation scheduled: ${sessionId} [${span.fromSeq}, ${span.toSeq})`)
     return { resetTokens: true, advanceCheckpoint: true }
   }
 
@@ -543,6 +552,39 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
     }
   }
 
+  /**
+   * The one place a consolidation span is cut and queued.
+   *
+   * Every automatic trigger and every explicit user request goes through this,
+   * so the range arithmetic (`fromSeq` never inside a fork's inherited prefix,
+   * `toSeq` never past what has been logged) and the task shape exist once.
+   *
+   * @param {string} sessionId
+   * @param {any} session
+   * @returns {Promise<{fromSeq: number, toSeq: number} | undefined>} the span,
+   *   or undefined when there is nothing to cut.
+   */
+  async function enqueueSpan(sessionId, session) {
+    const current = progress.get(sessionId) ?? EMPTY_PROGRESS
+    const fromSeq = consolidationStart(current, session)
+    const toSeq = Math.min(session?.seq ?? 0, current.lastLoggedSeq)
+    if (toSeq <= fromSeq) return undefined
+    const project = await projectFor(session)
+    // Immediate: the caller already decided this span is ready — the thresholds
+    // were met, the session is ending, or a human asked. Riding the flush window
+    // only delayed it by `flushWindowMs` (two minutes by default), and a restart
+    // inside that window left the task persisted but unscheduled.
+    await queue.enqueue({
+      kind: CONSOLIDATE_KIND,
+      sessionId,
+      fromSeq,
+      toSeq,
+      project,
+      immediate: true,
+    })
+    return { fromSeq, toSeq }
+  }
+
   /**
    * Final consolidation for a session that is ending.
    *
@@ -559,21 +601,64 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
   async function onSessionEnd(sessionId, session) {
     const config = getConfig()
     if (config.enabled === false || config.consolidation.enabled === false) return false
+    const span = await enqueueSpan(sessionId, session)
+    if (span === undefined) return false
+    status.info(`consolidation scheduled at session end: ${sessionId} [${span.fromSeq}, ${span.toSeq})`)
+    return true
+  }
+
+  /**
+   * Consolidate a session because a HUMAN asked for it right now.
+   *
+   * Same path as {@link onSessionEnd} — same span arithmetic, same task, same
+   * executor — with one difference: the session is not ending, so the cut is
+   * only a cut. The span is `[watermark, min(seq, lastLoggedSeq))` at the
+   * moment of the request, and everything appended afterwards waits for the
+   * next trigger exactly as it would have. Nothing is frozen.
+   *
+   * The thresholds are deliberately bypassed. They pace an ongoing
+   * conversation; an explicit request IS the reason to cut now, and the
+   * measured gap this exists for is 151 logged events against a token floor
+   * that had only accumulated 645 — a request cannot wait for a gate that may
+   * never open. The config switches are NOT bypassed: an explicit request is
+   * not a reason to write while the user has the plugin or its consolidation
+   * half turned off.
+   *
+   * @param {string} sessionId
+   * @returns {Promise<{sessionId: string, queued: boolean, reason: string,
+   *   fromSeq: number, toSeq: number}>} `reason` is '' when queued, otherwise
+   *   one of {@link SUMMARIZE_REASON}.
+   */
+  async function consolidateNow(sessionId) {
+    const config = getConfig()
+    if (config.enabled === false || config.consolidation.enabled === false) {
+      return { sessionId, queued: false, reason: SUMMARIZE_REASON.Disabled, fromSeq: 0, toSeq: 0 }
+    }
+    const session = await sessions.get(sessionId)
+    if (session === undefined) {
+      status.warn(`consolidation requested for ${sessionId}, but the session is not available`)
+      return { sessionId, queued: false, reason: SUMMARIZE_REASON.Unknown, fromSeq: 0, toSeq: 0 }
+    }
     const current = progress.get(sessionId) ?? EMPTY_PROGRESS
     const fromSeq = consolidationStart(current, session)
     const toSeq = Math.min(session?.seq ?? 0, current.lastLoggedSeq)
-    if (toSeq <= fromSeq) return false
-    const project = await projectFor(session)
-    await queue.enqueue({
-      kind: 'consolidate',
-      sessionId,
-      fromSeq,
-      toSeq,
-      project,
-      immediate: true,
-    })
-    status.info(`consolidation scheduled at session end: ${sessionId} [${fromSeq}, ${toSeq})`)
-    return true
+    if (toSeq <= fromSeq) {
+      return { sessionId, queued: false, reason: SUMMARIZE_REASON.Empty, fromSeq, toSeq }
+    }
+    // A task already accepted for this range makes the request redundant: it is
+    // the same work. Only work that is actually scheduled counts — a `deferred`
+    // record is waiting for a session that is, by construction, available here
+    // (the lookup above just answered), so this request is re-enqueueing it,
+    // which is what schedules it. Nothing that falls through loses events:
+    // `enqueue` widens the record and the queue re-runs the uncovered tail.
+    const existing = queue.peek?.(CONSOLIDATE_KIND, sessionId)
+    const scheduled = existing !== undefined && (existing.status === 'pending' || existing.status === 'running')
+    if (scheduled && toSeq <= existing.toSeq) {
+      return { sessionId, queued: false, reason: SUMMARIZE_REASON.Busy, fromSeq, toSeq }
+    }
+    await enqueueSpan(sessionId, session)
+    status.info(`consolidation scheduled on request: ${sessionId} [${fromSeq}, ${toSeq})`)
+    return { sessionId, queued: true, reason: '', fromSeq, toSeq }
   }
 
   /** Queue executor for one consolidate task. */
@@ -797,6 +882,7 @@ export function createConsolidator({ queue, progress, sessions, llm, cli, writer
   return {
     onTurnEnd,
     onSessionEnd,
+    consolidateNow,
     adjudicate,
     // The pure priority selector, shared with the cascade: both executors hold
     // their own `task.attempts`, so neither needs a place of its own in a