@cspeach/cli 1.1.53 → 1.1.54

package/dist/projects/saved-lines.js

@@ -5,14 +5,15 @@
  * below the line" block (subject, body, review steps, sign-off). It looked
  * cluttered and signed itself with the OS account name ("Admin"). Now:
  *
- *   Saved: <file name> (in this project's .cspeach folder)
+ *   Saved: <full path> (in this project's .cspeach folder)
  *   To review or share: open cspeach.dev/edit and drop the file in.
  *
  * Never prints a user name.
  */
-import { basename, dirname, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { resolveProjectFolderSync } from './project-folder.js';
-function editorLabel() {
+import { isSharedSpecPath } from './spec-share.js';
+export function editorLabel() {
     const url = process.env.CSPEACH_EDITOR_URL?.trim();
     return url ? url : 'cspeach.dev/edit';
 }
@@ -24,23 +25,24 @@ function sameDir(a, b) {
     return norm(a) === norm(b);
 }
 /**
- * `<file name> (in <where>)` — names the folder kind (2026-10-08): this
- * project's .cspeach folder (solo), your own working folder (team), or the
- * home fallback folder with a hint. Anywhere else: the folder itself.
+ * `<full path> (in <where>)` — names the folder kind (2026-10-08): this
+ * project's .cspeach folder (solo), the shared team folder (a team spec),
+ * your own working folder (team), or the home fallback folder with a hint. Anywhere else: the full path alone.
+ * 2026-10-27 — the full path, not the bare file name: a standalone customer
+ * could not find the file (it sits in .cspeach, the Word copy in cspeach-out).
  */
 export function savedLocation(savedPath, cwd) {
-    const dir = dirname(savedPath);
+    const full = resolve(savedPath);
     const pf = resolveProjectFolderSync(cwd);
-    let where = dir;
-    if (sameDir(dir, pf.workDir)) {
-        if (pf.kind === 'solo')
-            where = "this project's .cspeach folder";
-        else if (pf.kind === 'team')
-            where = 'your own working folder for this team project, not shared';
-        else
-            where = `${dir} — start CSPeach in a project folder to keep projects apart`;
-    }
-    return `${basename(savedPath)} (in ${where})`;
+    if (pf.kind === 'team' && isSharedSpecPath(pf.projectDir, savedPath))
+        return `${full} (in the shared team folder, for the developer)`;
+    if (!sameDir(dirname(full), pf.workDir))
+        return full;
+    if (pf.kind === 'solo')
+        return `${full} (in this project's .cspeach folder)`;
+    if (pf.kind === 'team')
+        return `${full} (in your own working folder for this team project, not shared)`;
+    return `${full} (start CSPeach in a project folder to keep projects apart)`;
 }
 export function formatSavedLines(savedPath, cwd) {
     return [

package/dist/projects/spec-share.js

@@ -0,0 +1,239 @@
+/**
+ * Team build (spec 2026-10-25) — the spec lands in the shared team folder.
+ *
+ * A spec-gap saved in a team build folder goes to `<team>/specs/<slug>/`, for
+ * the developer, instead of the seat's private `.cspeach` folder:
+ *
+ *   specs/<slug>/<envelope>.cspeach.json   the author's file, never rewritten
+ *   specs/<slug>/<slug>.md (+ .docx)       the spec as people read it
+ *   specs/<slug>/status/<stamp>-<status>-<rand>.json   added-only status records
+ *   specs/<slug>/answers/<stamp>-<gap>-<rand>.json     added-only answer records
+ *   specs/<slug>/files/                    room for the files that go with it
+ *
+ * One writer per file, records only added: a second save of the same title
+ * lands beside the first (`-2`), an answer is a record of its own, and the
+ * spec people read is composed at read time (composeSpec). The model's file
+ * tools never write `specs/` (tools/_team-work-path.ts TEAM_OWNED_DIRS).
+ *
+ * Ruling R10: the build project is found by the folder CSPeach runs in, never
+ * by `activeProject()` (a developer on a clean-core wave keeps that active).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readProjectFile as readEnvelopeFile } from './status.js';
+import { saveProject } from './save.js';
+import { applyBlockerAnswers } from './answer-blockers.js';
+import { resolveProjectFolderSync, key } from './project-folder.js';
+import { isBuildProject } from '../commands/team-build.js';
+import { readProjectFile, loadState, writerIdFor, defaultRand, stripBom } from '../register/store.js';
+import { writeWhole } from '../register/write-whole.js';
+import { fileStamp } from '../register/records.js';
+import { writeNoClobber, writeDocxNextTo } from '../docx/write-docx.js';
+import { metaFromMarkdown } from '../docx/doc-meta.js';
+export const SPECS_DIR = 'specs';
+const STATUSES = ['draft', 'ready for build', 'being built'];
+/** Same instant: the later step in the life of a spec wins. */
+const STATUS_RANK = { draft: 0, 'ready for build': 1, 'being built': 2 };
+/** A folder name for a spec title: lower-case, `[^a-z0-9]+` → `-`, ≤ 60 chars, `spec` when empty. */
+export function specSlug(title) {
+    const s = String(title ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60)
+        .replace(/-+$/, '');
+    return s || 'spec';
+}
+/**
+ * The team build folder a spec-gap save goes to, by the folder CSPeach runs
+ * in (R10). Null for any other artefact, folder kind or team project type.
+ */
+export function sharedSpecTargetFor(cwd, artefactType) {
+    if (artefactType !== 'spec-gap')
+        return null;
+    try {
+        const pf = resolveProjectFolderSync(cwd);
+        if (pf.kind !== 'team')
+            return null;
+        const project = readProjectFile(pf.projectDir);
+        if (!isBuildProject(project))
+            return null;
+        return { teamDir: pf.projectDir, projectId: project.projectId };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who writes a spec record: the name this laptop records under for the build
+ * project (`team join --as`, kept in the register state by project id — not
+ * the active project, R10), else the author name; the writer id is
+ * `writerIdFor(name)`, as `cspeach team join` derives it.
+ */
+export function specAuthorFor(projectId, fallbackName) {
+    let saved;
+    try {
+        saved = loadState().projects[projectId]?.name;
+    }
+    catch {
+        saved = undefined;
+    }
+    const name = saved ?? fallbackName;
+    return { name, writer: writerIdFor(name) };
+}
+const statusSlug = (s) => s.replace(/\s+/g, '-');
+const safePart = (s) => s.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'x';
+export function writeStatusRecord(specDir, rec, rand = defaultRand) {
+    const full = { kind: 'spec-status', formatVersion: 1, ...rec };
+    const file = path.join(specDir, 'status', `${fileStamp(new Date(rec.at))}-${statusSlug(rec.status)}-${rand(2)}.json`);
+    writeWhole(file, `${JSON.stringify(full, null, 2)}\n`);
+    return file;
+}
+export function writeAnswerRecord(specDir, rec, rand = defaultRand) {
+    const full = { kind: 'spec-answer', formatVersion: 1, ...rec };
+    const file = path.join(specDir, 'answers', `${fileStamp(new Date(rec.at))}-${safePart(rec.gapId)}-${rand(2)}.json`);
+    writeWhole(file, `${JSON.stringify(full, null, 2)}\n`);
+    return file;
+}
+/** Every `*.json` in `dir`, parsed; unreadable files are skipped. */
+function readJsonDir(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names.sort()) {
+        if (!n.endsWith('.json'))
+            continue;
+        try {
+            out.push(JSON.parse(stripBom(fs.readFileSync(path.join(dir, n), 'utf8'))));
+        }
+        catch { /* skipped */ }
+    }
+    return out;
+}
+const isBy = (b) => !!b && typeof b.name === 'string' && typeof b.writer === 'string';
+export function readSpecStatus(specDir) {
+    const history = readJsonDir(path.join(specDir, 'status')).filter((r) => r?.kind === 'spec-status' && STATUSES.includes(r.status) && typeof r.at === 'string' && isBy(r.by));
+    history.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : STATUS_RANK[a.status] - STATUS_RANK[b.status]));
+    const record = history.length ? history[history.length - 1] : null;
+    return { current: record?.status ?? 'draft', record, history };
+}
+export function readAnswers(specDir) {
+    return readJsonDir(path.join(specDir, 'answers')).filter((r) => r?.kind === 'spec-answer' && typeof r.gapId === 'string' && typeof r.answer === 'string' && typeof r.at === 'string' && isBy(r.by));
+}
+/** The spec as people read it: the author's envelope with every answer record applied, in time order. */
+export function composeSpec(env, answers) {
+    const ordered = [...answers].sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+    let out = env;
+    for (const a of ordered) {
+        out = applyBlockerAnswers(out, new Map([[a.gapId, a.answer]]), { name: a.by.name, role: 'consultant' }, a.at);
+    }
+    return out;
+}
+export async function writeSharedSpec(a) {
+    const slug = specSlug(a.env.title);
+    const specDir = path.join(a.teamDir, SPECS_DIR, slug);
+    fs.mkdirSync(path.join(specDir, 'files'), { recursive: true });
+    fs.mkdirSync(path.join(specDir, 'answers'), { recursive: true });
+    // saveProject never overwrites: a taken name gets -2, -3 … beside it.
+    const jsonPath = await saveProject(a.env, { cwd: specDir });
+    const mdPath = await writeNoClobber(path.join(specDir, `${slug}.md`), a.markdown);
+    let docxPath = null;
+    try {
+        docxPath = await writeDocxNextTo(mdPath, a.markdown, metaFromMarkdown(a.markdown, {
+            date: a.today, kind: 'document', ...(a.sapSystem ? { system: a.sapSystem } : {}),
+        }));
+    }
+    catch {
+        docxPath = null;
+    }
+    const statusPath = writeStatusRecord(specDir, {
+        projectId: a.projectId, slug, file: path.basename(jsonPath), status: 'draft', by: a.by, at: a.now.toISOString(),
+    }, a.rand);
+    return { specDir, jsonPath, mdPath, docxPath, statusPath };
+}
+export function listSharedSpecs(teamDir) {
+    const root = path.join(teamDir, SPECS_DIR);
+    let dirs;
+    try {
+        dirs = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const d of dirs.sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))) {
+        if (!d.isDirectory())
+            continue;
+        const specDir = path.join(root, d.name);
+        let names;
+        try {
+            names = fs.readdirSync(specDir);
+        }
+        catch {
+            continue;
+        }
+        let best = null;
+        for (const n of names) {
+            if (!n.endsWith('.cspeach.json'))
+                continue;
+            const p = path.join(specDir, n);
+            try {
+                const env = readEnvelopeFile(p);
+                if (env.artefactType !== 'spec-gap')
+                    continue;
+                const mtime = fs.statSync(p).mtimeMs;
+                if (!best || env.version > best.env.version || (env.version === best.env.version && mtime > best.mtime))
+                    best = { path: p, env, mtime };
+            }
+            catch { /* unreadable envelope: skipped */ }
+        }
+        if (!best || best.env.artefactType !== 'spec-gap')
+            continue;
+        // R11: answers apply only to the envelope they were recorded for.
+        const bestFile = path.basename(best.path);
+        const composed = composeSpec(best.env, readAnswers(specDir).filter((a) => a.file === bestFile));
+        if (composed.artefactType !== 'spec-gap')
+            continue;
+        const open = new Set(composed.interaction.items.filter((i) => i.status === 'open').map((i) => i.id));
+        const questions = [];
+        for (const s of composed.content.sections) {
+            for (const g of s.gaps)
+                if (open.has(g.id))
+                    questions.push({ id: g.id, severity: g.severity, text: g.text });
+        }
+        const openQuestions = [...questions.filter((q) => q.severity === 'BLOCKER'), ...questions.filter((q) => q.severity !== 'BLOCKER')];
+        const st = readSpecStatus(specDir);
+        out.push({
+            slug: d.name,
+            specDir,
+            envelopePath: best.path,
+            title: best.env.title,
+            author: best.env.createdBy.name,
+            createdAt: best.env.createdAt,
+            summary: `${best.env.content.inputType} · ${best.env.content.inferredDomain}`,
+            openQuestions,
+            status: st.current,
+            statusBy: st.record?.by.name ?? null,
+            statusAt: st.record?.at ?? null,
+        });
+    }
+    return out;
+}
+/** True when `p`, links followed, is inside `<teamDir>/specs/`. */
+export function isSharedSpecPath(teamDir, p) {
+    try {
+        const root = key(path.join(teamDir, SPECS_DIR));
+        // A file not written yet: its folder, links followed, decides.
+        const target = fs.existsSync(p) ? key(p) : path.join(key(path.dirname(p)), process.platform === 'win32' ? path.basename(p).toLowerCase() : path.basename(p));
+        const rel = path.relative(root, target);
+        return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/register/picture.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { buildRegister, narrowedLanes } from '@cspeach/register-core';
-import { collectRecords, readBaseline, readEstate, readLanes, readProjectFile } from './store.js';
+import { collectRecords, coreProject, readBaseline, readEstate, readLanes, readProjectFile } from './store.js';
 /** `project`: the folder's project file when the caller has already read it (one read, one answer). */
 export function registerFor(projectDir, outboxDir, project = readProjectFile(projectDir)) {
     const collected = collectRecords(projectDir);
@@ -13,7 +13,7 @@ export function registerFor(projectDir, outboxDir, project = readProjectFile(pro
     // The newest discovery, when the folder holds one: the estate around the team project.
     const estate = readEstate(projectDir)?.estate;
     const register = buildRegister({
-        project, baseline, lanes, records: [...collected.records, ...own.records], ...(estate !== undefined ? { estate } : {}),
+        project: coreProject(project), baseline, lanes, records: [...collected.records, ...own.records], ...(estate !== undefined ? { estate } : {}),
     });
     return {
         register, files: collected.files + own.files,

package/dist/register/store.js

@@ -21,6 +21,19 @@ import { writeWhole } from './write-whole.js';
 export const TEAM_FILE = 'cspeach-team.json';
 export const BASELINE_FILE = path.join('baseline', 'objects.json');
 export const LANES_FILE = 'lanes.json';
+/**
+ * Team build (2026-10-25): 2 is the team build (`type: 'build'`, no baseline).
+ * Clean-core and upgrade folders stay formatVersion 1, untouched. A file
+ * newer than this is refused: it was made by a newer CSPeach.
+ */
+export const TEAM_FORMAT_VERSION = 2;
+/**
+ * register-core types a project file as formatVersion 1 and never reads the
+ * field (its sheet makes a bare one with 1). Handing it a team build file
+ * (formatVersion 2) is safe; this says so in one place instead of a cast at
+ * every call.
+ */
+export const coreProject = (p) => p;
 export class RegisterError extends Error {
 }
 export const defaultRand = (bytes) => randomBytes(bytes).toString('hex');
@@ -86,6 +99,9 @@ export function readProjectFile(projectDir) {
     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`);
     }
+    if (typeof p.formatVersion === 'number' && p.formatVersion > TEAM_FORMAT_VERSION) {
+        throw new RegisterError('This team folder was made by a newer CSPeach. Update CSPeach: cspeach --upgrade');
+    }
     return p;
 }
 /**
@@ -124,6 +140,9 @@ function readTextOrSay(file, missing) {
 }
 /** `project`: the folder's project file when the caller has already read it (one read, one answer). */
 export function readBaseline(projectDir, project = readProjectFile(projectDir)) {
+    // A team build pulls no baseline: nothing to read, and baseline/ is never touched.
+    if (project.type === 'build' && project.formatVersion === 2)
+        return [];
     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) {

package/dist/repl/builtin-commands.js

@@ -34,6 +34,7 @@ export const BUILTIN_ENTRIES = [
     { name: '/usage', get description() { return usageCommandDescription(); } },
     { name: '/compact', description: 'Shrink a long session and keep the facts (later turns cost far less)' },
     { name: '/export', description: 'Export the session audit record (/export audit [filename]) or a Word copy: of the last answer (/export docx, or /export docx <name>), of the whole conversation (/export docx conversation) or of a Markdown file (/export docx <file>.md)' },
+    { name: '/files', description: 'Pick a saved project file and what to do with it' },
     { name: '/context', description: 'Show what fills the model context window — a composition grid of bars' },
     { name: '/exit', description: 'Exit CSPeach' },
     { name: '/quit', description: 'Exit CSPeach (alias)' },
@@ -56,9 +57,9 @@ export const BUILTIN_ENTRIES = [
 ];
 /**
  * Builtin command heads for routing checks. Superset of BUILTIN_ENTRIES:
- * `/files` is a real REPL builtin (repl.tsx handles it in both paths) and
- * `/cancel` is still handled by the classic loop, but neither is listed in the
- * picker catalogue, so both are added here.
+ * `/cancel` is still handled by the classic loop but is not listed in the
+ * picker catalogue, so it is added here. (`/files` is listed since 2026-10-27;
+ * it stays here too, harmlessly.)
  */
 const BUILTIN_HEADS = new Set([
     ...BUILTIN_ENTRIES.map((e) => e.name),

package/dist/repl/file-picker.js

@@ -4,7 +4,7 @@
  * UX:
  *   1. Search-as-you-type list of files (filename + artefactType + version)
  *   2. Action menu tailored to the picked artefactType — pick one of:
- *        spec-gap → --status, --from /abap-design
+ *        spec-gap → answer the questions (viewer steps), --from /abap-design, --status
  *        design   → --status, --from /abap-estimate
  *        estimate → --status only
  *        unknown  → all --status variants
@@ -16,10 +16,15 @@
  * slash-picker.ts so cancellation in either step doesn't drop the user
  * back to the parent shell.
  */
+import path from 'node:path';
 import { search, select } from '@inquirer/prompts';
 import { withInquirer } from './inquirer-guard.js';
 import { listProjectFiles, detectDesignShape } from '../projects/workspace.js';
+import { editorLabel } from '../projects/saved-lines.js';
+import { resolveProjectFolderSync } from '../projects/project-folder.js';
 const CANCEL_VALUE = '__cspeach_cancel__';
+/** Spec gap "answer the questions" (2026-10-27): prints the viewer steps, runs nothing. */
+const ANSWER_VALUE = '__cspeach_answer__';
 /**
  * Compute the menu of valid actions for an envelope of a given
  * artefactType. Order: most-common first.
@@ -35,7 +40,8 @@ const CANCEL_VALUE = '__cspeach_cancel__';
 function envelopeActionsFor(type, designShape = 'unknown') {
     if (type === 'spec-gap') {
         return [
-            { label: '/abap-design --from         (promote → design)', command: '/abap-design --from' },
+            { label: 'Answer the questions        (open in cspeach.dev/edit)', command: ANSWER_VALUE },
+            { label: '/abap-design --from         (use the answers → design)', command: '/abap-design --from' },
             { label: '/abap-spec-gap --status     (inspect)', command: '/abap-spec-gap --status' },
         ];
     }
@@ -153,6 +159,46 @@ function textActionsFor() {
  * then dumped the full file list every time the user cancelled. This
  * tagged result removes the conflation.
  */
+/**
+ * The steps printed for "Answer the questions" (2026-10-27): a standalone
+ * customer did not know how to enter answers. The viewer's own button names
+ * (Pick folder, Save back to folder, Download updated file).
+ */
+export function answerStepsText(file, workDir = workFolder()) {
+    const full = path.resolve(file.path);
+    // A file from an earlier location is read-only: its answers go to today's folder.
+    if (file.earlier) {
+        return [
+            'To answer the questions:',
+            `  1. Open ${editorLabel()} and drop ${full} on the page.`,
+            '  2. Type each answer and mark it answered.',
+            `  3. Choose Download updated file and put that file in ${workDir}`,
+            'Then type /files and pick the new version to go on from your answers.',
+        ].join('\n');
+    }
+    const dir = path.dirname(full);
+    return [
+        'To answer the questions:',
+        `  1. Open ${editorLabel()}, choose Pick folder and pick ${dir}`,
+        `  2. Open ${file.filename}, type each answer and mark it answered.`,
+        '  3. Choose Save back to folder. It saves a new version next to this one.',
+        'Then type /files and pick the new version to go on from your answers.',
+        `No Pick folder button (it needs Edge or Chrome)? Drop ${full} on the page instead, choose Download updated file and put that file in ${dir}.`,
+    ].join('\n');
+}
+/** Picked action → result: the answer action prints steps, every other one is a command. */
+function resultFor(action, file) {
+    if (action === ANSWER_VALUE)
+        return { kind: 'info', text: answerStepsText(file) };
+    return { kind: 'command', command: `${action} @${file.filename}` };
+}
+/**
+ * This project's file folder, where saves go — not a file's folder: the list
+ * can hold files from earlier locations (marked `earlier`) after today's.
+ */
+function workFolder() {
+    return path.resolve(resolveProjectFolderSync(process.cwd()).workDir);
+}
 /** Action menu for a picked file (shared by the inquirer and Ink paths). */
 function actionsForFile(file) {
     const designShape = file.artefactType === 'design' ? detectDesignShape(file.path) : 'unknown';
@@ -185,7 +231,7 @@ export async function openFilePicker(opts = {}) {
         return await withInquirer(async () => {
             // Step 1 — pick a file.
             const fileResult = await search({
-                message: 'Pick a project file',
+                message: `Pick a project file (in ${workFolder()})`,
                 source: async (input) => {
                     const filter = (input ?? '').toLowerCase();
                     const filtered = filter.length === 0
@@ -223,7 +269,7 @@ export async function openFilePicker(opts = {}) {
             });
             if (action === CANCEL_VALUE)
                 return { kind: 'cancelled' };
-            return { kind: 'command', command: `${action} @${pickedFile.filename}` };
+            return resultFor(action, pickedFile);
         });
     }
     catch {
@@ -238,6 +284,7 @@ async function openFilePickerInk(files) {
     const picked = await withFocusClaim(() => filesCardEmitter.requestPick({
         id: 'files',
         title: 'Pick a project file',
+        folder: workFolder(),
         items: files.map((f) => ({ value: f.filename, label: f.filename, detail: `${f.artefactType} v${f.version ?? '?'}` })),
     }));
     if (picked.value == null)
@@ -257,5 +304,5 @@ async function openFilePickerInk(files) {
     }, { trace: false });
     if (res.value == null || res.value === CANCEL_VALUE)
         return { kind: 'cancelled' };
-    return { kind: 'command', command: `${res.value} @${pickedFile.filename}` };
+    return resultFor(res.value, pickedFile);
 }

package/dist/repl/mode-cycle.js

@@ -1,4 +1,5 @@
 import { clampToCeiling, modeCeiling, WRITE_MODE_ORDER, } from './mode-ceiling.js';
+import { isFunctionalSeat } from '../licence/seat-state.js';
 /**
  * Session-scoped effective write mode + cycling core (UX Wave 1, Task 2).
  *
@@ -29,14 +30,23 @@ export function getSessionWriteMode() {
 }
 /** cfgMode overlaid by session override, then clamped to the alias role's ceiling. */
 export function getEffectiveWriteMode(cfgMode, role) {
+    // Team build Task 6 — a functional seat is pinned at advisory whatever the
+    // config, the role or a session override says.
+    if (isFunctionalSeat())
+        return 'advisory-only';
     return clampToCeiling(sessionWriteMode ?? cfgMode, role);
 }
+/** Team build Task 6 — the /mode answer on a functional seat, for any argument. */
+export const SEAT_MODE_LINE = 'mode stays advisory on this seat — it reads SAP and never changes it';
 /**
  * Cycle to the next mode the role allows (wraps). Sets the session override
  * so the new mode takes effect immediately. Returns the new mode AND whether
  * the requested step was capped (for the refusal line).
  */
 export function cycleWriteMode(cfgMode, role) {
+    // Functional seat: pinned; the session override is left alone.
+    if (isFunctionalSeat())
+        return { mode: 'advisory-only', capped: true };
     const ceilingIdx = WRITE_MODE_ORDER.indexOf(modeCeiling(role));
     // Modes at or below the ceiling, in cycling order (most→least restricted).
     const allowed = WRITE_MODE_ORDER.slice(0, ceilingIdx + 1);
@@ -77,6 +87,8 @@ function refusalLine(clamped, role, alias) {
  * mode (caller pushes it into the SapStateStore so the statusline is live).
  */
 export function runModeCommand(arg, cfgMode, role, alias) {
+    if (isFunctionalSeat())
+        return { line: SEAT_MODE_LINE, mode: 'advisory-only' };
     const prev = getEffectiveWriteMode(cfgMode, role);
     const normalized = arg?.trim().toLowerCase() ?? '';
     if (normalized === '') {