@cmetech/otto 1.1.1 → 1.2.5

package/src/resources/extensions/coworker-memory/memory-command.ts

@@ -0,0 +1,131 @@
+// src/resources/extensions/coworker-memory/memory-command.ts
+import type { MemoryBundle } from './memory-singleton.js';
+import { runMemorize } from './memorize-tool.js';
+import { runRecall } from './recall-tool.js';
+
+export interface MemoryCommandResult {
+  message: string;
+}
+
+export async function runMemoryCommand(bundle: MemoryBundle, argv: string[]): Promise<MemoryCommandResult> {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case 'note': {
+      const text = rest.join(' ').trim();
+      if (!text) throw new Error('Usage: /memory note <text>');
+      await runMemorize(bundle, { text, kind: 'lesson', scope: 'workspace' });
+      return { message: `lesson stored in workspace.` };
+    }
+    case 'status': {
+      const status = await bundle.backend.status();
+      return {
+        message: [
+          `scope_mode: ${bundle.scopeMode}`,
+          `workspace_wing: ${bundle.workspaceWing}`,
+          `drawer_count: ${status.drawer_count}`,
+          `layer_b_db_path: ${status.layer_b_db_path}`,
+          `schema_version: ${status.schema_version}`,
+        ].join('\n'),
+      };
+    }
+    case 'clear': {
+      let wing: string | undefined;
+      let confirm = false;
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--wing' && rest[i+1]) { wing = rest[++i]; }
+        else if (rest[i] === '--confirm') { confirm = true; }
+      }
+      if (!confirm) throw new Error('Usage: /memory clear --wing <wing> --confirm');
+      const out = await bundle.backend.clear({ wing, confirm: true });
+      return { message: `deleted: ${out.deleted}` };
+    }
+    case 'wing':
+    case 'room': {
+      // Session overrides — caller manages state; this is a placeholder return acknowledging.
+      const target = rest.join(' ').trim();
+      if (!target) throw new Error(`Usage: /memory ${sub} <name>`);
+      return { message: `${sub} override: ${target}` };
+    }
+    case 'seed': {
+      // Caller wires this to applyPersonaSeed via session-hooks; here we just acknowledge the request.
+      return { message: 're-seed will run on next session_start; flip workspace.json.memory_seed_applied=false and reattach.' };
+    }
+    case 'show': {
+      let target: 'all' | 'profile' | 'rule' | 'lesson' = 'all';
+      let scopeOverride: 'workspace' | 'global' | null = null;
+      for (let i = 0; i < rest.length; i++) {
+        const t = rest[i];
+        if (t === '--scope' && rest[i + 1]) {
+          const s = rest[++i];
+          if (s !== 'workspace' && s !== 'global') throw new Error(`Usage: /memory show [profile|rules|lessons] [--scope workspace|global]`);
+          scopeOverride = s;
+        } else if (t === 'profile') { target = 'profile'; }
+        else if (t === 'rule' || t === 'rules') { target = 'rule'; }
+        else if (t === 'lesson' || t === 'lessons') { target = 'lesson'; }
+        else if (t === 'all') { target = 'all'; }
+        else { throw new Error(`Usage: /memory show [profile|rules|lessons] [--scope workspace|global]`); }
+      }
+      const kinds: Array<'profile' | 'rule' | 'lesson'> =
+        target === 'all' ? ['profile', 'rule', 'lesson'] : [target];
+      // Determine scopes: --scope override wins; otherwise derive from bundle.scopeMode.
+      const scopes: Array<{ name: 'workspace' | 'global'; store: typeof bundle.workspaceLayerA }> = [];
+      if (scopeOverride === 'workspace') {
+        scopes.push({ name: 'workspace', store: bundle.workspaceLayerA });
+      } else if (scopeOverride === 'global') {
+        scopes.push({ name: 'global', store: bundle.globalLayerA });
+      } else if (bundle.scopeMode === 'global') {
+        scopes.push({ name: 'global', store: bundle.globalLayerA });
+      } else if (bundle.scopeMode === 'per-project') {
+        scopes.push({ name: 'workspace', store: bundle.workspaceLayerA });
+      } else {
+        // per-project-tagged: workspace first, then global
+        scopes.push({ name: 'workspace', store: bundle.workspaceLayerA });
+        scopes.push({ name: 'global', store: bundle.globalLayerA });
+      }
+      const TITLE_FOR = { profile: 'Profile', rule: 'Rules', lesson: 'Lessons' } as const;
+      const sections: string[] = [];
+      for (const k of kinds) {
+        for (const scope of scopes) {
+          const body = await scope.store.read(k);
+          sections.push(`## ${TITLE_FOR[k]} (${scope.name})\n${body || '(none)'}`);
+        }
+      }
+      return { message: sections.join('\n\n') };
+    }
+    case 'recall': {
+      // First flag/positional split: gather positional tokens for the query;
+      // recognize --kind, --room, --wing, --limit, --days_back.
+      const flags: { kind?: string; room?: string; wing?: string; limit?: number; days_back?: number } = {};
+      const queryTokens: string[] = [];
+      for (let i = 0; i < rest.length; i++) {
+        const t = rest[i];
+        if (t === '--kind' && rest[i + 1]) { flags.kind = rest[++i]; }
+        else if (t === '--room' && rest[i + 1]) { flags.room = rest[++i]; }
+        else if (t === '--wing' && rest[i + 1]) { flags.wing = rest[++i]; }
+        else if (t === '--limit' && rest[i + 1]) {
+          const n = parseInt(rest[++i]!, 10);
+          if (Number.isFinite(n)) flags.limit = n;
+        } else if (t === '--days_back' && rest[i + 1]) {
+          const n = parseInt(rest[++i]!, 10);
+          if (Number.isFinite(n)) flags.days_back = n;
+        } else {
+          queryTokens.push(t!);
+        }
+      }
+      const query = queryTokens.join(' ').trim();
+      if (!query) throw new Error('Usage: /memory recall <query> [--kind <k>] [--room <r>] [--wing <w>] [--limit N] [--days_back N]');
+      // Defer to the same runRecall the LLM tool uses for parity.
+      const out = await runRecall(bundle, {
+        query,
+        kind: flags.kind as never,           // runRecall accepts string; backend validates
+        room: flags.room,
+        wing: flags.wing,
+        max_results: flags.limit,
+        days_back: flags.days_back,
+      });
+      return { message: out.markdown };
+    }
+    default:
+      throw new Error(`Unknown /memory subcommand: ${sub}. Try: note, status, clear, wing, room, seed, show, recall.`);
+  }
+}

