@cmetech/otto 1.1.1 → 1.2.4

package/src/resources/extensions/coworker-scratchpad/sp-command.ts

@@ -0,0 +1,602 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ExtensionAPI } from '@otto/pi-coding-agent';
+import { ScratchpadBusyError, StalenessBanner } from '@otto/coworker-scratchpad';
+import type { ScratchpadManager, RecoveryNote } from '@otto/coworker-scratchpad';
+import { LocalDataVault } from '@otto/coworker-vault';
+import { validateName, readCellsJsonl, readPersistedLeaf } from './helpers.js';
+import { projectTree, formatTreeText } from '@otto/coworker-scratchpad';
+import { sessionSidecarPath, writeSessionSidecar, deleteSessionSidecar, readSessionSidecar } from './session-sidecar.js';
+import { detectWorkspaceRoot } from './workspace-root.js';
+import { workspaceHash, workspacePointerPath, writeWorkspacePointer, type WorkspacePointer } from './workspace-pointer.js';
+import { showRecoveryNotesBanner, showDivergenceBanner, formatNoteLine } from './attach-banners.js';
+import { formatRelativeAge } from './format-age.js';
+
+export interface SpDeps {
+  getManager: () => ScratchpadManager;
+  getCurrentName: () => string | null;
+  setCurrentName: (name: string | null) => void;
+  rootDir: () => string;
+  getSessionId: () => string;
+  /**
+   * Returns the workspace cwd captured at session_start. Using this instead of
+   * process.cwd() ensures the workspace pointer is anchored to the same root that
+   * session_start used, even if the process chdirs between session_start and a
+   * /sp command.
+   */
+  getWorkspaceCwd: () => string;
+  /**
+   * Phase 2 Task 16: optional vault hook for staleness-banner emission on
+   * attach. When provided, /sp attach reads meta.bindings and asks the vault
+   * for each binding's last-modified timestamp; refs that were modified after
+   * the spawned kernel's start time produce a one-shot banner (per scratchpad,
+   * per (session, ref)). Absent => /sp attach skips the staleness check
+   * silently, which is the right behavior for sessions running without vault.
+   *
+   * Wiring contract: the extension activator (or the vault-extension counterpart)
+   * is responsible for plumbing a closure that returns the live VaultBundle's
+   * `lookupLastModified` reference. Decoupled here so the scratchpad extension
+   * does not have to know about VaultBundle construction order.
+   */
+  getStalenessVault?: () => { lookupLastModified: (ref: string) => Promise<string | null> } | null;
+}
+
+type SpVerb = 'list' | 'new' | 'attach' | 'reset' | 'view' | 'remove' | 'tree' | 'fork' | 'save' | 'detach' | 'clear-history' | 'notes' | 'evict' | 'use' | 'unuse';
+const VERBS: SpVerb[] = ['list', 'new', 'attach', 'reset', 'view', 'remove', 'tree', 'fork', 'save', 'detach', 'clear-history', 'notes', 'evict', 'use', 'unuse'];
+
+/**
+ * Phase 2 Task 16: module-level singleton so banner one-shot state survives
+ * across multiple /sp invocations within one process. Reset on /sp reset for
+ * the affected scratchpad (the kernel respawns ⇒ stale tracking restarts).
+ *
+ * Per-test isolation: tests create distinct scratchpad names (or new tmp
+ * roots) so the per-(scratchpad, session, ref) key set never collides across
+ * tests. No reset-all escape hatch is exposed.
+ */
+const stalenessBanner = new StalenessBanner();
+
+function readBindingsFromMeta(metaPath: string): string[] {
+  if (!existsSync(metaPath)) return [];
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { bindings?: unknown };
+    return Array.isArray(meta.bindings) ? (meta.bindings as string[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function ensureCurrent(deps: SpDeps): string {
+  let current = deps.getCurrentName();
+  if (!current) {
+    current = 'default';
+    deps.setCurrentName(current);
+  }
+  return current;
+}
+
+function listExistingScratchpads(root: string): string[] {
+  if (!existsSync(root)) return [];
+  const names: string[] = [];
+  for (const entry of readdirSync(root)) {
+    const dir = join(root, entry);
+    try {
+      if (statSync(dir).isDirectory() && existsSync(join(dir, 'meta.json'))) names.push(entry);
+    } catch {
+      // entry vanished -> skip
+    }
+  }
+  return names.sort();
+}
+
+function formatCellSummary(rec: { id: number; ok: boolean; code: string; value?: unknown; error?: { message: string } }): string {
+  const head = rec.ok ? `cell ${rec.id} [ok]` : `cell ${rec.id} [err]`;
+  const value = rec.ok ? ` value=${JSON.stringify(rec.value)}` : ` error=${rec.error?.message ?? ''}`;
+  return `${head} ${rec.code.split('\n')[0].slice(0, 80)} ${value}`;
+}
+
+interface UiCtx {
+  hasUI: boolean;
+  ui: {
+    notify: (msg: string, level: 'info' | 'warning' | 'error') => void;
+    confirm: (title: string, msg: string) => Promise<boolean>;
+    input: (title: string, placeholder?: string) => Promise<string | undefined>;
+  };
+}
+
+function persistWorkspacePointer(deps: SpDeps, name: string): void {
+  const wsRoot = detectWorkspaceRoot(deps.getWorkspaceCwd());
+  const wsHash = workspaceHash(wsRoot);
+  const wsPath = workspacePointerPath(deps.rootDir(), wsHash);
+  const wsPayload: WorkspacePointer = {
+    schema_version: 1,
+    workspace_hash: wsHash,
+    workspace_root: wsRoot,
+    last_session_id: deps.getSessionId(),
+    last_current_name: name,
+    last_attached_at: new Date().toISOString(),
+  };
+  writeWorkspacePointer(wsPath, wsPayload);
+}
+
+function joinQuotedArg(parts: string[], startIdx: number): string | null {
+  if (startIdx >= parts.length) return null;
+  const first = parts[startIdx];
+  if (!first) return null;
+  if (!first.startsWith('"')) return first;
+  // Quoted: walk forward until we find a part ending with "
+  if (first.length > 1 && first.endsWith('"')) {
+    return first.slice(1, -1); // single-token quoted reason
+  }
+  const collected: string[] = [first.slice(1)]; // strip opening quote
+  for (let i = startIdx + 1; i < parts.length; i++) {
+    const p = parts[i] ?? '';
+    if (p.endsWith('"')) {
+      collected.push(p.slice(0, -1));
+      return collected.join(' ');
+    }
+    collected.push(p);
+  }
+  return collected.join(' '); // no closing quote — take rest
+}
+
+export function registerSpCommand(pi: ExtensionAPI, deps: SpDeps): void {
+  pi.registerCommand('sp', {
+    description: 'Manage scratchpads: /sp [list|new|attach|reset|view|remove|tree|fork|save|detach|clear-history|notes|evict|use|unuse] [name]',
+    getArgumentCompletions: (prefix: string) => {
+      // Split on whitespace but preserve whether the prefix ends with a space
+      // (trailing space = user typed the verb and hit space, ready for name completion).
+      const trimmed = prefix.trimStart();
+      const parts = trimmed.split(/\s+/);
+      // If trailing space: user has finished typing the verb, want name completions.
+      const trailingSpace = prefix.endsWith(' ');
+      if (parts.length <= 1 && !trailingSpace) {
+        return VERBS.filter((v) => v.startsWith(parts[0] ?? '')).map((v) => ({ value: v, label: v }));
+      }
+      const verb = parts[0];
+      if (verb === 'attach' || verb === 'reset' || verb === 'view' || verb === 'remove') {
+        const namePrefix = trailingSpace && parts.length === 1 ? '' : (parts[1] ?? '');
+        return listExistingScratchpads(deps.rootDir())
+          .filter((n) => n.startsWith(namePrefix))
+          .map((n) => ({ value: `${verb} ${n}`, label: n }));
+      }
+      return [];
+    },
+    handler: async (args: string, ctx: UiCtx) => {
+      const trimmed = args.trim();
+      const parts = trimmed.length === 0 ? [] : trimmed.split(/\s+/);
+      const verb = (parts[0] as SpVerb | undefined) ?? 'list';
+      const name = parts[1];
+
+      try {
+        switch (verb) {
+          case 'list': {
+            const mgr = deps.getManager();
+            const live = mgr.list();
+            const liveByName = new Map(live.map((e) => [e.name, e]));
+            const onDisk = listExistingScratchpads(deps.rootDir());
+            const all = Array.from(new Set([...liveByName.keys(), ...onDisk])).sort();
+            const cur = deps.getCurrentName();
+            if (all.length === 0) {
+              ctx.ui.notify('No scratchpads yet. Use /sp new <name> to create one.', 'info');
+              return;
+            }
+            // Task D: render idle-age column for warm entries. Compute `now` once so
+            // every row shares the same baseline.
+            const now = Date.now();
+            // Pad name column so the age column lines up. Cold entries have no age.
+            const maxNameLen = all.reduce((m, n) => Math.max(m, n.length), 0);
+            const lines = all.map((n) => {
+              const l = liveByName.get(n);
+              const state = l?.live ? '● live' : '○ cold';
+              const marker = n === cur ? ' (current)' : '';
+              let age = '';
+              if (l?.live) {
+                age = l.hasActiveCell ? 'active' : formatRelativeAge(now - l.lastUsedAt);
+              }
+              const namePadded = age ? n.padEnd(maxNameLen) : n;
+              const ageCol = age ? `  ${age}` : '';
+              // Phase 2 Task 16: binding count read from meta.json. Renders as
+              // `uses:N` after the age column so the existing live/cold and
+              // active/idle assertions stay intact. Hidden when 0 to avoid
+              // visual noise for scratchpads that aren't bound.
+              const bindingCount = readBindingsFromMeta(join(deps.rootDir(), n, 'meta.json')).length;
+              const bindingsCol = bindingCount > 0 ? `  uses:${bindingCount}` : '';
+              return `  ${state}  ${namePadded}${ageCol}${bindingsCol}${marker}`;
+            });
+            ctx.ui.notify(['scratchpads:', ...lines].join('\n'), 'info');
+            return;
+          }
+          case 'new': {
+            if (!name) { ctx.ui.notify('Usage: /sp new <name> [--use <engine:name>] ...', 'error'); return; }
+            validateName(name);
+            // Phase 2 Task 16: parse --use flag. Repeatable: `--use jira:prod --use foo:bar`.
+            // Each ref is validated via LocalDataVault.parseRef before persisting; a single
+            // malformed ref aborts the whole create so we don't end up with a half-bound
+            // scratchpad on disk.
+            const bindings: string[] = [];
+            for (let i = 2; i < parts.length; i++) {
+              if (parts[i] === '--use') {
+                const ref = parts[i + 1];
+                if (!ref) { ctx.ui.notify('Usage: /sp new <name> --use <engine:name>', 'error'); return; }
+                try {
+                  LocalDataVault.parseRef(ref);
+                } catch (err) {
+                  ctx.ui.notify((err as Error).message, 'error');
+                  return;
+                }
+                bindings.push(ref);
+                i++; // skip ref token
+              }
+            }
+            await deps.getManager().create(name, bindings.length > 0 ? { bindings } : {});
+            deps.setCurrentName(name);
+            writeSessionSidecar(sessionSidecarPath(deps.rootDir(), deps.getSessionId()), {
+              schema_version: 1,
+              session_id: deps.getSessionId(),
+              current_name: name,
+              attached_at: new Date().toISOString(),
+            });
+            persistWorkspacePointer(deps, name);
+            const suffix = bindings.length > 0 ? ` (bindings: ${bindings.join(', ')})` : '';
+            ctx.ui.notify(`created scratchpad: ${name} (now current)${suffix}`, 'info');
+            return;
+          }
+          case 'use': {
+            const target = name;
+            const ref = parts[2];
+            if (!target || !ref) { ctx.ui.notify('Usage: /sp use <name> <engine:name>', 'error'); return; }
+            validateName(target);
+            try {
+              LocalDataVault.parseRef(ref);
+            } catch (err) {
+              ctx.ui.notify((err as Error).message, 'error');
+              return;
+            }
+            try {
+              const { added } = await deps.getManager().addBinding(target, ref);
+              if (!added) {
+                ctx.ui.notify(`binding already present: ${ref} → ${target}`, 'info');
+              } else {
+                // Hint /sp reset because the live kernel was spawned without this
+                // env block; the binding only takes effect on the next respawn.
+                ctx.ui.notify(`binding added: ${ref} → ${target}. /sp reset to inject into the live kernel.`, 'info');
+              }
+            } catch (err) {
+              ctx.ui.notify((err as Error).message, 'error');
+            }
+            return;
+          }
+          case 'unuse': {
+            const target = name;
+            const ref = parts[2];
+            if (!target || !ref) { ctx.ui.notify('Usage: /sp unuse <name> <engine:name>', 'error'); return; }
+            validateName(target);
+            try {
+              const { removed } = await deps.getManager().removeBinding(target, ref);
+              if (!removed) {
+                ctx.ui.notify(`binding not present: ${ref} → ${target}`, 'info');
+              } else {
+                ctx.ui.notify(`binding removed: ${ref} from ${target}. /sp reset to drop the env block from the live kernel.`, 'info');
+              }
+            } catch (err) {
+              ctx.ui.notify((err as Error).message, 'error');
+            }
+            return;
+          }
+          case 'attach': {
+            if (!name) {
+              ctx.ui.notify('Usage: /sp attach <name> [--force-takeover] [--reason "<text>"]', 'error');
+              return;
+            }
+            validateName(name);
+            // Slash-command path is strict: error on typo instead of silently auto-creating
+            // (the LLM-tool path via cw_scratchpad action=exec stays permissive).
+            const metaPath = join(deps.rootDir(), name, 'meta.json');
+            if (!existsSync(metaPath)) {
+              ctx.ui.notify(
+                `scratchpad not found: ${name}. Use /sp new ${name} to create it.`,
+                'error',
+              );
+              return;
+            }
+            const forceFlag = parts.includes('--force-takeover');
+            const reasonIdx = parts.indexOf('--reason');
+            const reasonArg = reasonIdx >= 0 ? joinQuotedArg(parts, reasonIdx + 1) : null;
+
+            let attached = false;
+            // Phase 2 Task 16: capture the runtime returned by getOrAttach so we
+            // can use its spawnTime as the staleness banner's clock. Defensive
+            // typing because some tests return null from a stubbed manager.
+            let runtime: { spawnTime?: Date } | null = null;
+            try {
+              runtime = (await deps.getManager().getOrAttach(name)) as { spawnTime?: Date } | null;
+              attached = true;
+            } catch (err) {
+              if (!(err instanceof ScratchpadBusyError)) {
+                ctx.ui.notify((err as Error).message, 'error');
+                return;
+              }
+              const holder = err.holder;
+              const proceed = forceFlag || await ctx.ui.confirm(
+                'Force takeover?',
+                `${name}: lock held by pid ${holder.pid} on host ${holder.host} (acquired ${holder.acquired_at}). Take it?`,
+              );
+              if (!proceed) { ctx.ui.notify('cancelled', 'info'); return; }
+
+              let reason: string | null = reasonArg;
+              if (reason === null) {
+                const input = await ctx.ui.input('Takeover reason', 'why are you taking over?');
+                if (input === undefined) { ctx.ui.notify('cancelled', 'info'); return; }
+                reason = input.trim() || '(no reason given)';
+              }
+              try {
+                runtime = (await deps.getManager().getOrAttach(name, { forceTakeover: true, takeoverReason: reason })) as { spawnTime?: Date } | null;
+                attached = true;
+              } catch (retryErr) {
+                ctx.ui.notify((retryErr as Error).message, 'error');
+                return;
+              }
+            }
+            if (!attached) return;
+
+            deps.setCurrentName(name);
+            writeSessionSidecar(sessionSidecarPath(deps.rootDir(), deps.getSessionId()), {
+              schema_version: 1,
+              session_id: deps.getSessionId(),
+              current_name: name,
+              attached_at: new Date().toISOString(),
+            });
+            persistWorkspacePointer(deps, name);
+            ctx.ui.notify(`attached to scratchpad: ${name}`, 'info');
+
+            // §2 + §4 banners (1g2):
+            const { markSeen } = showRecoveryNotesBanner(name, deps.rootDir(), ctx.ui);
+            if (markSeen) {
+              await deps.getManager().markRecoveryNotesSeen(name);
+            }
+            showDivergenceBanner(name, deps.rootDir(), ctx.ui);
+
+            // Phase 2 Task 16: staleness banner. If a vault is wired AND this
+            // scratchpad has bindings, check each ref's last-modified vs the
+            // kernel's spawnTime; emit one-shot warning if any are stale.
+            // Skipped silently when no vault is configured — the scratchpad
+            // extension still works without coworker-vault present.
+            //
+            // spawnTime source: prefer the runtime's stamped Date from
+            // ChildProcessRuntime.start() (Task 13). Fallback to meta.json's
+            // mtime — also rewritten on every attach by writeMeta — when the
+            // runtime is null (stubbed manager paths in tests) or missing the
+            // spawnTime field. Both anchors converge on the same user-visible
+            // semantic: "your creds changed since you started this kernel."
+            if (deps.getStalenessVault) {
+              const vault = deps.getStalenessVault();
+              const bindings = readBindingsFromMeta(join(deps.rootDir(), name, 'meta.json'));
+              if (vault && bindings.length > 0) {
+                try {
+                  const spawnTime = runtime?.spawnTime instanceof Date && runtime.spawnTime.getTime() > 0
+                    ? runtime.spawnTime
+                    : new Date(statSync(join(deps.rootDir(), name, 'meta.json')).mtime);
+                  const banner = await stalenessBanner.check({
+                    scratchpadName: name,
+                    sessionId: deps.getSessionId(),
+                    bindings,
+                    spawnTime,
+                    lookupLastModified: (ref) => vault.lookupLastModified(ref),
+                  });
+                  if (banner) ctx.ui.notify(banner, 'warning');
+                } catch {
+                  // Banner emission must never block /sp attach — swallow errors.
+                }
+              }
+            }
+            return;
+          }
+          case 'reset': {
+            const target = name ?? ensureCurrent(deps);
+            validateName(target);
+            const mgr = deps.getManager();
+            // Phase 2 Task 16: preserve bindings across reset. remove() wipes
+            // the dir, then create() rewrites a fresh meta.json — without this
+            // pre-read the new meta.bindings would be []. Resetting is "respawn
+            // the kernel with current config", so the binding list is part of
+            // config that must survive.
+            const preservedBindings = mgr.readBindings(target);
+            await mgr.remove(target);
+            await mgr.create(target, preservedBindings.length > 0 ? { bindings: preservedBindings } : {});
+            // Phase 2 Task 16: clear the staleness-banner one-shot state for
+            // this scratchpad — the new kernel has a fresh spawnTime, so old
+            // "stale" status is no longer relevant.
+            stalenessBanner.resetForRespawn(target);
+            // currentName preserved if it was the reset target; otherwise unchanged
+            ctx.ui.notify(`reset scratchpad: ${target}`, 'info');
+            return;
+          }
+          case 'view': {
+            const target = name ?? ensureCurrent(deps);
+            validateName(target);
+            const { cells, total_cells } = readCellsJsonl(join(deps.rootDir(), target));
+            if (total_cells === 0) {
+              ctx.ui.notify(`${target}: no cells yet`, 'info');
+              return;
+            }
+            const tail = cells.slice(-10);
+            const lines = tail.map((c) => formatCellSummary(c));
+            ctx.ui.notify([`${target} (${total_cells} cells, last 10):`, ...lines].join('\n'), 'info');
+            return;
+          }
+          case 'remove': {
+            if (!name) { ctx.ui.notify('Usage: /sp remove <name> [--yes]', 'error'); return; }
+            const force = parts.includes('--yes');
+            validateName(name);
+            if (name === deps.getCurrentName() && !force) {
+              const confirmed = await ctx.ui.confirm(
+                'Remove current scratchpad?',
+                `${name} is your current scratchpad. Remove it? This deletes kernel.db, namespace.json, and the cell journal.`,
+              );
+              if (!confirmed) { ctx.ui.notify('cancelled', 'info'); return; }
+            }
+            const wasCurrent = name === deps.getCurrentName();
+            await deps.getManager().remove(name);
+            if (wasCurrent) {
+              deleteSessionSidecar(sessionSidecarPath(deps.rootDir(), deps.getSessionId()));
+              deps.setCurrentName(null);
+            }
+            ctx.ui.notify(`removed scratchpad: ${name}`, 'info');
+            return;
+          }
+          case 'evict': {
+            if (!name) { ctx.ui.notify('Usage: /sp evict <name> [--force]', 'error'); return; }
+            const force = parts.includes('--force');
+            validateName(name);
+            try {
+              const { interrupted } = await deps.getManager().evict(name, { force });
+              const msg = interrupted
+                ? `interrupted active cell and evicted ${name}`
+                : `evicted ${name} (still on disk; /sp attach ${name} to re-warm)`;
+              ctx.ui.notify(msg, 'info');
+            } catch (e) {
+              ctx.ui.notify((e as Error).message, 'error');
+            }
+            return;
+          }
+          case 'tree': {
+            // Usage: /sp tree [<name>] [--to <id>]
+            const flagIdx = parts.indexOf('--to');
+            let target: string;
+            if (flagIdx === -1) {
+              target = name ?? ensureCurrent(deps);
+            } else {
+              target = flagIdx === 1 ? ensureCurrent(deps) : (parts[1] as string);
+              const toId = Number(parts[flagIdx + 1]);
+              if (!Number.isInteger(toId) || toId <= 0) {
+                ctx.ui.notify('Usage: /sp tree [<name>] --to <id>', 'error');
+                return;
+              }
+              validateName(target);
+              await deps.getManager().setLeaf(target, toId);
+              ctx.ui.notify(`set leaf of ${target} to cell ${toId}`, 'info');
+              return;
+            }
+            validateName(target);
+            const { cells } = readCellsJsonl(join(deps.rootDir(), target));
+            if (cells.length === 0) {
+              ctx.ui.notify(`${target}: no cells yet`, 'info');
+              return;
+            }
+            const tree = projectTree(cells);
+            const leaf = readPersistedLeaf(join(deps.rootDir(), target, 'meta.json'));
+            ctx.ui.notify(`${target} cell tree:\n${formatTreeText(tree, leaf)}`, 'info');
+            return;
+          }
+          case 'fork': {
+            // Usage: /sp fork <src> <dst>
+            if (parts.length < 3) { ctx.ui.notify('Usage: /sp fork <src> <dst>', 'error'); return; }
+            const src = parts[1]!;
+            const dst = parts[2]!;
+            validateName(src);
+            validateName(dst);
+            await deps.getManager().fork(src, dst);
+            ctx.ui.notify(`forked ${src} → ${dst}`, 'info');
+            return;
+          }
+          case 'save': {
+            const target = name ?? deps.getCurrentName();
+            if (!target) { ctx.ui.notify('Usage: /sp save [<name>] — no current scratchpad', 'error'); return; }
+            validateName(target);
+            await deps.getManager().save(target);
+            ctx.ui.notify(`saved ${target}`, 'info');
+            return;
+          }
+          case 'detach': {
+            const target = deps.getCurrentName();
+            if (!target) { ctx.ui.notify('not attached to any scratchpad', 'error'); return; }
+            await deps.getManager().detach(target, deps.getSessionId());
+            deleteSessionSidecar(sessionSidecarPath(deps.rootDir(), deps.getSessionId()));
+            deps.setCurrentName(null);
+            ctx.ui.notify(`detached from ${target}`, 'info');
+            return;
+          }
+          case 'clear-history': {
+            const target = name ?? deps.getCurrentName();
+            if (!target) { ctx.ui.notify('Usage: /sp clear-history [<name>] — no current scratchpad', 'error'); return; }
+            validateName(target);
+            const confirmed = await ctx.ui.confirm(
+              'Clear cell history?',
+              `Clear cell history for ${target}? kernel.db + namespace.json are preserved.`,
+            );
+            if (!confirmed) { ctx.ui.notify('cancelled', 'info'); return; }
+            await deps.getManager().clearHistory(target);
+            ctx.ui.notify(`cleared cell history for ${target}`, 'info');
+            return;
+          }
+          case 'notes': {
+            const target = name ?? deps.getCurrentName();
+            if (!target) {
+              ctx.ui.notify('Usage: /sp notes [<name>] (no current scratchpad)', 'error');
+              return;
+            }
+            validateName(target);
+            const metaPath = join(deps.rootDir(), target, 'meta.json');
+            if (!existsSync(metaPath)) {
+              ctx.ui.notify(`scratchpad not found: ${target}`, 'error');
+              return;
+            }
+            let meta: Record<string, unknown>;
+            try {
+              meta = JSON.parse(readFileSync(metaPath, 'utf8')) as Record<string, unknown>;
+            } catch {
+              ctx.ui.notify(`${target}: meta.json unreadable`, 'error');
+              return;
+            }
+            type RecoveryNoteEntry = RecoveryNote & { at: string };
+            const notes = Array.isArray(meta.recovery_notes) ? (meta.recovery_notes as RecoveryNoteEntry[]) : [];
+            if (notes.length === 0) {
+              ctx.ui.notify(`no recovery notes for ${target}`, 'info');
+              return;
+            }
+            const lines = notes.map(formatNoteLine);
+            ctx.ui.notify(`${target} recovery notes (${notes.length}):\n${lines.join('\n')}`, 'info');
+            // Deliberately does NOT update recovery_notes_seen_at — re-view path is read-only.
+            return;
+          }
+          default: {
+            ctx.ui.notify(`unknown verb: ${verb}. Try one of: ${VERBS.join(', ')}`, 'error');
+          }
+        }
+      } catch (err) {
+        ctx.ui.notify((err as Error).message, 'error');
+      }
+    },
+  });
+}
+
+/**
+ * Phase 3 Task 18: exposes a session→scratchpad-name lookup for cross-pillar
+ * consumers (memory's MemoryRecorder uses this to derive the default Room).
+ *
+ * Reads the per-session sidecar written by /sp new and /sp attach. Returns
+ * null when no scratchpad is currently attached for `sessionId`, when
+ * `sessionId` is empty/undefined, or on any IO/parse error — callers must
+ * tolerate null (the caller-side fallback is "use workspace as Room").
+ *
+ * Decoupled from `SpDeps` so consumers outside the slash-command lifecycle
+ * (e.g. recorders constructed at extension activation) can call it without
+ * holding a reference to the scratchpad manager.
+ *
+ * Note on the sidecar reader's actual signature: `readSessionSidecar(path)`
+ * takes a fully-resolved path, not `{scratchpadsRoot, sessionId}`. We compose
+ * with `sessionSidecarPath(rootDir, sessionId)` to bridge.
+ */
+export function createCurrentScratchpadProvider(opts: {
+  scratchpadsRoot: string;
+}): (sessionId: string) => string | null {
+  return (sessionId: string) => {
+    if (!sessionId) return null;
+    try {
+      const sidecar = readSessionSidecar(sessionSidecarPath(opts.scratchpadsRoot, sessionId));
+      return sidecar?.current_name ?? null;
+    } catch {
+      return null;
+    }
+  };
+}

package/src/resources/extensions/coworker-scratchpad/workspace-pointer.test.ts

@@ -0,0 +1,74 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  workspaceHash,
+  workspacePointerPath,
+  readWorkspacePointer,
+  writeWorkspacePointer,
+  isPointerFresh,
+  WORKSPACE_POINTER_STALE_MS,
+  type WorkspacePointer,
+} from './workspace-pointer.js';
+
+describe('workspace-pointer', () => {
+  it('writes and round-trip reads a pointer', () => {
+    const root = mkdtempSync(join(tmpdir(), 'wsp-'));
+    try {
+      const hash = workspaceHash('/home/me/project');
+      const path = workspacePointerPath(root, hash);
+      const payload: WorkspacePointer = {
+        schema_version: 1,
+        workspace_hash: hash,
+        workspace_root: '/home/me/project',
+        last_session_id: 'sess-A',
+        last_current_name: 't04-tree',
+        last_attached_at: '2026-06-01T12:00:00.000Z',
+      };
+      writeWorkspacePointer(path, payload);
+      assert.deepEqual(readWorkspacePointer(path), payload);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('isPointerFresh respects the 7-day boundary', () => {
+    const base: WorkspacePointer = {
+      schema_version: 1,
+      workspace_hash: 'h',
+      workspace_root: '/x',
+      last_session_id: 's',
+      last_current_name: 'n',
+      last_attached_at: '2026-06-01T00:00:00.000Z',
+    };
+    const at0 = Date.parse(base.last_attached_at);
+    assert.equal(isPointerFresh(base, at0 + WORKSPACE_POINTER_STALE_MS - 1), true);
+    assert.equal(isPointerFresh(base, at0 + WORKSPACE_POINTER_STALE_MS), false);
+    assert.equal(isPointerFresh(base, at0 + WORKSPACE_POINTER_STALE_MS + 1000), false);
+  });
+
+  it('returns null for corrupt JSON or missing schema_version', () => {
+    const root = mkdtempSync(join(tmpdir(), 'wsp-bad-'));
+    try {
+      const path = workspacePointerPath(root, 'abc');
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, 'not valid json at all');
+      assert.equal(readWorkspacePointer(path), null);
+      writeFileSync(path, JSON.stringify({ schema_version: 99, foo: 'bar' }));
+      assert.equal(readWorkspacePointer(path), null);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('workspaceHash is deterministic 16-char hex and varies by input', () => {
+    const a = workspaceHash('/home/me/projA');
+    const b = workspaceHash('/home/me/projB');
+    assert.equal(a.length, 16);
+    assert.match(a, /^[0-9a-f]{16}$/);
+    assert.notEqual(a, b);
+    assert.equal(workspaceHash('/home/me/projA'), a);
+  });
+});