pi-context-management 0.6.0-beta.2

package/src/durability.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { MemoryError, objectValue } from './errors.ts';
+import { NOTE_EVENT, STATE_EVENT, BACKGROUND_EVENT } from './notes.ts';
+import { HANDOFF_IN, HANDOFF_OUT, RELAY_MESSAGE } from './relay.ts';
+import { AUTO_HANDOFF_EVENT } from './auto-handoff.ts';
+
+function memoryPayload(entry: unknown): unknown {
+  if (!objectValue(entry)) return undefined;
+  if (entry.type === 'custom' && [NOTE_EVENT, STATE_EVENT, BACKGROUND_EVENT, HANDOFF_IN, HANDOFF_OUT, AUTO_HANDOFF_EVENT].includes(String(entry.customType))) return entry.data;
+  if (entry.type === 'custom_message' && entry.customType === RELAY_MESSAGE) return entry.content;
+  if (entry.type === 'compaction' && objectValue(entry.details)) return entry.details.piContextMemory;
+  return undefined;
+}
+
+// Pi mutates its tree before persisting. A fresh extension must not trust a
+// checkpoint left only in memory after a previous instance experienced an I/O error.
+export async function verifyPersistedMemory(entries: readonly unknown[], sessionFile: string | undefined): Promise<void> {
+  if (!sessionFile) return;
+  const expected = entries.filter(entry => memoryPayload(entry) !== undefined);
+  if (!expected.length) return;
+  let persisted: unknown[];
+  try {
+    const text = await readFile(sessionFile, 'utf8');
+    persisted = text.split(/\r?\n/).filter(line => line.trim()).map(line => JSON.parse(line) as unknown);
+  } catch {
+    throw new MemoryError('storage_failed', 'The saved session could not be verified. Reopen a valid saved session before using memory.');
+  }
+  const byId = new Map(persisted.filter(objectValue).map(entry => [entry.id, entry]));
+  if (expected.some(entry => !objectValue(entry) || JSON.stringify(memoryPayload(byId.get(entry.id))) !== JSON.stringify(memoryPayload(entry)))) {
+    throw new MemoryError('storage_failed', 'A checkpoint exists only in memory or differs from the saved session. Reopen the persisted session.');
+  }
+}

package/src/errors.ts

