@cspeach/cli 1.1.30 → 1.1.31

package/dist/session/backfill.js

@@ -0,0 +1,342 @@
+/**
+ * 2026-10-08 (sessions/folders, Task 12) — one-off tagging of old sessions.
+ *
+ * Sessions saved before folders existed have no `project_dir`, so they only
+ * show under "Show all folders". This pass tags each one ONCE with the folder
+ * its own content points at, and changes nothing else in the file:
+ *
+ *   1. paths it wrote with file_write / file_edit (absolute only): the folder
+ *      above the first `.cspeach` segment, else the file's folder; the most
+ *      frequent folder wins;
+ *   2. its plan in flight: the folder above the plan's `.cspeach`;
+ *   3. `<attached file="NAME">` in its user messages: the ONE folder, among
+ *      those found by 1–2 across all sessions, whose `.cspeach` holds NAME;
+ *   4. else left alone.
+ *
+ * Best effort: never throws to the caller, never rewrites a file that does
+ * not parse, never touches reader-* files or sessions that already have a
+ * folder. A file is rewritten with the store's own serialisation (tmp +
+ * rename) and keeps its file time, which the session lists sort by.
+ * Files saved in the last 5 minutes (likely open in a running CLI) and files
+ * that change between read and rename are not written now: they are kept in
+ * a deferred list and retried on later starts.
+ * Each start spends at most a small time budget. When it runs out, the place
+ * reached is saved and the next start goes on from there; the done-marker is
+ * written only once every session file has been looked at.
+ */
+import fs from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { sessionsDir } from '../config/paths.js';
+import { readSoloProjectId, teamProjectId } from '../projects/project-folder.js';
+import { normDir } from './project-match.js';
+export const BACKFILL_MARKER = '.backfilled-v1';
+export const BACKFILL_PROGRESS = '.backfill-progress';
+/** Start-up never waits on this for longer than this. */
+const BUDGET_MS = 2000;
+const WRITE_TOOLS = new Set(['file_write', 'file_edit', 'write_file', 'edit_file']);
+/** The folder above the first `.cspeach` segment of `p`, or null. */
+export function folderAboveCspeach(p) {
+    const parts = p.split(/[\\/]/);
+    const i = parts.findIndex((s) => s.toLowerCase() === '.cspeach');
+    if (i < 1)
+        return null;
+    let head = parts.slice(0, i).join(path.sep);
+    if (head === '' || /^[A-Za-z]:$/.test(head))
+        head += path.sep;
+    return path.resolve(head);
+}
+/** Step 1: the most frequent folder among absolute written paths. */
+function folderFromWrites(toolCalls) {
+    if (!Array.isArray(toolCalls))
+        return null;
+    const counts = new Map();
+    for (const c of toolCalls) {
+        const tool = c?.tool ?? c?.name;
+        const p = c?.args?.path;
+        if (!WRITE_TOOLS.has(tool) || typeof p !== 'string' || !path.isAbsolute(p))
+            continue;
+        const dir = folderAboveCspeach(p) ?? path.dirname(path.resolve(p));
+        const key = normDir(dir);
+        const hit = counts.get(key);
+        if (hit)
+            hit.n++;
+        else
+            counts.set(key, { dir, n: 1 });
+    }
+    let best = null;
+    for (const v of counts.values())
+        if (!best || v.n > best.n)
+            best = v;
+    return best?.dir ?? null;
+}
+/** Step 2: the folder above the plan in flight's `.cspeach`. */
+function folderFromPlan(plan) {
+    const p = plan?.path;
+    return typeof p === 'string' && path.isAbsolute(p) ? folderAboveCspeach(p) : null;
+}
+/** Attached file names in the user messages. */
+function attachedNames(messages) {
+    if (!Array.isArray(messages))
+        return [];
+    const names = new Set();
+    const scan = (t) => {
+        if (typeof t !== 'string')
+            return;
+        for (const m of t.matchAll(/<attached file="([^"]+)">/g))
+            names.add(m[1]);
+    };
+    for (const msg of messages) {
+        if (msg?.role !== 'user')
+            continue;
+        if (typeof msg.content === 'string')
+            scan(msg.content);
+        else if (Array.isArray(msg.content))
+            for (const b of msg.content)
+                if (b?.type === 'text')
+                    scan(b.text);
+    }
+    return [...names];
+}
+/** Does `<dir>/.cspeach` hold a file called `name` (a few levels deep)? */
+function cspeachHolds(dir, name) {
+    const walk = (d, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const e of entries)
+            if (e.isFile() && e.name.toLowerCase() === name.toLowerCase())
+                return true;
+        if (depth <= 0)
+            return false;
+        for (const e of entries)
+            if (e.isDirectory() && walk(path.join(d, e.name), depth - 1))
+                return true;
+        return false;
+    };
+    return walk(path.join(dir, '.cspeach'), 3);
+}
+async function readProgress(file) {
+    try {
+        const p = JSON.parse(await fs.readFile(file, 'utf-8'));
+        if (p && Array.isArray(p.known) && Array.isArray(p.pending)) {
+            return {
+                cursor: typeof p.cursor === 'string' ? p.cursor : null, scanned: p.scanned === true,
+                known: p.known, pending: p.pending, deferred: Array.isArray(p.deferred) ? p.deferred : [],
+            };
+        }
+    }
+    catch { /* none yet, or unreadable: start over */ }
+    return { cursor: null, scanned: false, known: [], pending: [], deferred: [] };
+}
+async function writeProgress(file, p) {
+    const tmp = `${file}.bf-${process.pid}.tmp`;
+    try {
+        await fs.writeFile(tmp, JSON.stringify(p), 'utf-8');
+        await fs.rename(tmp, file);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw err;
+    }
+}
+/** A session file that may be tagged: parses, is an object, not a reader. */
+async function readSession(file) {
+    let st;
+    let state;
+    try {
+        // Stat BEFORE reading: a save in between shows up as a changed stamp
+        // at rename time, so the tag is skipped rather than written over it.
+        st = await fs.stat(file);
+        state = JSON.parse(await fs.readFile(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (!state || typeof state !== 'object' || Array.isArray(state))
+        return null;
+    if (typeof state.id === 'string' && state.id.startsWith('reader-'))
+        return null;
+    return { state, mtimeMs: st.mtimeMs, size: st.size, atime: st.atime, mtime: st.mtime };
+}
+/** Saved in the last few minutes: likely open in a running CLI, leave it. */
+const RECENT_MS = 5 * 60 * 1000;
+const isRecent = (s) => Date.now() - s.mtimeMs < RECENT_MS;
+/**
+ * Tag one session file. Returns false (nothing written) when the file
+ * changed since it was read — a running CLI saved it; its newer content wins.
+ * The tmp name is our own, never the store's `<file>.tmp`.
+ */
+async function writeTagged(file, s, dir, beforeRename) {
+    const state = { ...s.state, project_dir: dir };
+    // A team folder matches by its team id (final fix wave, item 2); never the
+    // home-folder rule, which would read another folder's id.
+    const id = teamProjectId(dir) ?? readSoloProjectId(dir);
+    if (id)
+        state.project_id = id;
+    const tmp = `${file}.bf-${process.pid}.tmp`;
+    try {
+        await fs.writeFile(tmp, JSON.stringify(state, null, 2), 'utf-8');
+        if (beforeRename)
+            await beforeRename(file);
+        const now = await fs.stat(file);
+        if (now.mtimeMs !== s.mtimeMs || now.size !== s.size) {
+            await fs.rm(tmp, { force: true });
+            return false;
+        }
+        await fs.rename(tmp, file);
+    }
+    catch {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        return false;
+    }
+    await fs.utimes(file, s.atime, s.mtime).catch(() => { });
+    return true;
+}
+/** One pass per process: `--resume` then the REPL start must not pay twice. */
+let ranThisProcess = false;
+/** Tests only: allow another pass in the same process. */
+export function resetBackfillRunFlag() { ranThisProcess = false; }
+export async function backfillSessionFolders(opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    const result = { tagged: 0, unknown: 0 };
+    if (ranThisProcess)
+        return result;
+    ranThisProcess = true;
+    const dir = sessionsDir();
+    const marker = path.join(dir, BACKFILL_MARKER);
+    const progressFile = path.join(dir, BACKFILL_PROGRESS);
+    try {
+        if (!existsSync(dir) || existsSync(marker))
+            return result;
+        const start = now().getTime();
+        // Every start finishes at least one whole file before the budget counts.
+        let processed = 0;
+        const overBudget = () => processed > 0 && now().getTime() - start > BUDGET_MS;
+        const prog = await readProgress(progressFile);
+        const known = new Map(prog.known.map((f) => [normDir(f), f]));
+        const pending = [...prog.pending];
+        const carried = [...prog.deferred]; // deferred by an earlier start: retry now
+        const deferred = []; // deferred in this start: retry next start
+        const save = () => writeProgress(progressFile, {
+            cursor: prog.cursor, scanned: prog.scanned, known: [...known.values()], pending,
+            deferred: [...carried, ...deferred],
+        });
+        /**
+         * Steps 1–2 for one file. A file that is live (saved recently) or that
+         * changed under us is deferred, never dropped; one with no 1–2 evidence
+         * waits in `pending` for step 3.
+         */
+        const evaluate = async (f) => {
+            const file = path.join(dir, f);
+            const s = await readSession(file);
+            if (!s)
+                return;
+            const found = folderFromWrites(s.state.toolCalls) ?? folderFromPlan(s.state.plan_in_flight);
+            if (found)
+                known.set(normDir(found), found);
+            if (s.state.project_dir != null)
+                return;
+            if (isRecent(s)) {
+                deferred.push(f);
+                return;
+            }
+            if (!found) {
+                pending.push(f);
+                return;
+            }
+            if (await writeTagged(file, s, found, opts.beforeRename))
+                result.tagged++;
+            else
+                deferred.push(f);
+        };
+        if (!prog.scanned) {
+            const files = (await fs.readdir(dir))
+                .filter((f) => f.endsWith('.json') && !f.startsWith('.') && !f.includes('-reader-'))
+                .sort().reverse()
+                .filter((f) => prog.cursor === null || f < prog.cursor);
+            for (const f of files) {
+                await evaluate(f);
+                prog.cursor = f;
+                processed++;
+                if (overBudget()) {
+                    await save();
+                    return result;
+                }
+            }
+            prog.scanned = true;
+        }
+        while (carried.length > 0) {
+            await evaluate(carried[0]);
+            carried.shift();
+            processed++;
+            if (overBudget()) {
+                await save();
+                return result;
+            }
+        }
+        const holds = new Map(); // `${folderKey}\0${name}` → found
+        const holdsCached = (key, folder, name) => {
+            const k = `${key}\0${name.toLowerCase()}`;
+            let v = holds.get(k);
+            if (v === undefined) {
+                v = cspeachHolds(folder, name);
+                holds.set(k, v);
+            }
+            return v;
+        };
+        while (pending.length > 0) {
+            const f = pending[0];
+            const file = path.join(dir, f);
+            const s = await readSession(file);
+            if (s && s.state.project_dir == null) {
+                if (isRecent(s)) {
+                    deferred.push(f);
+                }
+                else {
+                    const hits = new Set();
+                    let outOfTime = false;
+                    for (const name of attachedNames(s.state.messages)) {
+                        for (const [key, folder] of known)
+                            if (holdsCached(key, folder, name))
+                                hits.add(key);
+                        if (overBudget()) {
+                            outOfTime = true;
+                            break;
+                        }
+                    }
+                    // Out of time mid-match: keep this file first in line for next start.
+                    if (outOfTime) {
+                        await save();
+                        return result;
+                    }
+                    if (hits.size !== 1)
+                        result.unknown++;
+                    else if (await writeTagged(file, s, known.get([...hits][0]), opts.beforeRename))
+                        result.tagged++;
+                    else
+                        deferred.push(f);
+                }
+            }
+            pending.shift();
+            processed++;
+            if (overBudget()) {
+                await save();
+                return result;
+            }
+        }
+        // Done only when every file was looked at and nothing waits.
+        if (deferred.length > 0) {
+            await save();
+            return result;
+        }
+        await fs.writeFile(marker, `${now().toISOString()}\n`, 'utf-8');
+        await fs.rm(progressFile, { force: true });
+    }
+    catch { /* best effort — never blocks start-up */ }
+    return result;
+}

package/dist/session/project-match.js

@@ -0,0 +1,63 @@
+/**
+ * 2026-10-08 (sessions/folders, Task 6) — the ONE rule that says whether a
+ * saved session belongs to the folder the CLI runs in.
+ *
+ * - Team folder: match by project id only (each person syncs the shared
+ *   folder to a different local path).
+ * - Otherwise: the same project id (both set) matches, so a renamed folder
+ *   keeps its sessions; else the normalised folder paths must be equal.
+ *   A sub-folder is a different folder.
+ */
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { resolveProjectFolderSync } from '../projects/project-folder.js';
+/** Real path when it exists, else resolved; no trailing separator; lower-case on win32. */
+export function normDir(p) {
+    let r;
+    try {
+        r = realpathSync.native(p);
+    }
+    catch {
+        r = path.resolve(p);
+    }
+    r = r.replace(/[\\/]+$/, '') || r;
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+}
+export function currentFolderKey(cwd) {
+    const pf = resolveProjectFolderSync(cwd);
+    return { dir: pf.projectDir, id: pf.projectId, kind: pf.kind };
+}
+/** `hereDirNorm`: normDir(here.dir) computed once by a caller that checks many sessions. */
+export function sessionMatchesFolder(s, here, hereDirNorm) {
+    if (here.kind === 'team')
+        return here.id !== null && s.projectId === here.id;
+    if (s.projectId && here.id && s.projectId === here.id)
+        return true;
+    return s.projectDir !== null && normDir(s.projectDir) === (hereDirNorm ?? normDir(here.dir));
+}
+/** The folder and id a new session is tagged with at creation. */
+export function folderTag(cwd) {
+    const k = currentFolderKey(cwd);
+    return { dir: k.dir, id: k.id };
+}
+/**
+ * The first save hands over the folder's project id. Fill it in only when
+ * the session belongs to this folder:
+ * - an old untagged session (no folder) takes this folder and its id;
+ * - a session from this same folder without an id takes the id;
+ * - a session from another folder, or one that already has an id, is left as is.
+ * Returns true when the session changed (the caller saves it).
+ */
+export function tagSessionOnSave(session, cwd, id) {
+    if (session.project_dir == null) {
+        session.project_dir = path.resolve(cwd);
+        session.project_id = id;
+        return true;
+    }
+    if (session.project_id)
+        return false;
+    if (normDir(session.project_dir) !== normDir(cwd))
+        return false;
+    session.project_id = id;
+    return true;
+}

package/dist/session/resume.js

@@ -1,6 +1,9 @@
 import { select } from '../repl/themed-prompts.js';
 import chalk from 'chalk';
-import { listSessions, loadSession, RESUME_PICKER_LIMIT } from './store.js';
+import path from 'node:path';
+import { listSessions, loadSession, latestSessionHere, RESUME_PICKER_LIMIT } from './store.js';
+import { currentFolderKey, sessionMatchesFolder } from './project-match.js';
+import { backfillSessionFolders } from './backfill.js';
 import { formatTimeAgo } from './time-ago.js';
 import { runRepl } from '../repl.js';
 import { formatFailure, formatAttention } from '../renderer/notice-shape.js';
@@ -30,29 +33,61 @@ export function pickerSessions(sessions) {
         return b.lastTurnAt.localeCompare(a.lastTurnAt);
     });
 }
+/** The picker's last choice in this folder's list: open the all-folders list. */
+const ALL = '__all__';
+/**
+ * 2026-10-08 — `cspeach --continue`: resume the latest session of this
+ * folder. Searches every session file, not only the startup window.
+ */
+export async function runContinue(opts = {}) {
+    const here = currentFolderKey(opts.cwd ?? process.cwd());
+    await backfillSessionFolders().catch(() => { });
+    const s = await latestSessionHere(here, { scanAll: true });
+    if (!s) {
+        console.log('No session in this folder yet. cspeach --resume lists all folders.');
+        return 0;
+    }
+    return runResume(s.id, opts);
+}
+/** One resume picker; resolves to the chosen value (a session id or ALL). */
+async function pick(sessions, withFolder, showAll) {
+    return select({
+        message: `Pick a session to resume:
+${formatSessionHeader(withFolder)}`,
+        choices: [
+            ...sessions.map((s) => ({
+                value: s.id,
+                name: formatSessionRow(s, undefined, withFolder),
+                // Round 6 item 4a — the answered line shows the id, not the whole row.
+                short: s.id,
+                description: s.interrupted
+                    ? interruptedPickerLine(s.interruptedReason)
+                    : `${s.userTurnCount} prior turn(s) — pick up from where you left off`,
+            })),
+            ...(showAll ? [{ value: ALL, name: 'Show all folders', short: 'all folders' }] : []),
+        ],
+    });
+}
 export async function runResume(id, opts = {}) {
     let targetId = id;
+    const here = currentFolderKey(opts.cwd ?? process.cwd());
     if (!targetId) {
-        const sessions = pickerSessions(await listSessions(RESUME_PICKER_LIMIT, { skipEmpty: true }));
-        if (sessions.length === 0) {
-            console.log('No recent sessions.');
-            return 0;
-        }
-        const sorted = sessions;
+        await backfillSessionFolders().catch(() => { });
+        // 2026-10-08 — this folder's sessions first, with "Show all folders" last.
+        const local = pickerSessions(await listSessions(RESUME_PICKER_LIMIT, { skipEmpty: true, here, scanAll: true }));
         try {
-            targetId = await select({
-                message: `Pick a session to resume:
-${formatSessionHeader()}`,
-                choices: sorted.map((s) => ({
-                    value: s.id,
-                    name: formatSessionRow(s),
-                    // Round 6 item 4a — the answered line shows the id, not the whole row.
-                    short: s.id,
-                    description: s.interrupted
-                        ? interruptedPickerLine(s.interruptedReason)
-                        : `${s.userTurnCount} prior turn(s) — pick up from where you left off`,
-                })),
-            });
+            let choice = ALL;
+            if (local.length > 0)
+                choice = await pick(local, false, true);
+            if (choice === ALL) {
+                const sessions = pickerSessions(await listSessions(RESUME_PICKER_LIMIT, { skipEmpty: true }));
+                if (sessions.length === 0) {
+                    console.log('No recent sessions.');
+                    return 0;
+                }
+                choice = await pick(sessions, true, false);
+            }
+            targetId = choice;
         }
         catch (err) {
             // Ctrl+C in the picker: exit quietly, like Claude Code (fix round 3).
@@ -69,6 +104,10 @@ ${formatSessionHeader()}`,
         console.error('\n' + formatFailure({ what: 'Could not load the session', detail: [err.message], next: 'cspeach --resume  (pick from the list)' }));
         return 1;
     }
+    // 2026-10-08 — resume by id works from any folder; say where it began.
+    if (session.project_dir && !sessionMatchesFolder({ projectDir: session.project_dir, projectId: session.project_id ?? null }, here)) {
+        console.log(chalk.dim(`This session was started in ${session.project_dir}. New files save here, in ${here.dir}.`));
+    }
     const unfinished = session.toolCalls.filter((c) => !c.completed);
     // Round 6 review I3 — moving a session with unfinished SAP changes to
     // another system would leave those changes unreconcilable: refuse.
@@ -126,21 +165,23 @@ ${formatSessionHeader()}`,
     return runRepl({ resumedSession: session, sapAlias: opts.sapAlias, noSap: opts.noSap });
 }
 // Column widths shared by the rows and the header so the labels line up.
-const W = { id: 8, time: 10, sap: 8, skill: 22, turns: 5 };
+const W = { id: 8, time: 10, sap: 8, skill: 22, turns: 5, folder: 16 };
 /**
  * One picker row. Round 4 item 10 — the preview is cut to the terminal
  * width (a long one wrapped onto a second line at 100 columns and broke the
  * table): room = columns − the picker's 2-cell cursor gutter − the fixed
  * columns − 1 spare cell.
  */
-export function formatSessionRow(s, columns = process.stdout.columns ?? 80) {
+export function formatSessionRow(s, columns = process.stdout.columns ?? 80, withFolder = false) {
     const flag = s.interrupted ? paint('warn', getGlyphs().attention) + ' ' : '  ';
     const idCol = chalk.cyan(s.id.padEnd(W.id));
     const timeCol = chalk.gray(formatTimeAgo(s.lastTurnAt).padEnd(W.time));
     const sapCol = chalk.gray((s.sapSystem ?? '-').padEnd(W.sap));
     const skillCol = chalk.gray(`/${s.skill ?? '-'}`.padEnd(W.skill));
     const turns = chalk.gray(`${s.userTurnCount}t`.padStart(W.turns));
-    const prefix = `${flag}${idCol} ${timeCol} ${sapCol} ${skillCol} ${turns}  `;
+    // 2026-10-08 — the all-folders picker adds a FOLDER column.
+    const folderCol = withFolder ? ' ' + chalk.gray(folderLabel(s.projectDir).padEnd(W.folder)) : '';
+    const prefix = `${flag}${idCol} ${timeCol}${folderCol} ${sapCol} ${skillCol} ${turns}  `;
     // Measured (string-width ignores colour codes), not summed: a value wider
     // than its column pads nothing.
     const room = Math.max(8, columns - 2 - stringWidth(prefix) - 1);
@@ -152,14 +193,21 @@ export function formatSessionRow(s, columns = process.stdout.columns ?? 80) {
  * picker draws a 2-char cursor gutter before each choice but not before the
  * message, so the header adds it: gutter + flag = 4 leading spaces.
  */
-export function formatSessionHeader() {
+export function formatSessionHeader(withFolder = false) {
     return chalk.dim('    ' +
         [
             'ID'.padEnd(W.id),
             'LAST USED'.padEnd(W.time),
+            ...(withFolder ? ['FOLDER'.padEnd(W.folder)] : []),
             'SYSTEM'.padEnd(W.sap),
             'SKILL'.padEnd(W.skill),
             'TURNS'.padStart(W.turns),
         ].join(' ') +
         '  LAST PROMPT');
 }
+/** The folder column: the folder's name, cut to the column; "folder unknown" for older sessions. */
+function folderLabel(projectDir) {
+    if (!projectDir)
+        return 'folder unknown';
+    return truncateToWidth(path.basename(projectDir) || projectDir, W.folder);
+}

package/dist/session/schema.js

@@ -1,9 +1,11 @@
 export const SCHEMA_VERSION = 1;
-export function newSession(id, sapSystem, skill, model) {
+export function newSession(id, sapSystem, skill, model, project) {
     const now = new Date().toISOString();
     return {
         schema_version: SCHEMA_VERSION,
         id,
+        project_dir: project?.dir ?? null,
+        project_id: project?.id ?? null,
         started_at: now,
         last_turn_at: now,
         sap_system: sapSystem,