package/src/resources/extensions/coworker-memory/memory-singleton.test.ts

@@ -0,0 +1,41 @@
+// src/resources/extensions/coworker-memory/memory-singleton.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createMemoryBundle } from './memory-singleton.js';
+
+describe('memory singleton bundle', () => {
+  it('constructs scope-aware bundle with all stores', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'mem-home-'));
+    const ws = mkdtempSync(join(tmpdir(), 'mem-ws-'));
+    mkdirSync(ws, { recursive: true });
+    const bundle = await createMemoryBundle({
+      globalDir: home, workspaceDir: ws,
+      scopeMode: 'per-project-tagged',
+      currentScratchpadName: () => null,
+    });
+    assert.ok(bundle.globalLayerA);
+    assert.ok(bundle.workspaceLayerA);
+    assert.ok(bundle.backend);
+    assert.ok(bundle.recorder);
+    assert.equal(bundle.scopeMode, 'per-project-tagged');
+    assert.match(bundle.workspaceWing, /-[0-9a-f]{6}$/);
+    assert.equal(bundle.writeWing, bundle.workspaceWing);
+    assert.deepEqual(bundle.readWings, [bundle.workspaceWing, 'global']);
+    await bundle.dispose();
+  });
+  it('global mode bundle uses wing global', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'mem-home-g-'));
+    const ws = mkdtempSync(join(tmpdir(), 'mem-ws-g-'));
+    const bundle = await createMemoryBundle({
+      globalDir: home, workspaceDir: ws,
+      scopeMode: 'global',
+      currentScratchpadName: () => null,
+    });
+    assert.equal(bundle.writeWing, 'global');
+    assert.deepEqual(bundle.readWings, ['global']);
+    await bundle.dispose();
+  });
+});

package/src/resources/extensions/coworker-memory/memory-singleton.ts