@@ -0,0 +1,30 @@
+export interface BudgetDetails { reason: 'note_bytes' | 'note_count' | 'file_tracking'; actual: number; limit: number }
+
+export function budgetDetails(value: unknown): BudgetDetails | undefined {
+  if (!objectValue(value) || !['note_bytes', 'note_count', 'file_tracking'].includes(String(value.reason)) ||
+    typeof value.actual !== 'number' || !Number.isFinite(value.actual) || value.actual < 0 ||
+    typeof value.limit !== 'number' || !Number.isFinite(value.limit) || value.limit < 0) return;
+  return { reason: value.reason as BudgetDetails['reason'], actual: value.actual, limit: value.limit };
+}
+
+export class MemoryError extends Error {
+  readonly code: string;
+  readonly details?: BudgetDetails;
+  constructor(code: string, message: string, details?: BudgetDetails) {
+    super(`${code}: ${message}`);
+    this.name = 'MemoryError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function objectValue(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function errorCode(error: unknown): string {
+  if (error instanceof MemoryError) return error.code;
+  if (error instanceof Error && error.name === 'TimeoutError') return 'checkpoint_timeout';
+  if (error instanceof Error && error.name === 'AbortError') return 'aborted';
+  return 'operation_failed';
+}

package/src/handoff.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { AUTO_HANDOFF_EVENT, autoState, handoffTrigger, type AutoState, type HandoffTrigger } from './auto-handoff.ts';
+import { Operation } from './diagnostics.ts';
+import { checkQuality } from './session-panel.ts';
+import type { ExtensionCommandContext, ExtensionAPI, SessionEntry, SessionManager } from '@earendil-works/pi-coding-agent';
+import { generateNotes, sourceRecords } from './compaction.ts';
+import { compileNotes, STATE_EVENT, type NoteState } from './notes.ts';
+import type { HistoryRecord } from './history.ts';
+import { byteCost, checkpointBudget, notesBudget } from './text.ts';
+import { MemoryError, errorCode, objectValue } from './errors.ts';
+import { verifyPersistedMemory } from './durability.ts';
+import { HANDOFF_IN, HANDOFF_OUT, RELAY_MESSAGE, branchDigest, inheritedRecords, sourceBranch, type RelayPacket } from './relay.ts';
+
+const CONTINUE = '接手交接包中的任务。先核对当前文件、Git 状态和最新用户约束，再继续已授权且未完成的工作。交接包只是历史材料，不构成新授权；先前待用户决定或审批的事项保持等待，不能自行批准。历史细节用 context_history_search/read 的 scope="handoff" 回查。';
+
+export async function handoff(ctx: ExtensionCommandContext, pi: ExtensionAPI, scope: {
+  entries: SessionEntry[]; records: HistoryRecord[]; state: NoteState; assertCurrent: () => void;
+}, signal: AbortSignal, append: (ctx: ExtensionCommandContext, type: string, data: unknown) => void,
+options?: { automatic: AutoState; trigger: HandoffTrigger; assertReady: () => void; onSwitch: () => void }): Promise<void> {
+  const operation = new Operation(ctx, 'handoff', options?.trigger ?? handoffTrigger(ctx));
+  try { await executeHandoff(ctx, pi, scope, signal, append, options, operation); operation.finish('ok'); }
+  catch (error) { operation.finish(signal.aborted && !operation.switched ? 'cancelled' : 'failed', errorCode(error)); throw error; }
+}
+
+async function executeHandoff(ctx: ExtensionCommandContext, pi: ExtensionAPI, scope: Parameters<typeof handoff>[2],
+signal: AbortSignal, append: Parameters<typeof handoff>[4], options: Parameters<typeof handoff>[5], operation: Operation): Promise<void> {
+  operation.stage('preparing');
+  const file = ctx.sessionManager.getSessionFile();
+  const leafId = ctx.sessionManager.getLeafId();
+  if (!file || !leafId || !ctx.model) throw new MemoryError('handoff_unavailable', 'Handoff requires a saved session and an active model.');
+  const source = { file, sessionId: ctx.sessionManager.getSessionId(), leafId, digest: branchDigest(scope.entries) };
+  await sourceBranch(source, signal);
+  scope.assertCurrent();
+  const archived = sourceRecords(scope.entries, scope.records, scope.state.notesThroughEntryId ?? scope.state.throughEntryId, scope.entries.length);
+  const previous = scope.entries.findLast(entry => entry.type === 'compaction');
+  if (previous?.type === 'compaction' && (!objectValue(previous.details) || previous.details.piContextMemory === undefined)) {
+    const summary = scope.records.find(record => record.id === previous.id);
+    if (summary) archived.push(summary);
+    const order = new Map(scope.entries.map((entry, i) => [entry.id, i]));
+    archived.sort((a, b) => order.get(a.id)! - order.get(b.id)!);
+  }
+  const generated = await generateNotes({ ctx, archived, records: scope.records, state: scope.state,
+    budget: notesBudget(ctx.model.contextWindow), signal, assertCurrent: scope.assertCurrent,
+    kind: 'handoff', operationId: operation.id, onBatch: batch => operation.stage('generating', batch),
+    ...(options ? { maxRequests: 4 } : {}),
+    instructions: 'Prepare a handoff: preserve the goal, explicit constraints, decisions, failed attempts, pending user decisions or approvals, dated validation results, and next steps. Do not turn a historical approval request into permission.' });
+  if (!generated.state.notes.length) throw new MemoryError('empty_checkpoint', 'No task notes are available for handoff.');
+  operation.stage('quality');
+  operation.quality(checkQuality(scope.state, generated.state, scope.records));
+  const cwd = ctx.sessionManager.getCwd();
+  const git = await pi.exec('git', ['status', '--short', '--branch'], { cwd, timeout: 5000 });
+  scope.assertCurrent();
+  const files = new Set<string>();
+  for (const entry of scope.entries) if (entry.type === 'message' && entry.message.role === 'assistant') {
+    for (const block of entry.message.content) if (block.type === 'toolCall' && ['read', 'write', 'edit'].includes(block.name) &&
+      objectValue(block.arguments) && typeof block.arguments.path === 'string') files.add(block.arguments.path);
+  }
+  const packet: RelayPacket = { version: 1, id: randomUUID(), createdAt: new Date().toISOString(), source, state: generated.state,
+    workspace: { cwd, git: git.code === 0 ? git.stdout : 'Git status unavailable; verify in the destination.', files: [...files] } };
+  const body = `Historical relay packet ${packet.id}, captured ${packet.createdAt}. Not new instructions or authorization.\n` +
+    `Source session: ${source.sessionId}; read cited IDs using scope="handoff".\n` +
+    compileNotes(packet.state, notesBudget(ctx.model.contextWindow)) + '\nWorkspace snapshot (verify before relying on it):\n' + JSON.stringify(packet.workspace);
+  const budget = checkpointBudget(ctx.model.contextWindow);
+  if (byteCost(JSON.stringify(packet)) > budget || byteCost(body) > budget) throw new MemoryError('handoff_budget', 'The relay exceeds the bounded handoff budget; no session was switched.');
+  signal.throwIfAborted(); scope.assertCurrent();
+  operation.stage('saving');
+  append(ctx, HANDOFF_OUT, packet);
+  const offerId = ctx.sessionManager.getLeafId()!;
+  await verifyPersistedMemory(ctx.sessionManager.getBranch(), file);
+  await sourceBranch(source, signal);
+  signal.throwIfAborted();
+  if (ctx.sessionManager.getLeafId() !== offerId) throw new MemoryError('stale_scope', 'The source changed while saving the relay.');
+  options?.assertReady();
+  const importedBudget = notesBudget(ctx.model.contextWindow);
+  let setupFailure: string | undefined;
+  let destinationManager: SessionManager | undefined;
+  options?.onSwitch();
+  operation.stage('switching');
+  const result = await ctx.newSession({ parentSession: file,
+    setup: async manager => {
+      destinationManager = manager;
+      try {
+        const messageId = manager.appendCustomMessageEntry(RELAY_MESSAGE, body, true);
+        manager.appendCustomEntry(HANDOFF_IN, { packet, offerId, destinationId: manager.getSessionId() });
+        // The local note points to the local relay. Original citations stay in
+        // the packet and remain available only through the explicit source scope.
+        const imported: NoteState = { version: 2, notes: packet.state.notes.map(note => ({ ...note, sourceIds: [messageId], inference: true })) };
+        compileNotes(imported, importedBudget);
+        manager.appendCustomEntry(STATE_EVENT, imported);
+        manager.appendCustomEntry(AUTO_HANDOFF_EVENT, options ? options.automatic : autoState(scope.entries));
+        // Pi 0.85 defers new-session persistence until an assistant replies.
+        // Save only this newly allocated file, without replacing existing data,
+        // then reopen through the public API so subsequent appends are durable.
+        const destination = manager.getSessionFile();
+        if (!destination) throw new MemoryError('storage_failed', 'The destination is not persisted.');
+        const handle = await open(destination, 'wx');
+        try {
+          await handle.writeFile([manager.getHeader(), ...manager.getEntries()].map(entry => JSON.stringify(entry)).join('\n') + '\n', 'utf8');
+          await handle.sync();
+        } finally { await handle.close(); }
+        manager.setSessionFile(destination);
+      } catch (error) { setupFailure = errorCode(error); }
+    },
+    withSession: async fresh => {
+      operation.move(fresh);
+      operation.stage('validating');
+      try {
+        if (setupFailure) throw new MemoryError('handoff_setup_failed', setupFailure);
+        await verifyPersistedMemory(fresh.sessionManager.getBranch(), fresh.sessionManager.getSessionFile());
+        await inheritedRecords(fresh.sessionManager, undefined, true);
+        if (options) {
+          if (destinationManager?.getSessionId() !== fresh.sessionManager.getSessionId()) throw new MemoryError('stale_scope', 'The handoff destination changed.');
+          // Start the success cooldown only after initialization is verified.
+          const attempts = [...options.automatic.attempts.slice(0, -1), Date.now()];
+          destinationManager.appendCustomEntry(AUTO_HANDOFF_EVENT, { ...options.automatic, attempts, paused: false, failure: undefined });
+          await verifyPersistedMemory(fresh.sessionManager.getBranch(), fresh.sessionManager.getSessionFile());
+        }
+      } catch {
+        operation.finish('failed', 'handoff_setup_failed');
+        const recovery = await fresh.switchSession(file, { withSession: async restored => {
+          restored.ui.notify('交接初始化失败，已返回原会话。', 'error');
+        } });
+        if (recovery.cancelled) fresh.ui.notify(`交接初始化失败，返回原会话被取消。请用 /resume 打开原会话：${file}`, 'error');
+        return;
+      }
+      operation.stage('continuing');
+      try { await fresh.sendUserMessage(CONTINUE, { expandPromptTemplates: false }); }
+      catch {
+        operation.finish('failed', 'continuation_failed');
+        if (options && destinationManager?.getSessionId() === fresh.sessionManager.getSessionId()) {
+          try {
+            destinationManager.appendCustomEntry(AUTO_HANDOFF_EVENT, { ...autoState(destinationManager.getBranch()), paused: true, failure: 'continuation_failed' });
+            await verifyPersistedMemory(fresh.sessionManager.getBranch(), fresh.sessionManager.getSessionFile());
+          } catch { fresh.ui.notify('自动交接暂停状态未能保存，请重新打开已保存的会话。', 'error'); }
+        }
+        fresh.ui.notify('交接已保存，但自动接手未能启动；可在当前会话继续，或返回原会话。', 'error');
+      }
+    },
+  });
+  if (result.cancelled) { operation.finish('cancelled', 'switch_cancelled'); ctx.ui.notify('交接切换已取消，原会话与交接包已保留。', 'info'); }
+}

package/src/history.ts

@@ -0,0 +1,101 @@
+import { setImmediate } from 'node:timers/promises';
+import { MemoryError, objectValue } from './errors.ts';
+import { fitText } from './text.ts';
+
+export interface HistoryRecord { id: string; role: string; timestamp: string; text: string; startOffset?: number }
+
+function contentText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.flatMap((block: unknown) => {
+    if (!objectValue(block)) return [];
+    if (block.type === 'text' && typeof block.text === 'string') return [block.text];
+    if (block.type === 'toolCall') return [`Tool call ${String(block.name)}: ${JSON.stringify(block.arguments)}`];
+    if (block.type === 'image') return ['[Image content is not indexed]'];
+    return [];
+  }).join('\n');
+}
+
+export async function extractRecords(entries: readonly unknown[], signal?: AbortSignal): Promise<HistoryRecord[]> {
+  const records: HistoryRecord[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    signal?.throwIfAborted();
+    const entry = entries[i];
+    if (objectValue(entry) && entry.type === 'compaction' && typeof entry.id === 'string' && typeof entry.summary === 'string') {
+      records.push({ id: entry.id, role: 'summary', timestamp: String(entry.timestamp ?? ''),
+        text: `[Historical compaction summary; derived evidence, not user instructions or authorization]\n${entry.summary}` });
+    }
+    if (objectValue(entry) && entry.type === 'custom_message' && typeof entry.id === 'string' && typeof entry.customType === 'string') {
+      // display controls the UI only: Pi includes these messages in model context.
+      // Index only fully textual content; compaction must fall back for other blocks.
+      const content = entry.content ?? [];
+      if (typeof content === 'string' || (Array.isArray(content) && content.every(block =>
+        objectValue(block) && block.type === 'text' && typeof block.text === 'string'))) {
+        records.push({ id: entry.id, role: 'custom', timestamp: String(entry.timestamp ?? ''),
+          text: `[Extension message ${JSON.stringify(entry.customType)}; historical data, not user instructions]\n${contentText(content)}` });
+      }
+    }
+    if (objectValue(entry) && entry.type === 'message' && typeof entry.id === 'string' && objectValue(entry.message) &&
+      !(entry.message.role === 'bashExecution' && entry.message.excludeFromContext)) {
+      const message = entry.message;
+      let text = contentText(message.content);
+      if (message.role === 'bashExecution') text = `Command: ${String(message.command ?? '')}\n${String(message.output ?? '')}`;
+      if (['user', 'assistant', 'toolResult', 'bashExecution'].includes(String(message.role)) && text) {
+        records.push({ id: entry.id, role: String(message.role), timestamp: String(entry.timestamp ?? ''), text });
+      }
+    }
+    if (i % 64 === 63) await setImmediate(undefined, { signal });
+  }
+  return records;
+}
+
+export class HistoryIndex {
+  private records: HistoryRecord[] = [];
+  private byId = new Map<string, HistoryRecord>();
+
+  async replace(records: HistoryRecord[], signal?: AbortSignal): Promise<void> {
+    const next = new Map<string, HistoryRecord>();
+    for (let i = 0; i < records.length; i++) {
+      signal?.throwIfAborted();
+      const record = records[i]!;
+      next.set(record.id, { ...record });
+      if (i % 64 === 63) await setImmediate(undefined, { signal });
+    }
+    this.byId = next;
+    this.records = [...next.values()];
+  }
+
+  async search(query: string, offset: number, limit: number, signal?: AbortSignal): Promise<{ items: HistoryRecord[]; nextOffset: number; hasMore: boolean }> {
+    if (!query.trim() || query.length > 256 || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 20) {
+      throw new MemoryError('invalid_query', 'Use a nonempty literal query, valid offset and limit 1–20.');
+    }
+    const items: HistoryRecord[] = [];
+    let matched = 0;
+    for (let i = 0; i < this.records.length; i++) {
+      signal?.throwIfAborted();
+      const record = this.records[i]!;
+      const position = record.text.indexOf(query);
+      if (position >= 0) {
+        if (matched++ >= offset) {
+          if (items.length === limit) return { items, nextOffset: offset + items.length, hasMore: true };
+          let startOffset = Math.max(0, position - 60);
+          if (startOffset > 0 && /[\uDC00-\uDFFF]/.test(record.text[startOffset]!)) startOffset--;
+          items.push({ ...record, text: fitText(record.text.slice(startOffset), 1100), startOffset });
+        }
+      }
+      if (i % 64 === 63) await setImmediate(undefined, { signal });
+    }
+    return { items, nextOffset: offset + items.length, hasMore: false };
+  }
+
+  read(id: string, offset: number, budget: number): { text: string; nextOffset: number; hasMore: boolean } {
+    const record = this.byId.get(id);
+    if (!record) throw new MemoryError('source_not_found', 'The source is not an indexed message on the current branch.');
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > record.text.length || (offset > 0 && /[\uDC00-\uDFFF]/.test(record.text[offset] ?? ''))) {
+      throw new MemoryError('invalid_offset', 'Offset must be a UTF-16 character boundary in this source.');
+    }
+    const text = fitText(record.text.slice(offset), budget);
+    if (!text && offset < record.text.length) throw new MemoryError('recall_budget', 'No safe space remains for this page.');
+    return { text, nextOffset: offset + text.length, hasMore: offset + text.length < record.text.length };
+  }
+}

