@cmetech/otto 1.1.0 → 1.2.4

package/dist/resources/extensions/coworker-scratchpad/sp-command.js

@@ -0,0 +1,597 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ScratchpadBusyError, StalenessBanner } 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 } from './workspace-pointer.js';
+import { showRecoveryNotesBanner, showDivergenceBanner, formatNoteLine } from './attach-banners.js';
+import { formatRelativeAge } from './format-age.js';
+const VERBS = ['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) {
+    if (!existsSync(metaPath))
+        return [];
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+        return Array.isArray(meta.bindings) ? meta.bindings : [];
+    }
+    catch {
+        return [];
+    }
+}
+function ensureCurrent(deps) {
+    let current = deps.getCurrentName();
+    if (!current) {
+        current = 'default';
+        deps.setCurrentName(current);
+    }
+    return current;
+}
+function listExistingScratchpads(root) {
+    if (!existsSync(root))
+        return [];
+    const names = [];
+    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) {
+    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}`;
+}
+function persistWorkspacePointer(deps, name) {
+    const wsRoot = detectWorkspaceRoot(deps.getWorkspaceCwd());
+    const wsHash = workspaceHash(wsRoot);
+    const wsPath = workspacePointerPath(deps.rootDir(), wsHash);
+    const wsPayload = {
+        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, startIdx) {
+    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 = [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, deps) {
+    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) => {
+            // 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, ctx) => {
+            const trimmed = args.trim();
+            const parts = trimmed.length === 0 ? [] : trimmed.split(/\s+/);
+            const verb = parts[0] ?? '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 = [];
+                        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.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.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.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.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 = null;
+                        try {
+                            runtime = (await deps.getManager().getOrAttach(name));
+                            attached = true;
+                        }
+                        catch (err) {
+                            if (!(err instanceof ScratchpadBusyError)) {
+                                ctx.ui.notify(err.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 = 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 }));
+                                attached = true;
+                            }
+                            catch (retryErr) {
+                                ctx.ui.notify(retryErr.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.message, 'error');
+                        }
+                        return;
+                    }
+                    case 'tree': {
+                        // Usage: /sp tree [<name>] [--to <id>]
+                        const flagIdx = parts.indexOf('--to');
+                        let target;
+                        if (flagIdx === -1) {
+                            target = name ?? ensureCurrent(deps);
+                        }
+                        else {
+                            target = flagIdx === 1 ? ensureCurrent(deps) : parts[1];
+                            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;
+                        try {
+                            meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+                        }
+                        catch {
+                            ctx.ui.notify(`${target}: meta.json unreadable`, 'error');
+                            return;
+                        }
+                        const notes = Array.isArray(meta.recovery_notes) ? meta.recovery_notes : [];
+                        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.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) {
+    return (sessionId) => {
+        if (!sessionId)
+            return null;
+        try {
+            const sidecar = readSessionSidecar(sessionSidecarPath(opts.scratchpadsRoot, sessionId));
+            return sidecar?.current_name ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/resources/extensions/coworker-scratchpad/workspace-pointer.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const WORKSPACE_POINTER_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+export function workspaceHash(workspaceRoot) {
+    return createHash('sha256').update(workspaceRoot).digest('hex').slice(0, 16);
+}
+export function workspacePointerPath(rootDir, hash) {
+    return join(rootDir, '_workspaces', `${hash}.json`);
+}
+export function readWorkspacePointer(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed.schema_version === 1 &&
+            typeof parsed.workspace_hash === 'string' &&
+            typeof parsed.workspace_root === 'string' &&
+            typeof parsed.last_session_id === 'string' &&
+            typeof parsed.last_current_name === 'string' &&
+            typeof parsed.last_attached_at === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeWorkspacePointer(path, payload) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(payload, null, 2));
+    renameSync(tmp, path);
+}
+export function isPointerFresh(pointer, now) {
+    const attachedAt = Date.parse(pointer.last_attached_at);
+    if (Number.isNaN(attachedAt))
+        return false;
+    return (now - attachedAt) < WORKSPACE_POINTER_STALE_MS;
+}

package/dist/resources/extensions/coworker-scratchpad/workspace-root.js

@@ -0,0 +1,17 @@
+import { execSync } from 'node:child_process';
+export function detectWorkspaceRoot(cwd) {
+    try {
+        const out = execSync('git rev-parse --show-toplevel', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 500,
+        }).trim();
+        if (out)
+            return out;
+    }
+    catch {
+        /* not a git repo, git not installed, or timeout — fall through */
+    }
+    return cwd;
+}