@@ -0,0 +1,89 @@
+// src/resources/extensions/coworker-memory/memory-singleton.ts
+//
+// Factory that constructs the layered memory collaborators (LayerAStore x2,
+// LocalSqliteBackend, MemoryRecorder) plus shared audit + secret scanner for
+// given roots. Mirrors the coworker-vault singleton pattern. Pure beyond what
+// the underlying constructors already perform (dir creation, db open, etc.).
+import { join } from 'node:path';
+import { AuditLog, SecretScanner } from '@otto/coworker-utils';
+import {
+  LayerAStore,
+  LocalSqliteBackend,
+  MemoryRecorder,
+  resolveScope,
+  resolveWorkspaceId,
+  type ScopeMode,
+  type Wing,
+  type CurrentScratchpadProvider,
+  type WorkspaceIdRecord,
+} from '@otto/coworker-memory';
+
+export interface MemoryBundleOptions {
+  globalDir: string;
+  workspaceDir: string;
+  scopeMode: ScopeMode;
+  currentScratchpadName: CurrentScratchpadProvider;
+}
+
+export interface MemoryBundle {
+  globalLayerA: LayerAStore;
+  workspaceLayerA: LayerAStore;
+  backend: LocalSqliteBackend;
+  recorder: MemoryRecorder;
+  audit: AuditLog;
+  scanner: SecretScanner;
+  workspaceWing: Wing;
+  writeWing: Wing;
+  readWings: Wing[];
+  scopeMode: ScopeMode;
+  workspaceRecord: WorkspaceIdRecord;
+  workspaceDir: string;
+  dispose(): Promise<void>;
+}
+
+export async function createMemoryBundle(opts: MemoryBundleOptions): Promise<MemoryBundle> {
+  const audit = new AuditLog({ path: join(opts.globalDir, 'audit.jsonl') });
+  const scanner = new SecretScanner();
+  const wsRecord = await resolveWorkspaceId(opts.workspaceDir);
+  const scope = resolveScope({ mode: opts.scopeMode, workspaceId: wsRecord.id });
+  const globalLayerA = new LayerAStore({
+    scopeDir: join(opts.globalDir, 'memory'),
+    scope: 'global',
+    audit,
+    scanner,
+  });
+  const workspaceLayerA = new LayerAStore({
+    scopeDir: join(opts.workspaceDir, '.otto', 'memory'),
+    scope: 'workspace',
+    audit,
+    scanner,
+  });
+  const backend = new LocalSqliteBackend({
+    dbPath: join(opts.workspaceDir, '.otto', 'memory', 'layer-b.db'),
+  });
+  await backend.open();
+  const recorder = new MemoryRecorder({
+    backend,
+    scanner,
+    audit,
+    writeWing: scope.writeWing,
+    currentScratchpadName: opts.currentScratchpadName,
+  });
+  return {
+    globalLayerA,
+    workspaceLayerA,
+    backend,
+    recorder,
+    audit,
+    scanner,
+    workspaceWing: wsRecord.id,
+    writeWing: scope.writeWing,
+    readWings: scope.readWings,
+    scopeMode: opts.scopeMode,
+    workspaceRecord: wsRecord,
+    workspaceDir: opts.workspaceDir,
+    async dispose() {
+      await backend.close();
+    },
+  };
+}

package/src/resources/extensions/coworker-memory/recall-tool.test.ts

