@cspeach/cli 1.1.14 → 1.1.16

package/dist/register/store.js

@@ -0,0 +1,227 @@
+/**
+ * Project Register on disk (spec §3, §3a).
+ *
+ * Two places, both chosen by a person, never by the model:
+ *   - the TEAM PROJECT FOLDER the lead creates: cspeach-team.json, baseline/,
+ *     lanes.json, rulings/. Collected records sit under writers/.
+ *   - this laptop's OUTBOX: where this machine's records are written. It mirrors
+ *     the project-folder layout (writers/<id>/records/…) so that handing records
+ *     in is a plain folder copy. By default it lives under ~/.cspeach; a developer
+ *     may point it inside their own OneDrive-synced folder instead.
+ *
+ * CSPeach writes only to paths on this list. It never writes to a network
+ * location on its own initiative.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { cspeachRoot } from '../config/paths.js';
+export const TEAM_FILE = 'cspeach-team.json';
+export const BASELINE_FILE = path.join('baseline', 'objects.json');
+export const LANES_FILE = 'lanes.json';
+export class RegisterError extends Error {
+}
+export const defaultRand = (bytes) => randomBytes(bytes).toString('hex');
+const stateFile = () => path.join(cspeachRoot(), 'register.json');
+export function loadState() {
+    try {
+        const s = JSON.parse(stripBom(fs.readFileSync(stateFile(), 'utf8')));
+        if (s && typeof s === 'object' && s.projects)
+            return { active: s.active ?? null, projects: s.projects };
+    }
+    catch { /* first use, or unreadable: start empty */ }
+    return { active: null, projects: {} };
+}
+export function saveState(state) {
+    fs.mkdirSync(cspeachRoot(), { recursive: true });
+    fs.writeFileSync(stateFile(), `${JSON.stringify(state, null, 2)}\n`);
+}
+/** The team project this laptop is recording against, or null. Cheap: one small file read. */
+export function activeProject() {
+    const s = loadState();
+    if (!s.active || !s.projects[s.active])
+        return null;
+    return { projectId: s.active, ...s.projects[s.active] };
+}
+export function defaultOutboxDir(projectId) {
+    return path.join(cspeachRoot(), 'register', projectId, 'outbox');
+}
+/** `mike-khan-7f3a`: the person plus this machine, so one file never has two writers. */
+export function writerIdFor(name, machine = os.hostname()) {
+    const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'writer';
+    return `${slug}-${createHash('sha256').update(machine.toLowerCase()).digest('hex').slice(0, 4)}`;
+}
+export function projectIdFor(name, rand = defaultRand) {
+    const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'project';
+    return `${slug}-${rand(2)}`;
+}
+export const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * A byte-order mark, taken off by NUMBER. Notepad, Excel and a few sync tools
+ * put one in front of a file they save as UTF-8; `JSON.parse` then refuses the
+ * whole file. Written as a character in a regex it is invisible in the source —
+ * which is how two of these were copied around and a third was forgotten — so
+ * this is the one place that knows about it, and it names the code point.
+ */
+export const stripBom = (text) => (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+function readJson(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        throw new RegisterError(`Cannot read ${file}`);
+    }
+    try {
+        return JSON.parse(stripBom(text));
+    }
+    catch {
+        throw new RegisterError(`${file} is not valid JSON`);
+    }
+}
+export function readProjectFile(projectDir) {
+    const p = readJson(path.join(projectDir, TEAM_FILE));
+    if (p?.kind !== 'team-project' || typeof p.projectId !== 'string' || typeof p.lead?.name !== 'string') {
+        throw new RegisterError(`${path.join(projectDir, TEAM_FILE)} is not a CSPeach team project file`);
+    }
+    return p;
+}
+/**
+ * What SAP accepts as a check variant name. Checked by every caller BEFORE a
+ * run, not only at the moment of writing: a name that cannot be written must
+ * not be measured with either.
+ */
+export const VARIANT_NAME = /^[A-Z0-9_/]{1,40}$/;
+/**
+ * The one field of the team project file that is set after `init`: which ATC
+ * check variant this team project measures with. Written whole, then renamed,
+ * like a record — a sync tool must never pick up half a team project file.
+ */
+export function writeProjectVariant(projectDir, variant) {
+    if (!VARIANT_NAME.test(variant))
+        throw new RegisterError(`"${variant}" is not an ATC check variant name.`);
+    const file = path.join(projectDir, TEAM_FILE);
+    const next = { ...readProjectFile(projectDir), atcVariant: variant };
+    fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(next, null, 2)}\n`);
+    fs.renameSync(`${file}.tmp`, file);
+}
+/**
+ * One read, one sentence. `existsSync` then `readFileSync` answers only the
+ * easy failure: a folder halfway through a sync also gives EISDIR (a folder
+ * where the file goes), EBUSY and EPERM (a file the sync tool still holds, or
+ * one OneDrive has not fetched). None of those may reach a person as a stack.
+ */
+function readTextOrSay(file, missing) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            throw new RegisterError(missing);
+        throw new RegisterError(`${file} could not be read. It may still be syncing.`);
+    }
+}
+export function readBaseline(projectDir) {
+    const project = readProjectFile(projectDir);
+    const file = path.join(projectDir, project.baseline?.file ?? BASELINE_FILE);
+    const text = readTextOrSay(file, `The baseline file is missing: ${file}`);
+    if (project.baseline?.sha256 && sha256(text) !== project.baseline.sha256) {
+        throw new RegisterError(`${file} does not match the checksum in the team project file. It was changed or only partly copied.`);
+    }
+    // A folder halfway through a sync is the everyday reason this file is not
+    // whole JSON. A person reads a sentence about their own folder here, never a
+    // parser's stack trace about a position in a byte stream.
+    let b;
+    try {
+        b = JSON.parse(stripBom(text));
+    }
+    catch {
+        throw new RegisterError(`${file} could not be read. It may still be syncing.`);
+    }
+    if (b?.kind !== 'baseline' || !Array.isArray(b.objects))
+        throw new RegisterError(`${file} is not a baseline file`);
+    // Every caller reads `o.type` and `o.name` straight away. One hand-edited or
+    // half-copied entry that is not an object would come out as a TypeError with
+    // a stack, from whichever command happened to touch it first.
+    if (b.objects.some((o) => !o || typeof o.type !== 'string' || typeof o.name !== 'string')) {
+        throw new RegisterError(`${file} could not be read. It may still be syncing.`);
+    }
+    return b.objects;
+}
+export function readLanes(projectDir) {
+    const file = path.join(projectDir, LANES_FILE);
+    if (!fs.existsSync(file))
+        return [];
+    const l = readJson(file);
+    return Array.isArray(l?.lanes) ? l.lanes : [];
+}
+export function writeLanes(projectDir, projectId, lanes) {
+    fs.writeFileSync(path.join(projectDir, LANES_FILE), `${JSON.stringify({ kind: 'lanes', formatVersion: 1, projectId, lanes }, null, 2)}\n`);
+}
+/**
+ * A record is a short list of object names. Anything this big is a dump, a log
+ * or something that is not a record at all, and reading it would cost a
+ * gigabyte of memory before `JSON.parse` could say so.
+ */
+const MAX_RECORD_BYTES = 64 * 1024 * 1024;
+/** One record file, or nothing. Counted as unreadable rather than thrown, whatever is wrong with it. */
+function readRecord(file) {
+    try {
+        if (fs.statSync(file).size > MAX_RECORD_BYTES)
+            return { ok: false };
+        return { ok: true, value: JSON.parse(stripBom(fs.readFileSync(file, 'utf8'))) };
+    }
+    catch {
+        // A file can be listed before the sync tool has finished writing it, or be a
+        // folder, or be held open: skip and count, never fail.
+        return { ok: false };
+    }
+}
+/** Every record-shaped JSON under a folder: writers/<id>/records, rulings, baseline/measurement-*.json. */
+export function collectRecords(root) {
+    const records = [];
+    let unreadable = 0;
+    let files = 0;
+    const take = (file) => {
+        files += 1;
+        const read = readRecord(file);
+        if (read.ok)
+            records.push(read.value);
+        else
+            unreadable += 1;
+    };
+    const readDir = (dir) => {
+        let names = [];
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!name.toLowerCase().endsWith('.json'))
+                continue;
+            take(path.join(dir, name));
+        }
+    };
+    let writers = [];
+    try {
+        writers = fs.readdirSync(path.join(root, 'writers'));
+    }
+    catch { /* none handed in yet */ }
+    for (const w of writers)
+        readDir(path.join(root, 'writers', w, 'records'));
+    readDir(path.join(root, 'rulings'));
+    try {
+        for (const name of fs.readdirSync(path.join(root, 'baseline'))) {
+            if (!/^measurement-.*\.json$/i.test(name))
+                continue;
+            // Measurement zero lands here, written by the lead and then synced: the
+            // same hazards as any other record, read the same way.
+            take(path.join(root, 'baseline', name));
+        }
+    }
+    catch { /* no baseline folder here (an outbox has none) */ }
+    return { records, unreadable, files };
+}

package/dist/repl/post-turn-status.js

@@ -23,6 +23,7 @@ import { globalStore } from '../ui/sap-state-store.js';
 import { globalCredits } from '../cost/credits.js';
 import { printStatusFooter, formatStatusFooter } from '../renderer/status-footer.js';
 import { shouldUseInk } from '../renderer/tty.js';
+import { isUserPrompt } from '../session/user-prompt.js';
 export function snapshotTurnStart(session) {
     return {
         input: session.usage.input_tokens,
@@ -34,7 +35,7 @@ export function snapshotTurnStart(session) {
 }
 export function pushPostTurnStatus(params) {
     const { session, selectedAlias, snapshot, chunkEmitter, turnModel } = params;
-    const userTurns = session.messages.filter((m) => m.role === 'user' && typeof m.content === 'string').length;
+    const userTurns = session.messages.filter(isUserPrompt).length;
     const lifetimeTokensAfter = session.usage.input_tokens + session.usage.output_tokens;
     const lifetimeTokensBefore = snapshot.input + snapshot.output;
     const turnTokens = Math.max(0, lifetimeTokensAfter - lifetimeTokensBefore);

package/dist/repl.js

@@ -1014,6 +1014,10 @@ export async function runRepl(opts) {
                             // from regex, not the LLM, and surface the real cause.
                             chunkEmitter.emit('chunk', chalk.dim(`↪ [offline classifier — proxy unreachable: ${c.transport_error ?? 'unknown'}]\n`));
                         }
+                        if (c.screenshot) {
+                            chunkEmitter.emit('chunk', chalk.dim(`┄ Screenshot: ${c.screenshot}
+`));
+                        }
                         const decision = decideRouting(c);
                         // 2026-05-17 — pass the just-used skill so the picker can
                         // default cursor to it (one-Enter "continue" UX for follow-up
@@ -2482,8 +2486,16 @@ export async function runRepl(opts) {
                 // user re-submits the empty pre-fill, just silently re-fill
                 // without re-spamming the hint line. Tracked via lastEmptyPrefill.
                 if (lastEmptyPrefill !== head) {
-                    console.log(chalk.dim(`↪ ${head} — type your prompt and press Enter ` +
-                        chalk.dim(`(or "/cancel" to abandon)`)));
+                    // 2026-09-23 (Glenn's first run): "type your prompt" never said WHAT
+                    // to type, and our own skills suggest a bare next command
+                    // ("/abap-estimate next"), so the user is told to run something and
+                    // then asked an unanswerable question. Every skill now carries an
+                    // `asks` line with an example (skill-catalog.ts).
+                    const asks = SKILL_CATALOG.find((e) => `/${e.name}` === head)?.asks;
+                    console.log(chalk.dim(asks
+                        ? `↪ ${head} — ${asks}`
+                        : `${'↪'} ${head} — type your prompt and press Enter`));
+                    console.log(chalk.dim('  Enter to send · /cancel to abandon'));
                     lastEmptyPrefill = head;
                 }
                 // 2026-05-02: bake the pre-fill into the next prompt string
@@ -2569,6 +2581,8 @@ export async function runRepl(opts) {
                     if (c.offline) {
                         console.log(chalk.dim(`↪ [offline classifier — proxy unreachable: ${c.transport_error ?? 'unknown'}]`));
                     }
+                    if (c.screenshot)
+                        console.log(chalk.dim(`┄ Screenshot: ${c.screenshot}`));
                     const decision = decideRouting(c);
                     // 2026-05-17 — pass the just-used skill so the picker can
                     // default cursor to it. session.skill = immediately-previous

package/dist/rewind/candidates.js

@@ -24,6 +24,7 @@
  *   - sap_delete_object ⇒ restorable when a pre-delete snapshot exists (the
  *     snapshot IS the prior source; the executor recreates it).
  */
+import { includeSnapshotType } from '../tools/include-snapshot.js';
 /** The five write tools whose effects can (potentially) be rewound. */
 const WRITE_TOOLS = new Set([
     'sap_set_source',
@@ -116,7 +117,19 @@ function extractIdentity(tool, rawArgs) {
     const args = (rawArgs ?? {});
     if (IMPLICIT_CLASS_TOOLS.has(tool)) {
         const object = pickString(args, 'className') ?? pickString(args, 'class_name');
-        return object ? { object: object.toUpperCase(), objType: 'CLAS' } : null;
+        if (!object)
+            return null;
+        // An include write is rewound from the INCLUDE's own snapshot
+        // (type CLAS.<INCLUDE>), never from the class main source — restoring the
+        // main source would report success while the include change stayed.
+        // No includeType recorded ⇒ unknown target ⇒ not rewindable.
+        if (tool === 'sap_set_class_include') {
+            const includeType = pickString(args, 'includeType');
+            return includeType
+                ? { object: object.toUpperCase(), objType: includeSnapshotType(includeType) }
+                : null;
+        }
+        return { object: object.toUpperCase(), objType: 'CLAS' };
     }
     const object = pickString(args, 'name') ?? pickString(args, 'object_name');
     if (!object)

package/dist/rewind/restore.js

@@ -27,6 +27,7 @@ import { getEffectiveWriteMode } from '../repl/mode-cycle.js';
 import { effectiveRisk } from '../approvals/risk-floor.js';
 import { verifySyntax, verifyActive } from '../tools/verify.js';
 import { renderDiff } from '../repl/diff-display.js';
+import { parseIncludeSnapshotType } from '../tools/include-snapshot.js';
 /** Compact single-line failure text for receipts / error envelopes. */
 function shortError(err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -55,6 +56,10 @@ export async function restoreSnapshot(c, deps) {
     if (c.snapshotId === null) {
         return { ok: false, steps, error: 'no snapshot to restore from' };
     }
+    // A class-include candidate (objType CLAS.<INCLUDE>) restores that include;
+    // syntax check / activation / verify then run on the CLASS.
+    const include = parseIncludeSnapshotType(c.objType);
+    const repoType = include ? 'CLAS' : c.objType;
     // ── Step 2: Read the snapshot source (the content we will restore) ────────
     let snapshotSource;
     try {
@@ -67,12 +72,23 @@ export async function restoreSnapshot(c, deps) {
     // A 404 means the object was deleted this session; current = null and we
     // will recreate it. Any OTHER read failure is NOT proof of absence — stop
     // rather than blindly treat it as a create.
+    // Class include candidates (objType CLAS.<INCLUDE>) read and write the
+    // include itself; there is no delete-restore for an include, so a 404 stops.
     let currentSource;
     try {
-        currentSource = await deps.adt.getSource(c.objType, c.object);
+        if (include) {
+            const inc = await deps.adt.classIncludes(c.object, include);
+            if (typeof inc !== 'string') {
+                return { ok: false, steps, error: 'could not read current include source' };
+            }
+            currentSource = inc;
+        }
+        else {
+            currentSource = await deps.adt.getSource(c.objType, c.object);
+        }
     }
     catch (err) {
-        if (err instanceof SapError && err.httpStatus === 404) {
+        if (err instanceof SapError && err.httpStatus === 404 && !include) {
             currentSource = null;
         }
         else {
@@ -87,7 +103,7 @@ export async function restoreSnapshot(c, deps) {
     const change = {
         op,
         object: c.object,
-        type: c.objType,
+        type: repoType,
         diff: renderDiff(currentSource ?? '', snapshotSource, {
             label: `${c.objType}/${c.object}`,
             syntaxHighlight: false,
@@ -143,20 +159,38 @@ export async function restoreSnapshot(c, deps) {
             return { ok: false, steps, error: `recreate failed: ${created.error ?? `HTTP ${created.httpStatus}`}` };
         }
     }
-    let writeResult;
-    try {
-        writeResult = await deps.adt.setSource(c.objType, c.object, snapshotSource, deps.transport);
-    }
-    catch (err) {
-        record('② written ✗');
-        return { ok: false, steps, error: `write failed: ${shortError(err)}` };
+    if (include) {
+        // Include restore: write the include back. setClassInclude reads its own
+        // write back and returns written:false on a discarded or refused PUT.
+        let incResult;
+        try {
+            incResult = await deps.adt.setClassInclude(c.object, include, snapshotSource, deps.transport);
+        }
+        catch (err) {
+            record('② written ✗');
+            return { ok: false, steps, error: `write failed: ${shortError(err)}` };
+        }
+        if (!incResult.written) {
+            record('② written ✗');
+            return { ok: false, steps, error: `write failed: ${incResult.error ?? `HTTP ${incResult.httpStatus}`}` };
+        }
     }
-    // setSource RETURNS (does not throw) on HTTP 4xx — check the return value,
-    // exactly as sap_set_source does.
-    if (writeResult.error || (writeResult.writeStatus !== undefined && writeResult.writeStatus >= 400)) {
-        const detail = writeResult.error ?? `HTTP ${writeResult.writeStatus}`;
-        record('② written ✗');
-        return { ok: false, steps, error: `write failed: ${detail}` };
+    else {
+        let writeResult;
+        try {
+            writeResult = await deps.adt.setSource(c.objType, c.object, snapshotSource, deps.transport);
+        }
+        catch (err) {
+            record('② written ✗');
+            return { ok: false, steps, error: `write failed: ${shortError(err)}` };
+        }
+        // setSource RETURNS (does not throw) on HTTP 4xx — check the return value,
+        // exactly as sap_set_source does.
+        if (writeResult.error || (writeResult.writeStatus !== undefined && writeResult.writeStatus >= 400)) {
+            const detail = writeResult.error ?? `HTTP ${writeResult.writeStatus}`;
+            record('② written ✗');
+            return { ok: false, steps, error: `write failed: ${detail}` };
+        }
     }
     record('② written ✓');
     // ── Step 7: Syntax check (Rule 10) — errors ⇒ STOP, do NOT activate ───────
@@ -167,7 +201,7 @@ export async function restoreSnapshot(c, deps) {
     // WRITE HAPPENED; only the verification/activation call failed to run.
     let syntax;
     try {
-        syntax = await verifySyntax(deps.adt, c.object, c.objType);
+        syntax = await verifySyntax(deps.adt, c.object, repoType);
     }
     catch (err) {
         record(`③ syntax — check failed to run: ${shortError(err)}`);
@@ -191,7 +225,7 @@ export async function restoreSnapshot(c, deps) {
     // ── Step 8: Activate + verify (Rule 10) ───────────────────────────────────
     let activation;
     try {
-        activation = await deps.adt.activate(c.objType, c.object);
+        activation = await deps.adt.activate(repoType, c.object);
     }
     catch (err) {
         record(`④ activate — call failed: ${shortError(err)}`);
@@ -217,7 +251,7 @@ export async function restoreSnapshot(c, deps) {
     // past the receipt.
     let active;
     try {
-        active = await verifyActive(deps.adt, c.object, c.objType);
+        active = await verifyActive(deps.adt, c.object, repoType);
     }
     catch (err) {
         active = { active: false, verifyError: shortError(err) };

package/dist/router/classifier.js

@@ -3,6 +3,8 @@ import { getStore } from '../auth/api-key.js';
 import { classify as classifyLocal } from '../classifier/client.js';
 import { SKILL_CATALOG, SKILL_ALIASES, resolveSkillAlias } from '../skill-catalog.js';
 import { isBuiltinCommandHead } from '../repl/builtin-commands.js';
+import { expandImageAttachments } from '../projects/image-attachments.js';
+import { expandImageChips } from '../ui/clipboard-image.js';
 // 8s — sized to cover the observed Fly cold-start (~3.2s on the 2026-05-20
 // probe) plus headroom for a slow network. Tighter values risk timing out
 // legitimate cold-start hits and burning the retry budget on the same.
@@ -25,7 +27,7 @@ function extractCause(err) {
     }
     return e.message;
 }
-async function tryFetchOnce(proxyUrl, key, prompt, context) {
+async function tryFetchOnce(proxyUrl, key, prompt, context, images = []) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
     try {
@@ -35,7 +37,7 @@ async function tryFetchOnce(proxyUrl, key, prompt, context) {
                 'Authorization': `Bearer ${key}`,
                 'Content-Type': 'application/json',
             },
-            body: JSON.stringify({ prompt, context }),
+            body: JSON.stringify(images.length > 0 ? { prompt, context, images } : { prompt, context }),
             signal: ctrl.signal,
         });
     }
@@ -43,7 +45,24 @@ async function tryFetchOnce(proxyUrl, key, prompt, context) {
         clearTimeout(timer);
     }
 }
-export async function classifyPrompt(prompt, context) {
+/**
+ * Screenshot-aware routing (2026-09-23): images in the prompt (pasted
+ * [Image #N] chips or image paths) go to the router so it reads the picture
+ * with the text. Any problem (too large, too many, unreadable) → classify on
+ * text; the turn itself reports the error when it runs.
+ */
+async function promptImages(prompt, cwd) {
+    try {
+        const r = await expandImageAttachments(expandImageChips(prompt), cwd);
+        if (r.error)
+            return [];
+        return r.images.map((im) => ({ media_type: im.source.media_type, data: im.source.data }));
+    }
+    catch {
+        return [];
+    }
+}
+export async function classifyPrompt(prompt, context, opts = {}) {
     // D22/D35 structural invariant (2026-06-11) — an explicit slash command
     // must NEVER reach the classifier. The S3 battery proved the failure mode:
     // `/abap-plan <multiline>` failed the old parseShortcut regex, the whole
@@ -61,6 +80,7 @@ export async function classifyPrompt(prompt, context) {
     const key = await store.get();
     if (!key)
         throw new Error('no_api_key');
+    const images = await promptImages(prompt, opts.cwd ?? process.cwd());
     let r;
     let lastErr;
     // Two attempts total: the second masks the common case of a stale
@@ -71,7 +91,7 @@ export async function classifyPrompt(prompt, context) {
     // they bubble through as before.
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
-            r = await tryFetchOnce(cfg.proxy_url, key, prompt, context);
+            r = await tryFetchOnce(cfg.proxy_url, key, prompt, context, images);
             break;
         }
         catch (err) {

package/dist/session/recap.js

@@ -26,6 +26,7 @@ import { readProjectFile } from '../projects/status.js';
 import { parsePlanContent } from '../projects/plan-schema.js';
 import { statusesFromItems, isPhaseSatisfied } from '../projects/plan-run.js';
 import { defaultWorkspaceFor } from '../projects/workspace.js';
+import { userPromptText } from './user-prompt.js';
 /** Wave-1 truncation rule (see /reroute): ≤60 chars total, '...' suffix. */
 function truncatePrompt(s) {
     return s.length > 60 ? s.slice(0, 57) + '...' : s;
@@ -37,10 +38,12 @@ function truncatePrompt(s) {
 export function buildRecap(session, cwd, opts) {
     const lines = [];
     // ── line 1: session orientation ─────────────────────────────────────────
-    // "User turns" = plain-string user messages (tool_result rounds are arrays)
-    // — same counting rule as the resume picker (session/store.ts).
-    const userMessages = session.messages.filter((m) => m.role === 'user' && typeof m.content === 'string');
-    const turns = userMessages.length;
+    // "User turns" = typed prompts, not tool_result rounds — same counting
+    // rule as the resume picker (session/store.ts); see session/user-prompt.ts.
+    const userTexts = session.messages
+        .map(userPromptText)
+        .filter((t) => t !== null);
+    const turns = userTexts.length;
     if (turns === 0)
         return [];
     const skillLabel = session.skill ? `/${session.skill}` : 'no skill';
@@ -50,7 +53,7 @@ export function buildRecap(session, cwd, opts) {
     // rule as the picker's promptSnippet).
     let prompt = session.lastUserPrompt;
     if (!prompt) {
-        const last = userMessages[userMessages.length - 1].content;
+        const last = userTexts[userTexts.length - 1];
         prompt = last.replace(/<session_context>[\s\S]*?<\/session_context>\s*/g, '').trim() || null;
     }
     const quoted = prompt ? `"${truncatePrompt(prompt)}"` : '(no prompt)';

package/dist/session/resume.js

@@ -19,23 +19,15 @@ export async function runResume(id) {
             return b.lastTurnAt.localeCompare(a.lastTurnAt);
         });
         targetId = await select({
-            message: 'Pick a session to resume:',
-            choices: sorted.map((s) => {
-                const flag = s.interrupted ? chalk.yellow('⚠ ') : '  ';
-                const idCol = chalk.cyan(s.id.padEnd(8));
-                const timeCol = chalk.gray(formatTimeAgo(s.lastTurnAt).padEnd(10));
-                const sapCol = chalk.gray((s.sapSystem ?? '-').padEnd(8));
-                const skillCol = chalk.gray(`/${s.skill ?? '-'}`.padEnd(22));
-                const turns = chalk.gray(`${s.userTurnCount}t`.padStart(3));
-                const snippet = s.promptSnippet ?? chalk.dim('(no prompt)');
-                return {
-                    value: s.id,
-                    name: `${flag}${idCol} ${timeCol} ${sapCol} ${skillCol} ${turns}  ${snippet}`,
-                    description: s.interrupted
-                        ? `Interrupted (${s.interruptedReason ?? 'unknown'}) — type "continue" after resume`
-                        : `${s.userTurnCount} prior turn(s) — pick up from where you left off`,
-                };
-            }),
+            message: `Pick a session to resume:
+${formatSessionHeader()}`,
+            choices: sorted.map((s) => ({
+                value: s.id,
+                name: formatSessionRow(s),
+                description: s.interrupted
+                    ? `Interrupted (${s.interruptedReason ?? 'unknown'}) — type "continue" after resume`
+                    : `${s.userTurnCount} prior turn(s) — pick up from where you left off`,
+            })),
         });
     }
     let session;
@@ -75,3 +67,31 @@ export async function runResume(id) {
     // to the persistence work in agent/loop.ts.
     return runRepl({ resumedSession: session });
 }
+// 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 };
+export function formatSessionRow(s) {
+    const flag = s.interrupted ? chalk.yellow('⚠ ') : '  ';
+    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 snippet = s.promptSnippet ?? chalk.dim('(no prompt)');
+    return `${flag}${idCol} ${timeCol} ${sapCol} ${skillCol} ${turns}  ${snippet}`;
+}
+/**
+ * One dim line naming the row columns (2026-09-23 — rows had no labels). The
+ * 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() {
+    return chalk.dim('    ' +
+        [
+            'ID'.padEnd(W.id),
+            'LAST USED'.padEnd(W.time),
+            'SYSTEM'.padEnd(W.sap),
+            'SKILL'.padEnd(W.skill),
+            'TURNS'.padStart(W.turns),
+        ].join(' ') +
+        '  LAST PROMPT');
+}

package/dist/session/store.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { sessionsDir, pinnedSessionsDir } from '../config/paths.js';
 import { SCHEMA_VERSION } from './schema.js';
+import { userPromptText, isUserPrompt } from './user-prompt.js';
 export function makeSessionId() {
     return crypto.randomBytes(4).toString('hex');
 }
@@ -107,16 +108,17 @@ export async function listSessions(limit = 10) {
             let promptSnippet = null;
             for (let i = messages.length - 1; i >= 0; i--) {
                 const m = messages[i];
-                if (m && m.role === 'user' && typeof m.content === 'string') {
+                const text = m ? userPromptText(m) : null;
+                if (text !== null) {
                     // Strip <session_context>...</session_context> wrapper that the
                     // first turn injects, leaving only the user-typed prompt visible
                     // in the picker.
-                    const stripped = m.content.replace(/<session_context>[\s\S]*?<\/session_context>\s*/g, '').trim();
+                    const stripped = text.replace(/<session_context>[\s\S]*?<\/session_context>\s*/g, '').trim();
                     promptSnippet = (stripped || '<empty>').slice(0, 80);
                     break;
                 }
             }
-            const userTurnCount = messages.filter((m) => m?.role === 'user' && typeof m.content === 'string').length;
+            const userTurnCount = messages.filter((m) => m && isUserPrompt(m)).length;
             results.push({
                 id: parsed.id,
                 startedAt: parsed.started_at,