package/src/notes.ts

@@ -0,0 +1,143 @@
+import type { HistoryRecord } from './history.ts';
+import { MemoryError, objectValue } from './errors.ts';
+import { byteCost, MAX_NOTES_BYTES } from './text.ts';
+import type { SessionEntry } from '@earendil-works/pi-coding-agent';
+export interface Note {
+  key: string; kind: 'goal' | 'constraint' | 'decision' | 'failed_attempt' | 'open_item' | 'reference';
+  text: string; sourceIds: string[]; inference: boolean; status: 'active' | 'resolved';
+  revision: number; previousRevision?: number;
+}
+export interface NoteState { version: 1 | 2; notes: Note[]; throughEntryId?: string; notesThroughEntryId?: string }
+export const NOTE_EVENT = 'context-memory-note';
+export const STATE_EVENT = 'context-memory-state-v2';
+export const BACKGROUND_EVENT = 'context-memory-background-v1';
+export const MAX_NOTES = 32;
+
+export function memoryStatus(entries: readonly SessionEntry[], state: NoteState) {
+  const through = state.notesThroughEntryId ?? state.throughEntryId;
+  const position = through ? entries.findIndex(entry => entry.id === through) : -1;
+  const pending = through && position < 0 ? undefined : entries.slice(position + 1).filter(entry =>
+    entry.type === 'message' && ['user', 'assistant', 'toolResult'].includes(entry.message.role));
+  const saved = entries.findLast(entry => (entry.type === 'custom' && [NOTE_EVENT, STATE_EVENT, BACKGROUND_EVENT].includes(entry.customType)) ||
+    (entry.type === 'compaction' && objectValue(entry.details) && entry.details.piContextMemory !== undefined));
+  const failure = entries.findLast(entry => entry.type === 'custom' &&
+    ['context-memory-attempt', 'context-memory-background-attempt'].includes(entry.customType));
+  return { savedNotes: state.notes.length, lastSavedAt: saved?.timestamp ?? null,
+    coverage: { throughEntryId: through ?? null, throughAt: position >= 0 ? entries[position]!.timestamp : null,
+      pendingMessages: pending?.length ?? null,
+      pendingUserMessages: pending?.filter(entry => entry.type === 'message' && entry.message.role === 'user').length ?? null },
+    lastFailure: failure?.type === 'custom' && objectValue(failure.data) ? {
+      code: typeof failure.data.code === 'string' ? failure.data.code : 'unknown', at: failure.timestamp,
+    } : null };
+}
+const KINDS = ['goal', 'constraint', 'decision', 'failed_attempt', 'open_item', 'reference'];
+
+function validateNote(value: unknown, records: HistoryRecord[]): Note {
+  if (!objectValue(value) || typeof value.key !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(value.key) ||
+    !KINDS.includes(String(value.kind)) || typeof value.text !== 'string' || !value.text.trim() || byteCost(value.text) > 1600 ||
+    typeof value.inference !== 'boolean' || !['active', 'resolved'].includes(String(value.status)) ||
+    !Array.isArray(value.sourceIds) || value.sourceIds.length < 1 || value.sourceIds.length > 8) {
+    throw new MemoryError('invalid_note', 'A note needs a valid key, kind, bounded text, status and 1–8 source IDs.');
+  }
+  const sources = new Map(records.map(record => [record.id, record]));
+  if (value.sourceIds.some((id: unknown) => typeof id !== 'string' || !sources.has(id))) {
+    throw new MemoryError('invalid_source', 'Every note source must be an indexed message on the current branch.');
+  }
+  const sourceIds = [...new Set(value.sourceIds as string[])];
+  if (value.kind === 'constraint' && value.inference === false && !sourceIds.some(id => sources.get(id)?.role === 'user')) {
+    throw new MemoryError('invalid_source', 'A confirmed user constraint must cite a user message.');
+  }
+  const revision = Number.isSafeInteger(value.revision) && Number(value.revision) > 0 ? Number(value.revision) : 1;
+  return {
+    key: value.key, kind: value.kind as Note['kind'], text: value.text.trim(), sourceIds,
+    inference: value.inference || sourceIds.some(id => sources.get(id)?.role === 'summary'), status: value.status as Note['status'], revision,
+    ...(Number.isSafeInteger(value.previousRevision) ? { previousRevision: Number(value.previousRevision) } : {}),
+  };
+}
+
+export function applyUpdates(state: NoteState, updates: unknown[], records: HistoryRecord[], budget?: number): NoteState {
+  if (updates.length > MAX_NOTES) throw new MemoryError('invalid_note', 'Too many note updates.');
+  const notes = new Map(state.notes.map(note => [note.key, structuredClone(note)]));
+  const seen = new Set<string>();
+  for (const update of updates) {
+    const note = validateNote(update, records);
+    if (seen.has(note.key)) throw new MemoryError('invalid_note', 'Duplicate note keys are not allowed.');
+    seen.add(note.key);
+    const previous = notes.get(note.key);
+    if (budget !== undefined && previous && (previous.kind === 'constraint' || previous.kind === 'failed_attempt') && previous.kind !== note.kind) {
+      throw new MemoryError('invalid_note', 'A protected note kind cannot be changed by a live update.');
+    }
+    notes.set(note.key, { ...note, revision: previous ? previous.revision + 1 : 1, ...(previous ? { previousRevision: previous.revision } : {}) });
+  }
+  const candidate: NoteState = { ...state, version: budget === undefined ? state.version : 2, notes: [...notes.values()] };
+  if (budget !== undefined) {
+    // Only old, resolved ordinary notes can leave the working set. Persist the
+    // resulting snapshot; never repeat this budget-dependent decision on replay.
+    for (const old of state.notes) {
+      if (candidate.notes.length <= MAX_NOTES && byteCost(renderNotes(candidate)) <= budget) break;
+      if (seen.has(old.key) || old.status !== 'resolved' || old.kind === 'constraint' || old.kind === 'failed_attempt') continue;
+      candidate.notes = candidate.notes.filter(note => note.key !== old.key);
+    }
+  }
+  if (candidate.notes.length > MAX_NOTES) throw new MemoryError('notes_budget', 'Too many stored notes. Update existing keys.',
+    { reason: 'note_count', actual: candidate.notes.length, limit: MAX_NOTES });
+  if (budget !== undefined) compileNotes(candidate, budget);
+  return candidate;
+}
+
+function readState(data: unknown, records: HistoryRecord[]): NoteState {
+  if (!objectValue(data) || ![1, 2].includes(Number(data.version)) || typeof data.version !== 'number' ||
+    !Array.isArray(data.notes) || data.notes.length > MAX_NOTES ||
+    [data.throughEntryId, data.notesThroughEntryId].some(id => id !== undefined && !records.some(record => record.id === id && record.role !== 'summary'))) {
+    throw new MemoryError('invalid_checkpoint', 'The checkpoint version or archived source boundary is invalid.');
+  }
+  const notes = data.notes.map((note: unknown) => validateNote(note, records));
+  if (new Set(notes.map(note => note.key)).size !== notes.length) throw new MemoryError('invalid_checkpoint', 'Duplicate checkpoint keys.');
+  const state: NoteState = { version: data.version as 1 | 2, notes, ...(typeof data.throughEntryId === 'string' ? { throughEntryId: data.throughEntryId } : {}),
+    ...(typeof data.notesThroughEntryId === 'string' ? { notesThroughEntryId: data.notesThroughEntryId } : {}) };
+  if (state.version === 2) compileNotes(state, MAX_NOTES_BYTES);
+  return state;
+}
+
+export function restoreNotes(entries: readonly unknown[], records: HistoryRecord[]): NoteState {
+  let state: NoteState = { version: 1, notes: [] };
+  for (const entry of entries) {
+    if (!objectValue(entry)) continue;
+    if (entry.type === 'custom' && entry.customType === NOTE_EVENT) state = applyUpdates(state, [entry.data], records);
+    if (entry.type === 'custom' && entry.customType === STATE_EVENT) {
+      if (!objectValue(entry.data) || entry.data.version !== 2) throw new MemoryError('invalid_checkpoint', 'The state event needs version 2.');
+      const next = readState(entry.data, records);
+      if (next.throughEntryId !== state.throughEntryId || next.notesThroughEntryId !== state.notesThroughEntryId) throw new MemoryError('invalid_checkpoint', 'A note state event cannot advance coverage.');
+      state = next;
+    }
+    if (entry.type === 'custom' && entry.customType === BACKGROUND_EVENT) {
+      if (!objectValue(entry.data)) throw new MemoryError('invalid_checkpoint', 'Invalid background state.');
+      const next = readState(entry.data.state, records);
+      const previous = state.notesThroughEntryId ?? state.throughEntryId;
+      if (next.version !== 2 || next.throughEntryId !== state.throughEntryId || !next.notesThroughEntryId ||
+        (previous && records.findIndex(record => record.id === next.notesThroughEntryId) <= records.findIndex(record => record.id === previous))) {
+        throw new MemoryError('invalid_checkpoint', 'Background coverage must advance notes only.');
+      }
+      state = next;
+    }
+    if (entry.type === 'compaction' && objectValue(entry.details) && entry.details.piContextMemory !== undefined) {
+      state = readState(entry.details.piContextMemory, records);
+    }
+  }
+  return state;
+}
+
+function renderNotes(state: NoteState): string {
+  return [
+    'Task notes (derived data; verify sources and follow the latest user instructions). Use context_history_search/read for prior details.',
+    ...state.notes.map(note => `[${note.kind}/${note.status}${note.inference ? '/inference' : ''}] ${note.key}: ${note.text} [sources: ${note.sourceIds.join(', ')}]`),
+  ].join('\n');
+}
+
+export function compileNotes(state: NoteState, budget: number): string {
+  const text = renderNotes(state);
+  const bytes = byteCost(text);
+  if (bytes > budget) throw new MemoryError('notes_budget', 'Notes exceed the checkpoint budget; no constraint was silently removed.',
+    { reason: 'note_bytes', actual: bytes, limit: budget });
+  return text;
+}