@@ -0,0 +1,50 @@
+// src/resources/extensions/coworker-memory/recall-tool.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createMemoryBundle } from './memory-singleton.js';
+import { runRecall } from './recall-tool.js';
+
+async function setup() {
+  const home = mkdtempSync(join(tmpdir(), 'rt-home-'));
+  const ws = mkdtempSync(join(tmpdir(), 'rt-ws-'));
+  mkdirSync(ws, { recursive: true });
+  return createMemoryBundle({
+    globalDir: home, workspaceDir: ws,
+    scopeMode: 'per-project-tagged', currentScratchpadName: () => null,
+  });
+}
+
+describe('recall tool', () => {
+  it('returns results with markdown rendering', async () => {
+    const b = await setup();
+    await b.recorder.recordTurn({ sessionId: 's', userText: 'customer paste about load balancer', turnId: 't1' });
+    const r = await runRecall(b, { query: 'load balancer' });
+    assert.equal(r.results.length, 1);
+    assert.match(r.markdown, /Memory recall \(1 matches\)/);
+    assert.match(r.markdown, /drawer:\/\//);
+    await b.dispose();
+  });
+  it('honors max_results clamp 1..64', async () => {
+    const b = await setup();
+    for (let i = 0; i < 100; i++) {
+      await b.recorder.recordTurn({ sessionId: 's', userText: `apple ${i}`, turnId: `t${i}` });
+    }
+    const big = await runRecall(b, { query: 'apple', max_results: 200 });
+    assert.ok(big.results.length <= 64);
+    const small = await runRecall(b, { query: 'apple', max_results: 0 });
+    assert.equal(small.results.length, 1);
+    await b.dispose();
+  });
+  it('filters by kind', async () => {
+    const b = await setup();
+    await b.recorder.recordTurn({ sessionId: 's', userText: 'short alpha', turnId: 't1' });
+    await b.recorder.recordPaste({ sessionId: 's', content: 'long alpha paste', turnId: 't2' });
+    const onlyPaste = await runRecall(b, { query: 'alpha', kind: 'paste' });
+    assert.equal(onlyPaste.results.length, 1);
+    assert.equal(onlyPaste.results[0]!.drawer.kind, 'paste');
+    await b.dispose();
+  });
+});

package/src/resources/extensions/coworker-memory/recall-tool.ts

@@ -0,0 +1,35 @@
+// src/resources/extensions/coworker-memory/recall-tool.ts
+import type { MemoryBundle } from './memory-singleton.js';
+import { formatRecall, type RecallQuery, type RecallResult } from '@otto/coworker-memory';
+
+export interface RecallToolArgs {
+  query: string;
+  kind?: RecallQuery['kind'];
+  wing?: string;
+  room?: string;
+  days_back?: number;
+  max_results?: number;
+}
+
+export interface RecallToolOutput {
+  results: RecallResult[];
+  markdown: string;
+}
+
+export async function runRecall(bundle: MemoryBundle, args: RecallToolArgs): Promise<RecallToolOutput> {
+  const wings = args.wing ? [args.wing, ...bundle.readWings.filter(w => w !== args.wing)] : bundle.readWings;
+  const limit = args.max_results === undefined ? 8 : Math.min(Math.max(args.max_results, 1), 64);
+  const results = await bundle.backend.recall({
+    query: args.query, wing: wings, room: args.room, kind: args.kind,
+    days_back: args.days_back, max_results: limit,
+  });
+  bundle.audit.append({
+    _schema: 1, ts: new Date().toISOString(), producer: 'memory', action: 'recall',
+    detail: {
+      wing_filter: wings, room_filter: args.room ?? null,
+      kind_filter: args.kind ?? null, days_back: args.days_back ?? null,
+      result_count: results.length,
+    },
+  });
+  return { results, markdown: formatRecall(results) };
+}

package/src/resources/extensions/coworker-memory/session-hooks.test.ts

@@ -0,0 +1,77 @@
+// src/resources/extensions/coworker-memory/session-hooks.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createMemoryBundle } from './memory-singleton.js';
+import { onSessionStart, onSessionShutdown } from './session-hooks.js';
+
+async function setup() {
+  const home = mkdtempSync(join(tmpdir(), 'sh-home-'));
+  const ws = mkdtempSync(join(tmpdir(), 'sh-ws-'));
+  mkdirSync(ws, { recursive: true });
+  return {
+    home,
+    ws,
+    bundle: await createMemoryBundle({
+      globalDir: home,
+      workspaceDir: ws,
+      scopeMode: 'per-project-tagged',
+      currentScratchpadName: () => null,
+    }),
+  };
+}
+
+describe('session hooks', () => {
+  it('onSessionStart returns Layer A context block', async () => {
+    const c = await setup();
+    await c.bundle.workspaceLayerA.append({
+      kind: 'lesson',
+      text: 'do not deploy on friday',
+      source: 'user',
+      ts: '2026-06-02T00:00:00Z',
+    });
+    const out = await onSessionStart(c.bundle, { tokenLimit: 3000 });
+    assert.match(out.contextBlock, /Memory \(Layer A\)/);
+    assert.match(out.contextBlock, /do not deploy on friday/);
+    await c.bundle.dispose();
+  });
+  it('onSessionStart applies persona seed when pending', async () => {
+    const c = await setup();
+    const personaDir = mkdtempSync(join(tmpdir(), 'persona-'));
+    const seedDir = join(personaDir, 'memory-seed');
+    mkdirSync(seedDir, { recursive: true });
+    writeFileSync(join(seedDir, 'rules.md'), 'Persona rule baseline');
+    const out = await onSessionStart(c.bundle, {
+      tokenLimit: 3000,
+      persona: { id: 'noc-ops', personaDir },
+    });
+    assert.deepEqual(out.seed.copied, ['rules.md']);
+    assert.equal(c.bundle.workspaceRecord.memory_seed_applied, true);
+    assert.equal(c.bundle.workspaceRecord.memory_seed_persona, 'noc-ops');
+    await c.bundle.dispose();
+  });
+  it('onSessionStart does not re-apply seed once flag is true', async () => {
+    const c = await setup();
+    const personaDir = mkdtempSync(join(tmpdir(), 'persona2-'));
+    const seedDir = join(personaDir, 'memory-seed');
+    mkdirSync(seedDir, { recursive: true });
+    writeFileSync(join(seedDir, 'rules.md'), 'Persona rule v1');
+    await onSessionStart(c.bundle, { tokenLimit: 3000, persona: { id: 'noc-ops', personaDir } });
+    // Now change the seed file but the flag is set.
+    writeFileSync(join(seedDir, 'rules.md'), 'Persona rule v2');
+    const second = await onSessionStart(c.bundle, {
+      tokenLimit: 3000,
+      persona: { id: 'noc-ops', personaDir },
+    });
+    assert.deepEqual(second.seed.copied, []);
+    await c.bundle.dispose();
+  });
+  it('onSessionShutdown closes backend without throwing', async () => {
+    const c = await setup();
+    await onSessionShutdown(c.bundle);
+    // Bundle is now disposed; second close should be safe.
+    await c.bundle.dispose();
+  });
+});

package/src/resources/extensions/coworker-memory/session-hooks.ts

@@ -0,0 +1,61 @@
+// src/resources/extensions/coworker-memory/session-hooks.ts
+//
+// Session lifecycle seams for the coworker-memory extension.
+// - onSessionStart: applies a one-shot persona seed (if pending) and returns
+//   the Layer A context block ready for system-prompt injection.
+// - onSessionShutdown: closes the backend (Layer B). Safe to double-call —
+//   LocalSqliteBackend.close() nulls its db handle so a second close is a no-op.
+import { buildLayerAContext, applyPersonaSeed, writeWorkspaceId } from '@otto/coworker-memory';
+import type { MemoryBundle } from './memory-singleton.js';
+
+export interface SessionStartOptions {
+  tokenLimit?: number;
+  persona?: { id: string; personaDir: string };
+}
+
+export interface SessionStartResult {
+  contextBlock: string;
+  seed: { copied: string[]; blocked: string[] };
+}
+
+export async function onSessionStart(
+  bundle: MemoryBundle,
+  opts: SessionStartOptions = {},
+): Promise<SessionStartResult> {
+  let seed = { copied: [] as string[], blocked: [] as string[] };
+  if (opts.persona && !bundle.workspaceRecord.memory_seed_applied) {
+    seed = await applyPersonaSeed({
+      personaId: opts.persona.id,
+      personaDir: opts.persona.personaDir,
+      store: bundle.workspaceLayerA,
+    });
+    if (seed.copied.length > 0 || seed.blocked.length > 0) {
+      bundle.workspaceRecord.memory_seed_applied = true;
+      bundle.workspaceRecord.memory_seed_persona = opts.persona.id;
+      await writeWorkspaceId(bundle.workspaceDir, bundle.workspaceRecord);
+      bundle.audit.append({
+        _schema: 1,
+        ts: new Date().toISOString(),
+        producer: 'memory',
+        action: 'seed-applied',
+        detail: {
+          persona_id: opts.persona.id,
+          files_copied: seed.copied,
+          files_blocked: seed.blocked,
+        },
+      });
+    }
+  }
+  const contextBlock = await buildLayerAContext({
+    mode: bundle.scopeMode,
+    globalStore: bundle.globalLayerA,
+    workspaceStore: bundle.workspaceLayerA,
+    tokenLimit: opts.tokenLimit ?? 3000,
+  });
+  return { contextBlock, seed };
+}
+
+export async function onSessionShutdown(bundle: MemoryBundle): Promise<void> {
+  // WAL checkpoint happens on backend close; this is the seam.
+  await bundle.dispose();
+}

package/src/resources/extensions/coworker-scratchpad/attach-banners.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { showRecoveryNotesBanner, showDivergenceBanner } from './attach-banners.js';
+
+interface FakeUi {
+  notifications: Array<[string, string]>;
+  notify: (msg: string, level: 'info' | 'warning' | 'error') => void;
+}
+
+function makeUi(): FakeUi {
+  const notifications: FakeUi['notifications'] = [];
+  return { notifications, notify: (m, l) => notifications.push([l, m]) };
+}
+
+function writeMeta(root: string, name: string, meta: Record<string, unknown>): void {
+  mkdirSync(join(root, name), { recursive: true });
+  writeFileSync(join(root, name, 'meta.json'), JSON.stringify(meta));
+}
+
+let root: string;
+
+describe('attach-banners', () => {
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'banners-'));
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it('showRecoveryNotesBanner emits warning when there are unseen notes; returns markSeen=true', () => {
+    writeMeta(root, 'p1', {
+      recovery_notes: [
+        { kind: 'snapshot-failed', message: 'boom', at: '2026-05-31T10:00:00.000Z' },
+        { kind: 'cells-since-snapshot', n: 3, at: '2026-05-31T11:00:00.000Z' },
+      ],
+      recovery_notes_seen_at: null,
+    });
+    const ui = makeUi();
+    const { unseenCount, markSeen } = showRecoveryNotesBanner('p1', root, ui);
+    assert.equal(unseenCount, 2);
+    assert.equal(markSeen, true);
+    assert.equal(ui.notifications.length, 1);
+    assert.equal(ui.notifications[0][0], 'warning');
+    assert.match(ui.notifications[0][1], /2 unread recovery notes/);
+    assert.match(ui.notifications[0][1], /snapshot-failed: boom/);
+    assert.match(ui.notifications[0][1], /3 cells since last snapshot/);
+  });
+
+  it('showRecoveryNotesBanner does not notify when all notes are seen; returns markSeen=false', () => {
+    writeMeta(root, 'p1', {
+      recovery_notes: [
+        { kind: 'snapshot-failed', message: 'boom', at: '2026-05-31T10:00:00.000Z' },
+      ],
+      recovery_notes_seen_at: '2026-05-31T11:00:00.000Z',
+    });
+    const ui = makeUi();
+    const { unseenCount, markSeen } = showRecoveryNotesBanner('p1', root, ui);
+    assert.equal(unseenCount, 0);
+    assert.equal(markSeen, false);
+    assert.equal(ui.notifications.length, 0);
+  });
+
+  it('showRecoveryNotesBanner truncates to 5 with "+ N more" footer', () => {
+    const notes = Array.from({ length: 8 }, (_, i) => ({
+      kind: 'snapshot-failed' as const,
+      message: `err-${i}`,
+      at: `2026-05-31T1${i}:00:00.000Z`,
+    }));
+    writeMeta(root, 'p1', { recovery_notes: notes, recovery_notes_seen_at: null });
+    const ui = makeUi();
+    const { unseenCount } = showRecoveryNotesBanner('p1', root, ui);
+    assert.equal(unseenCount, 8);
+    assert.match(ui.notifications[0][1], /\+ 3 more \(run \/sp notes\)/);
+    // Should include err-0..err-4 (first 5) but not err-5..err-7
+    assert.match(ui.notifications[0][1], /err-0/);
+    assert.match(ui.notifications[0][1], /err-4/);
+    assert.equal(ui.notifications[0][1].includes('err-5'), false);
+  });
+
+  it('showRecoveryNotesBanner tolerates missing or corrupt meta silently', () => {
+    const ui = makeUi();
+    // Missing scratchpad dir
+    const r1 = showRecoveryNotesBanner('absent', root, ui);
+    assert.deepEqual(r1, { unseenCount: 0, markSeen: false });
+    // Corrupt meta.json
+    mkdirSync(join(root, 'p2'), { recursive: true });
+    writeFileSync(join(root, 'p2', 'meta.json'), '{not json');
+    const r2 = showRecoveryNotesBanner('p2', root, ui);
+    assert.deepEqual(r2, { unseenCount: 0, markSeen: false });
+    assert.equal(ui.notifications.length, 0);
+  });
+
+  it('showDivergenceBanner emits info when leaf !== kernel; both set', () => {
+    writeMeta(root, 'p1', { cell_leaf_id: 5, kernel_at_cell_id: 8 });
+    const ui = makeUi();
+    const { diverged } = showDivergenceBanner('p1', root, ui);
+    assert.equal(diverged, true);
+    assert.equal(ui.notifications.length, 1);
+    assert.equal(ui.notifications[0][0], 'info');
+    assert.match(ui.notifications[0][1], /kernel state is at cell #8/);
+    assert.match(ui.notifications[0][1], /view is at cell #5/);
+    assert.match(ui.notifications[0][1], /\/sp tree to inspect/);
+  });
+
+  it('showDivergenceBanner does not notify when leaf===kernel, either is null, or meta missing', () => {
+    const ui = makeUi();
+    // Equal
+    writeMeta(root, 'p1', { cell_leaf_id: 5, kernel_at_cell_id: 5 });
+    assert.deepEqual(showDivergenceBanner('p1', root, ui), { diverged: false });
+    // Leaf null
+    writeMeta(root, 'p2', { cell_leaf_id: null, kernel_at_cell_id: 5 });
+    assert.deepEqual(showDivergenceBanner('p2', root, ui), { diverged: false });
+    // Kernel null
+    writeMeta(root, 'p3', { cell_leaf_id: 5, kernel_at_cell_id: null });
+    assert.deepEqual(showDivergenceBanner('p3', root, ui), { diverged: false });
+    // Meta missing
+    assert.deepEqual(showDivergenceBanner('absent', root, ui), { diverged: false });
+    assert.equal(ui.notifications.length, 0);
+  });
+});

package/src/resources/extensions/coworker-scratchpad/attach-banners.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { RecoveryNote } from '@otto/coworker-scratchpad';
+
+type RecoveryNoteEntry = RecoveryNote & { at: string };
+
+interface UiNotify {
+  notify: (msg: string, level: 'info' | 'warning' | 'error') => void;
+}
+
+export function showRecoveryNotesBanner(
+  name: string,
+  rootDir: string,
+  ui: UiNotify,
+): { unseenCount: number; markSeen: boolean } {
+  const metaPath = join(rootDir, name, 'meta.json');
+  if (!existsSync(metaPath)) return { unseenCount: 0, markSeen: false };
+  let meta: Record<string, unknown>;
+  try {
+    meta = JSON.parse(readFileSync(metaPath, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return { unseenCount: 0, markSeen: false };
+  }
+  const notes = Array.isArray(meta.recovery_notes) ? (meta.recovery_notes as RecoveryNoteEntry[]) : [];
+  if (notes.length === 0) return { unseenCount: 0, markSeen: false };
+  const seenAt = typeof meta.recovery_notes_seen_at === 'string' ? meta.recovery_notes_seen_at : null;
+  const unseen = notes.filter((n) => seenAt === null || n.at > seenAt);
+  if (unseen.length === 0) return { unseenCount: 0, markSeen: false };
+  const head = unseen.slice(0, 5).map(formatNoteLine).join('\n');
+  const tail = unseen.length > 5 ? `\n+ ${unseen.length - 5} more (run /sp notes)` : '';
+  ui.notify(`⚠ ${unseen.length} unread recovery notes:\n${head}${tail}`, 'warning');
+  return { unseenCount: unseen.length, markSeen: true };
+}
+
+export function showDivergenceBanner(
+  name: string,
+  rootDir: string,
+  ui: UiNotify,
+): { diverged: boolean } {
+  const metaPath = join(rootDir, name, 'meta.json');
+  if (!existsSync(metaPath)) return { diverged: false };
+  let meta: Record<string, unknown>;
+  try {
+    meta = JSON.parse(readFileSync(metaPath, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return { diverged: false };
+  }
+  const leaf = typeof meta.cell_leaf_id === 'number' ? meta.cell_leaf_id : null;
+  const kernel = typeof meta.kernel_at_cell_id === 'number' ? meta.kernel_at_cell_id : null;
+  if (leaf === null || kernel === null || leaf === kernel) return { diverged: false };
+  ui.notify(
+    `ℹ kernel state is at cell #${kernel}; view is at cell #${leaf} (run /sp tree to inspect)`,
+    'info',
+  );
+  return { diverged: true };
+}
+
+export function formatNoteLine(n: RecoveryNoteEntry): string {
+  const ts = n.at.slice(0, 19);
+  switch (n.kind) {
+    case 'snapshot-failed':       return `  • [${ts}] snapshot-failed: ${n.message}`;
+    case 'cells-since-snapshot':  return `  • [${ts}] ${n.n} cells since last snapshot`;
+    case 'namespace-corrupt':     return `  • [${ts}] namespace-corrupt: ${n.message}`;
+    case 'namespace-absent':      return `  • [${ts}] namespace-absent`;
+    default:                      return `  • [${ts}] ${(n as { kind: string }).kind}`;
+  }
+}