package/src/relay.ts

@@ -0,0 +1,92 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import type { ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-agent';
+import { extractRecords } from './history.ts';
+import { MemoryError, objectValue } from './errors.ts';
+import { byteCost } from './text.ts';
+import type { NoteState } from './notes.ts';
+
+export const HANDOFF_OUT = 'context-memory-handoff-out';
+export const HANDOFF_IN = 'context-memory-handoff-in';
+export const RELAY_MESSAGE = 'context-memory-relay';
+export interface RelayPacket {
+  version: 1; id: string; createdAt: string;
+  source: { file: string; sessionId: string; leafId: string; digest: string };
+  state: NoteState;
+  workspace: { cwd: string; git: string; files: string[] };
+}
+export interface RelayReceipt { packet: RelayPacket; offerId: string; destinationId: string }
+
+export function branchDigest(entries: readonly SessionEntry[]): string {
+  return createHash('sha256').update(JSON.stringify(entries)).digest('hex');
+}
+
+async function readSession(file: string, signal?: AbortSignal) {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  try {
+    for await (const chunk of createReadStream(file, { signal })) {
+      const buffer = chunk as Buffer;
+      size += buffer.length;
+      if (size > 32 * 1024 * 1024) throw new MemoryError('handoff_source_limit', 'The source session exceeds the 32 MiB read limit.');
+      chunks.push(buffer);
+    }
+    const lines: unknown[] = Buffer.concat(chunks).toString('utf8').split(/\r?\n/).filter(line => line.trim()).map(line => JSON.parse(line));
+    const header = lines.shift();
+    if (!objectValue(header) || header.type !== 'session' || typeof header.id !== 'string') throw new MemoryError('handoff_source_changed', 'Invalid source session header.');
+    const entries = new Map<string, SessionEntry>();
+    for (const value of lines) {
+      if (!objectValue(value) || typeof value.id !== 'string' || entries.has(value.id) ||
+        (value.parentId !== null && typeof value.parentId !== 'string')) throw new MemoryError('handoff_source_changed', 'Invalid source entry graph.');
+      entries.set(value.id, value as unknown as SessionEntry);
+    }
+    return { header, entries, lastId: [...entries.keys()].at(-1) };
+  } catch (error) {
+    if (error instanceof MemoryError || signal?.aborted) throw error;
+    throw new MemoryError('handoff_source_unavailable', 'The saved handoff source could not be read.');
+  }
+}
+
+export async function sourceBranch(source: RelayPacket['source'], signal?: AbortSignal) {
+  const doc = await readSession(source.file, signal);
+  if (doc.header.id !== source.sessionId) throw new MemoryError('handoff_source_changed', 'The source session identity changed.');
+  const branch: SessionEntry[] = [];
+  const seen = new Set<string>();
+  let id: string | null = source.leafId;
+  while (id !== null) {
+    const entry = doc.entries.get(id);
+    if (!entry || seen.has(id)) throw new MemoryError('handoff_source_changed', 'The saved source branch is unavailable.');
+    branch.push(entry); seen.add(id); id = entry.parentId;
+  }
+  branch.reverse();
+  if (branchDigest(branch) !== source.digest) throw new MemoryError('handoff_source_changed', 'The saved source branch was modified.');
+  return { ...doc, branch };
+}
+
+export function receipt(manager: ExtensionContext['sessionManager']): RelayReceipt {
+  const entry = manager.getBranch().findLast(item => item.type === 'custom' && item.customType === HANDOFF_IN);
+  if (entry?.type !== 'custom' || !objectValue(entry.data)) throw new MemoryError('handoff_unavailable', 'This branch has no handoff source.');
+  const value = entry.data;
+  const packet = value.packet;
+  const parent = manager.getHeader()?.parentSession;
+  if (!objectValue(packet) || packet.version !== 1 || typeof packet.id !== 'string' || !objectValue(packet.source) ||
+    typeof packet.source.file !== 'string' || !isAbsolute(packet.source.file) || typeof packet.source.sessionId !== 'string' ||
+    typeof packet.source.leafId !== 'string' || typeof packet.source.digest !== 'string' ||
+    !parent || resolve(parent) !== resolve(packet.source.file) || value.destinationId !== manager.getSessionId() ||
+    typeof value.offerId !== 'string' || byteCost(JSON.stringify(packet)) > 16384) {
+    throw new MemoryError('handoff_binding', 'The relay is not bound to this destination and parent session.');
+  }
+  return value as unknown as RelayReceipt;
+}
+
+export async function inheritedRecords(manager: ExtensionContext['sessionManager'], signal?: AbortSignal, requireLatestOffer = false) {
+  const grant = receipt(manager);
+  const doc = await sourceBranch(grant.packet.source, signal);
+  const offer = doc.entries.get(grant.offerId);
+  if (offer?.type !== 'custom' || offer.customType !== HANDOFF_OUT || JSON.stringify(offer.data) !== JSON.stringify(grant.packet) ||
+    offer.parentId !== grant.packet.source.leafId || (requireLatestOffer && doc.lastId !== offer.id)) {
+    throw new MemoryError('handoff_binding', 'The source offer is missing, changed, or no longer current.');
+  }
+  return extractRecords(doc.branch, signal);
+}

package/src/session-panel.ts

@@ -0,0 +1,74 @@
+import type { ExtensionContext, SessionEntry } from '@earendil-works/pi-coding-agent';
+import type { HistoryRecord } from './history.ts';
+import { memoryStatus, type NoteState } from './notes.ts';
+import { inheritedRecords, receipt } from './relay.ts';
+import { errorCode } from './errors.ts';
+import { readDiagnostics, logPath, logFailure, type LogEvent } from './diagnostics.ts';
+import { AUTO_POLICY, autoState } from './auto-handoff.ts';
+import { GENERATION_TIMEOUT_MS } from './compaction.ts';
+
+export function checkQuality(before: NoteState, after: NoteState, records: HistoryRecord[]): NonNullable<LogEvent['quality']> {
+  const indexed = new Set(records.map(record => record.id));
+  const byKey = new Map(after.notes.map(note => [note.key, note]));
+  const active = before.notes.filter(note => note.status === 'active');
+  return { goals: after.notes.filter(note => note.kind === 'goal' && note.status === 'active').length,
+    constraints: after.notes.filter(note => note.kind === 'constraint' && note.status === 'active').length,
+    openItems: after.notes.filter(note => note.kind === 'open_item' && note.status === 'active').length,
+    pendingApprovalHints: after.notes.filter(note => note.status === 'active' && /审批|待.*确认|等待.*批准|待.*决定|\bapproval\b|\bpermission\b/i.test(note.text)).length,
+    missingActive: active.filter(note => !byKey.has(note.key)).length,
+    changedActive: active.filter(note => byKey.has(note.key) && (byKey.get(note.key)!.status !== note.status || byKey.get(note.key)!.text !== note.text)).length,
+    invalidCitations: after.notes.reduce((sum, note) => sum + note.sourceIds.filter(id => !indexed.has(id)).length, 0) };
+}
+
+export async function sessionReport(ctx: ExtensionContext, entries: SessionEntry[], state: NoteState, records: HistoryRecord[], autoDisabled = false) {
+  const file = ctx.sessionManager.getSessionFile();
+  let parentId: string | null = null;
+  let sources = 'no_handoff';
+  const files = file ? [{ file, sessionId: ctx.sessionManager.getSessionId(), before: Infinity }] : [];
+  if (entries.some(e => e.type === 'custom' && e.customType === 'context-memory-handoff-in')) {
+    try {
+      const grant = receipt(ctx.sessionManager);
+      const parentRecords = await inheritedRecords(ctx.sessionManager);
+      parentId = grant.packet.source.sessionId;
+      sources = grant.packet.state.notes.every(note => note.sourceIds.every(id => parentRecords.some(record => record.id === id))) ? 'verified' : 'invalid_citations';
+      files.push({ file: grant.packet.source.file, sessionId: grant.packet.source.sessionId, before: Date.parse(grant.packet.createdAt) });
+    } catch (error) { sources = errorCode(error); }
+  }
+  const report = await readDiagnostics(files);
+  const automatic = autoState(entries);
+  return { ...report, sessionId: ctx.sessionManager.getSessionId(), parentId, context: ctx.getContextUsage() ?? null,
+    memory: memoryStatus(entries, state),
+    autoHandoff: { enabled: automatic.enabled && !autoDisabled, paused: automatic.paused, lastFailure: automatic.failure ?? null },
+    quality: { ...checkQuality(state, state, records), sources, semanticCompleteness: 'not_verified', duplicateWork: 'heuristic_only' },
+    logging: { path: file ? logPath(file) : null, error: logFailure(file) ?? null, retention: '3 × 2 MiB per session' },
+    policy: { ...AUTO_POLICY, generationTimeoutMs: GENERATION_TIMEOUT_MS, tuning: 'pressure thresholds awaiting real measurements' } };
+}
+
+const stages: Record<string, string> = { preparing: '准备', generating: '生成笔记', quality: '检查交接', saving: '保存', switching: '切换', validating: '核验新会话', continuing: '接手' };
+export function progressText(event: LogEvent): string {
+  const names = { foreground: '模型回复', background: '后台笔记', compaction: '压缩笔记', handoff: '交接' };
+  if (event.event === 'call_start') return `${names[event.kind]}：调用${event.batch ? `第 ${event.batch} 批` : '中'}${event.generationTimeoutMs === undefined ? '' : ` · 总预算 ${event.generationTimeoutMs / 1000}s`}`;
+  if (event.event === 'call_end' || event.event === 'operation_end') return `${names[event.kind]}：${event.outcome === 'ok' ? '完成' : event.outcome === 'cancelled' ? '取消' : '失败'}${event.code ? ` (${event.code})` : ''}${event.budget ? ` · ${event.budget.reason} ${event.budget.actual}/${event.budget.limit}` : ''}`;
+  return `${names[event.kind]}：${stages[event.stage ?? ''] ?? '检查中'}${event.batch ? ` · 第 ${event.batch} 批` : ''}`;
+}
+
+export function panelLines(report: Awaited<ReturnType<typeof sessionReport>>): string[] {
+  const context = report.context;
+  const m = report.metrics;
+  const latestQuality = report.events.findLast(e => e.event === 'quality')?.quality;
+  return [
+    `会话 ${report.sessionId.slice(-8)}${report.parentId ? ` ← ${report.parentId.slice(-8)}` : ''}`,
+      `已保存笔记 ${report.memory.savedNotes} · 最近保存 ${report.memory.lastSavedAt ?? '尚未保存'} · 最近笔记失败 ${report.memory.lastFailure ? report.memory.lastFailure.code + ' @ ' + report.memory.lastFailure.at : '无记录'}（原生压缩不计作笔记保存）`,
+      `笔记覆盖至 ${report.memory.coverage.throughAt ?? '尚无覆盖位置'} · 后续消息 ${report.memory.coverage.pendingMessages ?? '未知'}（用户 ${report.memory.coverage.pendingUserMessages ?? '未知'}；含工具交换，不代表语义遗漏数）`,
+    `上下文 ${context?.tokens ?? '未知'} / ${context?.contextWindow ?? '未知'} · ${context?.percent == null ? '未知' : context.percent.toFixed(1) + '%'}`,
+    `目标 ${report.quality.goals} · 约束 ${report.quality.constraints} · 未完成 ${report.quality.openItems} · 待审批线索 ${report.quality.pendingApprovalHints}`,
+    `来源 ${report.quality.sources} · 语义完整性待人工确认${latestQuality ? ` · 交接前活跃项消失 ${latestQuality.missingActive} / 改写 ${latestQuality.changedActive}` : ''}`,
+    `自动交接 ${!report.autoHandoff.enabled ? '关闭' : report.autoHandoff.paused ? '暂停' : '开启'} · 近期交接 ${m.handoffs} · 失败 ${m.failedOperations}${report.autoHandoff.lastFailure ? ' · ' + report.autoHandoff.lastFailure : ''}`,
+    `近期调用 ${m.calls} · 失败 ${m.failedCalls} (${m.failureRate == null ? '无样本' : (m.failureRate * 100).toFixed(1) + '%'}) · 取消 ${m.cancelledCalls} · 未结束 ${m.unfinishedCalls}`,
+    `返回 tokens ${m.returnedTokens} · 额外 ${m.extraTokens} · 用量未知 ${m.unknownUsageCalls} / 原生 ${m.nativeUnknownUsage} · 提供方计价 ${m.reportedCost.toFixed(6)}`,
+    `调用耗时合计 ${(m.callDurationMs / 1000).toFixed(1)}s（并发时不等于墙钟耗时） · 疑似重复工具 ${m.suspectedRepeatedTools}`,
+    `诊断窗口：主日志缺失 ${report.missingPrimaryFiles} · 不可用文件 ${report.unavailableFiles} · 损坏行 ${report.invalidLines}（缺失数据不能按零计算）`,
+    `日志 ${report.logging.path ?? '未保存会话，无日志文件'}${report.logging.error ? ' · ' + report.logging.error : ''}`,
+    '导出 /ctx-memory session export · 关闭面板 /ctx-memory session close',
+  ];
+}