@cspeach/cli 1.1.52 → 1.1.54

package/dist/agent/conversation-prompt.js

@@ -26,6 +26,7 @@ How you talk
 - Plain words, short sentences. Use headings, tables or lists only when they make the answer easier to read.
 - Have a view. If something is a bad idea, say so and say why. If you're not sure, say what you'd check.
 - When there is a next step, say what you would do in your own words. Do not end a reply with a word, phrase or command for the person to type to go on. If they ask which command does something, name it. If the next step is a workflow and they have asked for it, call hand_off now: the workflow shows its plan and asks before it writes. If it is a real choice, ask the question.
+- When there is a clear next step, end with it as one question card (next step recommended + 'Not now'). A step that only saves local files or plans runs on yes without asking again. SAP writes still show their approval card. Use ask_question for the card.
 - A playbook's report header (## [abap-x] — object, TL;DR, Headline, Top 3, Verdict, Next) goes only in a saved document and in the workflow's report after the person typed an /abap-… command. Not after your own hand_off, and not in other turns: there, answer as you would in conversation.
 - After a write, say what changed and what is next. Do not explain approvals, risk ratings or activation mechanics unless asked. If something failed or stayed inactive, say so.
 - No flattery. Apologise only when you got something wrong.

package/dist/agent/loop.js

@@ -1,7 +1,9 @@
 import chalk from 'chalk';
-import { basename } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { dispatchTool } from './tool-dispatch.js';
 import { listTools, getTool, isStandalone, toolsForContext, toAnthropicTools } from '../tools/index.js';
+import { toolsForSeat } from '../tools/seat-gate.js';
+import { getSeatKind } from '../licence/seat-state.js';
 import { saveSession } from '../session/store.js';
 import { tagSessionOnSave } from '../session/project-match.js';
 import { recordCompletedToolCall } from '../session/pending.js';
@@ -9,7 +11,7 @@ import { loadConfig } from '../config/loader.js';
 import { resolveModelRole, resolveEffort, modelAcceptsEffort, resolveAutoCompactThreshold, callModelFor } from '../models/resolve.js';
 import { getCustomerModelConfig, managedProxyServesNewShapes, servedToolLoading } from '../models/server-config.js';
 import { familyOf, familyAcceptsEffort } from '../models/model-identity.js';
-import { buildToolList, buildSkillToolAddition, placeSystemMessagesInPlace, resolveToolLoading, } from '../tools/tool-loading.js';
+import { buildToolList, buildSkillToolAddition, buildToolAdditionMessage, deferredNames, surfacedToolNames, placeSystemMessagesInPlace, resolveToolLoading, } from '../tools/tool-loading.js';
 import { settleSessionToolLoading } from './tool-loading-pin.js';
 import { resolveSkillAlias } from '../skill-catalog.js';
 import { retryWithBackoff } from './retry.js';
@@ -46,6 +48,7 @@ import { enrichUserMessage } from '../router/intent-extractor.js';
 import { resetRule8State, shouldGateRule8 } from '../repl/rule8-detector.js';
 import { consumeTodoSetThisTurn } from '../ui/todo-emitter.js';
 import { runSaveCommand, runPromoteCommand, detectArtifactSkill, offerAnswerBlockers } from '../projects/index.js';
+import { blockerAnswersNote, SPEC_ANSWERS_RECORD_TOOL } from '../projects/blocker-answers-note.js';
 import { planLaneBlockForTurn } from '../projects/plan-lane.js';
 import { DOCUMENT_SKILLS, WORD_AFTER_ARTIFACT_SAVE } from '../projects/document-skills.js';
 import { metaFromMarkdown } from '../docx/doc-meta.js';
@@ -70,7 +73,7 @@ import { renderStandaloneContextBlock } from '../sap/standalone-profile.js';
 import { renderStandardsBlock } from '../standards/standards-file.js';
 import { composeSessionContextBlock } from './session-context.js';
 import { objectKeyFromInput } from './retry-key.js';
-import { repairPartialBlocks, stripPreFallbackBlocks, healSessionMessagesInPlace, healOrphanToolUses, isPartialJsonApiError, stripUnsignedThinking, isThinkingOnly, dropTrailingThinkingOnly } from './repair-partial.js';
+import { repairPartialBlocks, stripPreFallbackBlocks, healSessionMessagesInPlace, healOrphanToolUses, isPartialJsonApiError, stripUnsignedThinking, isThinkingOnly, dropTrailingThinkingOnly, closedOffStepsLine } from './repair-partial.js';
 import { drainSteeringEntries, enqueueSteering } from './steering-queue.js';
 import { steeringReadLine } from '../renderer/steering-echo.js';
 import { TurnStreamWriter } from './turn-stream.js';
@@ -432,6 +435,19 @@ function localToday() {
  * package) loads only here, inside the catch: a broken docx install costs
  * one line after the save and never the save itself.
  */
+/** A spec gap saved into a team build's shared specs/ folder (merge of main into feat/team-build). */
+async function isSharedSpecSave(cwd, saveSkill, savedPath) {
+    if (saveSkill !== 'abap-spec-gap')
+        return false;
+    try {
+        const { sharedSpecTargetFor, isSharedSpecPath } = await import('../projects/spec-share.js');
+        const shared = sharedSpecTargetFor(cwd, 'spec-gap');
+        return !!shared && isSharedSpecPath(shared.teamDir, savedPath);
+    }
+    catch {
+        return false;
+    }
+}
 async function offerWordAfterArtifactSave(p, saveSkill, savedPath, confirm) {
     try {
         const { offerWordCopyAfterArtifactSave } = await import('../projects/document-save.js');
@@ -448,9 +464,51 @@ async function offerWordAfterArtifactSave(p, saveSkill, savedPath, confirm) {
         p.emit(formatInfo(`Word copy not written: ${e.message}`).trimEnd());
     }
 }
+/**
+ * Change options (2026-10-23) — an answer carrying the change-options marker
+ * pair gets its marked part saved (every complete pair, in order: a level
+ * picked in session adds the decided document), whatever the skill and even when the turn
+ * ends on the level question. Never on a sub-agent turn or inside a guided
+ * flow. Returns true when the marker check handled the turn (the question was
+ * asked or the document saved), so maybeOfferSave runs nothing else. An answer
+ * with no complete marker pair returns false and takes today's path unchanged.
+ */
+async function maybeOfferChangeOptions(p, confirm) {
+    if (p.subagent || p.guided || p.assistantText.includes('<!-- guided-run:'))
+        return false;
+    if (!p.assistantText.includes('csforge:change-options'))
+        return false;
+    const { extractChangeOptions } = await import('../projects/change-options.js');
+    // Every complete pair, in order: a level picked in session shows the
+    // document again with the decision, and that one is saved too (last).
+    const docs = extractChangeOptions(p.assistantText).filter((d) => d.markdown.trim().length > 0);
+    if (docs.length === 0)
+        return false;
+    // Set before the save question, so a declined save still routes the level reply.
+    if (p.session && !p.subagent)
+        p.session.lastChangeOptions = { object: docs[docs.length - 1].object, skill: p.skill };
+    try {
+        const { offerChangeOptionsSave } = await import('../projects/document-save.js');
+        const { loadConfig, resolveWordCopy } = await import('../config/loader.js');
+        await offerChangeOptionsSave({
+            docs: docs.map((d) => ({ object: d.object, markdown: d.markdown })), cwd: process.cwd(), today: localToday(),
+            sapSystem: p.sapSystem ?? null,
+            ...(p.sessionId ? { sessionId: p.sessionId } : {}),
+            ...(p.operator ? { operator: p.operator } : {}),
+            headless: isHeadless(), wordCopy: resolveWordCopy(await loadConfig()), confirm, emit: p.emit,
+        });
+    }
+    catch (e) {
+        p.emit(formatInfo(`Not saved. ${e.message}`).trimEnd());
+    }
+    return true;
+}
 export async function maybeOfferSave(p) {
     if (p.assistantText.trim().length === 0)
         return;
+    // Change options (2026-10-23): the marker check runs first, for every skill.
+    if (await maybeOfferChangeOptions(p, p.confirm ?? inkAwareConfirm))
+        return;
     // Word export (2026-10-19): reviews and handovers are prose documents, not
     // envelopes. They get a Markdown save under cspeach-out and the Word
     // question (projects/document-save.ts). Nothing below this branch changes
@@ -547,7 +605,7 @@ export async function maybeOfferSave(p) {
             tokensUsed: p.tokensUsed,
             model: p.model,
             author: getAuthorIdentity(),
-            cwd: process.cwd(),
+            cwd: p.cwd ?? process.cwd(),
             prompt,
             // Piece 2 / Q3 — interactive saves ask a Yes/No card; headless passes
             // no confirm so the blanket-'y' prompt above still answers (B5 contract).
@@ -562,6 +620,7 @@ export async function maybeOfferSave(p) {
             ...(p.latestSkeleton && p.skill === saveSkill ? { latestSkeleton: p.latestSkeleton } : {}),
             onNotSaved: (reason) => { notSaved = reason; },
             ...(p.onProjectId ? { onProjectId: p.onProjectId } : {}),
+            ...(p.sapSystem ? { sapSystem: p.sapSystem } : {}),
             // Never headless: a headless journey queues nothing.
             ...(p.journey && !isHeadless() && p.skill === saveSkill ? { journey: p.journey } : {}),
         });
@@ -569,7 +628,9 @@ export async function maybeOfferSave(p) {
         // is a document (spec gaps, design, estimate, plan, upgrade scan/report)
         // gets the same Word step as a review: `word_copy` decides, headless
         // never asks. The project file itself is untouched. Sub-agent turns: no.
-        if (savedPath && !p.subagent && WORD_AFTER_ARTIFACT_SAVE[saveSkill]) {
+        // A team build shared spec already has its Word copy beside it (save-command.ts).
+        if (savedPath && !p.subagent && WORD_AFTER_ARTIFACT_SAVE[saveSkill]
+            && !(await isSharedSpecSave(p.cwd ?? process.cwd(), saveSkill, savedPath))) {
             await offerWordAfterArtifactSave(p, saveSkill, savedPath, confirm);
         }
         // After a spec-gap file is saved, let a developer answer the open BLOCKER
@@ -577,7 +638,31 @@ export async function maybeOfferSave(p) {
         // business questions stay open for a consultant to answer in the viewer.
         // Uses inkAwarePrompt directly (NOT the save hook's blanket-'y' headless
         // prompt): in headless it returns '' → declined, so nothing is written.
+        // Task 16 (F-M): what the form recorded reaches the model as one note on
+        // its next call (session.blockerAnswersNote, sent by runTurn). Main turns
+        // with a session only; declined / not offered / not saved → no note.
         if (savedPath && saveSkill === 'abap-spec-gap') {
+            // Team build (Task 9): a spec in the shared specs/ folder is never
+            // rewritten — each answer is a record of its own, and the spec is read
+            // with the records applied. Found by the folder (R10), never activeProject().
+            const { sharedSpecTargetFor, isSharedSpecPath, composeSpec, readAnswers, writeAnswerRecord, specAuthorFor } = await import('../projects/spec-share.js');
+            const { readProjectFile } = await import('../projects/status.js');
+            const shared = sharedSpecTargetFor(p.cwd ?? process.cwd(), 'spec-gap');
+            const records = shared && isSharedSpecPath(shared.teamDir, savedPath)
+                ? {
+                    // R11: only the answers recorded for this envelope.
+                    readEnvelope: (path) => composeSpec(readProjectFile(path), readAnswers(dirname(path)).filter((a) => a.file === basename(path))),
+                    recordAnswer: (a) => {
+                        const specDir = dirname(savedPath);
+                        writeAnswerRecord(specDir, {
+                            projectId: shared.projectId, slug: basename(specDir), file: basename(savedPath),
+                            gapId: a.gapId, answer: a.answer, by: specAuthorFor(shared.projectId, a.identity.name), at: a.at,
+                        });
+                    },
+                }
+                : {};
+            const noteSession = p.session && !p.subagent ? p.session : undefined;
+            let outcomes;
             await offerAnswerBlockers({
                 path: savedPath,
                 identity: getAuthorIdentity(),
@@ -585,7 +670,18 @@ export async function maybeOfferSave(p) {
                 confirm: inkAwareConfirm,
                 choose: inkAwareChoose,
                 log: (...lines) => lines.forEach((l) => p.emit(l)),
+                ...records,
+                ...(noteSession ? { onOutcomes: (o) => { outcomes = o; } } : {}),
             });
+            if (noteSession && outcomes) {
+                // The path is shown against the read tool's base (ctx.cwd), so the model opens it with file_read.
+                const note = blockerAnswersNote({
+                    path: savedPath, cwd: p.readCwd ?? process.cwd(), outcomes,
+                    ...('readEnvelope' in records ? { readEnvelope: records.readEnvelope } : {}),
+                });
+                if (note)
+                    noteSession.blockerAnswersNote = note;
+            }
         }
         // App lane routing (Task 7) — the harness-owned /abap-app chain. Built
         // from the exact saved path, never from model text. Outside an app flow
@@ -1068,7 +1164,12 @@ ${imageExpansion.error}`));
     if (mainTurn && !inlineTurn && historyHoldsInline(session.messages)) {
         playbookLine = isChatSkill(params.skill) ? playbookLineSystemChat() : playbookLineSystem(params.skill);
     }
-    const sessionContextBlock = composeSessionContextBlock([sapSystemBlock, sapProfileBlock, standardsBlock, switchNote, playbookLine]);
+    // Task 16 (F-M) — what the blocker form recorded after the last turn: once,
+    // on the next main turn (never a sub-agent or reader child), then dropped.
+    const blockerNote = mainTurn && session.blockerAnswersNote
+        ? `<blocker_answers>\n${session.blockerAnswersNote}\n</blocker_answers>`
+        : '';
+    const sessionContextBlock = composeSessionContextBlock([sapSystemBlock, sapProfileBlock, standardsBlock, switchNote, blockerNote, playbookLine]);
     // Deterministically extract structured facts from the user's prompt
     // (package, transport, object names, environment hint, create intent)
     // and prepend them as an XML `<session_context>` block. The model reads
@@ -1084,11 +1185,12 @@ ${imageExpansion.error}`));
     // Final batch 1 — a caller-enriched message still gets the switch note,
     // inside its own <session_context> block.
     // Stage 1A — the <playbook> line rides the same way ('' ⇒ unchanged).
-    const callerNotes = composeSessionContextBlock([switchNote, playbookLine]);
+    const callerNotes = composeSessionContextBlock([switchNote, blockerNote, playbookLine]);
     const enriched = userMessageForLLM.startsWith('<session_context>')
         ? (callerNotes ? userMessageForLLM.replace('<session_context>', `<session_context>\n  ${callerNotes}`) : userMessageForLLM)
         : enrichUserMessage(userMessageForLLM, sessionContextBlock);
     const switchNoteUsed = switchNote !== '' && enriched.includes(switchNote);
+    const blockerNoteUsed = blockerNote !== '' && enriched.includes(blockerNote);
     // Phase 2 of Track B — opt-in project-context enrichment, gated by
     // CSPEACH_PROJECT_CONTEXT=on. Default OFF: production behavior is
     // identical to today. When on, the rendered <project_context> block
@@ -1116,6 +1218,7 @@ ${imageExpansion.error}`));
         projectContextBlock = await maybeBuildProjectContext({
             cwd: params.ctx.cwd,
             sapConnection,
+            emit: (line) => emit(chalk.dim(line)),
         });
     }
     const contextualContent = projectContextBlock
@@ -1137,6 +1240,9 @@ ${imageExpansion.error}`));
         lane: session.lane,
         tool_set_skill: session.tool_set_skill,
         turn_seq: session.turn_seq,
+        // Task 16 fix round 1 (I-1, R17): the one-time notes this turn consumes.
+        systemSwitchNote: session.systemSwitchNote,
+        blockerAnswersNote: session.blockerAnswersNote,
     };
     let round0Steers = [];
     // Images (if any) ride as blocks ahead of the text; with none this is the
@@ -1152,6 +1258,8 @@ ${imageExpansion.error}`));
     // it is in a pushed user message.
     if (switchNoteUsed)
         delete session.systemSwitchNote;
+    if (blockerNoteUsed)
+        delete session.blockerAnswersNote;
     if (imageExpansion.images.length > 0 && params.provider.name === 'local-openai-compat') {
         // The local (OpenAI-compatible) provider keeps text blocks only.
         emit(chalk.dim('(local model: the image is not sent — the model gets the text only)'));
@@ -1193,12 +1301,19 @@ ${imageExpansion.error}`));
     const hiddenSapTools = connectedTurn
         ? pinHiddenTools(session, params.ctx.sapAlias, listTools(), params.ctx.systemProfile ?? null)
         : [];
-    const contextTools = withoutTools(toolsForContext(listTools(), params.ctx), hiddenSapTools);
+    // Team build Task 6 — a functional seat is not offered the tools it may not
+    // call (dispatch refuses them anyway). Developers: the same array.
+    const contextTools = toolsForSeat(withoutTools(toolsForContext(listTools(), params.ctx), hiddenSapTools), getSeatKind());
     // Task 18 fixes M4 / M5 — no read_agent for an agent_run child, and none
     // when a reader would have no real read tool (standalone, file tools off).
-    const visibleTools = params.ctx.subagent || !hasReaderReadTools(new Set(contextTools.map((t) => t.name)))
+    const readerVisible = params.ctx.subagent || !hasReaderReadTools(new Set(contextTools.map((t) => t.name)))
         ? contextTools.filter((t) => t.name !== READ_AGENT)
         : contextTools;
+    // Task 18 fix round 1 (item 5) — an agent_run child never records spec
+    // answers: it could race the blocker form on the same file.
+    const visibleTools = params.ctx.subagent
+        ? readerVisible.filter((t) => t.name !== SPEC_ANSWERS_RECORD_TOOL)
+        : readerVisible;
     // Final review C1 (controller ruling) — deferred shapes only for a model on
     // the probe-proven allow-list, decided by the model actually sent on the
     // call (a plan-tier sonnet override, a haiku child or claude-opus-4-8 ⇒
@@ -1254,13 +1369,7 @@ ${imageExpansion.error}`));
     // Stage 1A — skill_appended goes on the turn's first cost line (a call
     // retried after a prompt-too-long recovery logs no line of its own).
     let skillAppendedLogged = false;
-    const surfaceStarters = (skill) => {
-        const msg = buildSkillToolAddition({
-            skill,
-            toolLoading: session.tool_loading,
-            toolList: turnTools,
-            messages: session.messages,
-        });
+    const pushToolAddition = (msg) => {
         if (msg)
             session.messages.push(msg);
         if (msg && inlineTurn) {
@@ -1270,10 +1379,24 @@ ${imageExpansion.error}`));
             }
         }
     };
+    const surfaceStarters = (skill) => {
+        pushToolAddition(buildSkillToolAddition({
+            skill,
+            toolLoading: session.tool_loading,
+            toolList: turnTools,
+            messages: session.messages,
+        }));
+    };
     // A turn on a different skill than the one the array was built for: the
     // user message was just pushed, so the system message follows it.
     if (params.skill !== session.tool_set_skill)
         surfaceStarters(params.skill);
+    // Task 18 fix round 1 (item 7) — the blocker note names spec_answers_record:
+    // on the turn that carries it, surface the tool when this list defers it
+    // (loaded already, static, or surfaced before: nothing is added).
+    if (blockerNoteUsed && session.tool_loading !== 'static' && !surfacedToolNames(session.messages).has(SPEC_ANSWERS_RECORD_TOOL)) {
+        pushToolAddition(buildToolAdditionMessage([SPEC_ANSWERS_RECORD_TOOL], deferredNames(turnTools)));
+    }
     /**
      * key: `${tool_name}:${object}` — consecutive failures per (tool, target).
      * For object-identifying tools (sap_set_source / sap_activate / etc.) the
@@ -1446,6 +1569,11 @@ ${imageExpansion.error}`));
             session.lane = preTurnState.lane;
             session.tool_set_skill = preTurnState.tool_set_skill;
             session.turn_seq = preTurnState.turn_seq;
+            // The re-run turn still gets the one-time notes (they were dropped on push).
+            if (preTurnState.systemSwitchNote !== undefined)
+                session.systemSwitchNote = preTurnState.systemSwitchNote;
+            if (preTurnState.blockerAnswersNote !== undefined)
+                session.blockerAnswersNote = preTurnState.blockerAnswersNote;
             // Steering drained in round 0 goes back to the queue, ahead of any
             // typed since, so the re-run turn still sees it.
             // LT-15 Task 4 — the round-0 ones were shown as "↳ read": marked, so the
@@ -1551,7 +1679,7 @@ ${imageExpansion.error}`));
                 // that ended before the model answered the tool_addition.
                 placeSystemMessagesInPlace(session.messages);
                 if (healedOrphans > 0) {
-                    emit(chalk.dim(`(repaired ${healedOrphans} tool call(s) cut off by an interruption — the model will redo them)`));
+                    emit(chalk.dim(closedOffStepsLine(healedOrphans)));
                 }
                 // Task 4 — effort only from an explicit act (ruling F2); never to a
                 // model that rejects it (probe P1: claude-haiku-4-5* ⇒ 400).
@@ -2281,10 +2409,15 @@ ${imageExpansion.error}`));
                         model: params.modelOverride ?? resolveModelRole('session_default', cfg) ?? session.model ?? 'unknown',
                         emit,
                         sapSystem: session.sap_system,
+                        // Final review F6: the save and the team build folder follow this turn's folder.
+                        cwd: params.ctx.cwd,
+                        ...(params.operator ? { operator: params.operator } : {}),
+                        sessionId: session.id,
                         ...(params.ctx.subagent ? { subagent: true } : {}),
                         ...(session.awaitingSkillAnswer === true ? { awaitingAnswer: true } : {}),
                         ...(getJourneyFlow(session) || getAppFlow(session) ? { guided: true } : {}),
                         session,
+                        readCwd: params.ctx.cwd,
                         promotedFrom: promotedFromForSave,
                         ...(promotedFromPathForSave ? { promotedFromPath: promotedFromPathForSave } : {}),
                         ...(() => {

package/dist/agent/maybe-build-project-context.js

@@ -30,7 +30,7 @@
  *    Phase 3. Today the cache is process-lifetime; users get a fresh
  *    context next CLI invocation.
  */
-import { getProjectContext, renderProjectContext } from '../project-context/index.js';
+import { getProjectContext, renderProjectContextCapped } from '../project-context/index.js';
 /**
  * The env-var name that gates this enrichment. Treated case-insensitively
  * but value comparison is exact ("on" only — anything else is OFF).
@@ -70,6 +70,8 @@ export function resetProjectContextCache() {
 export function __resetProjectContextCacheForTests() {
     resetProjectContextCache();
 }
+/** The one plain line shown when the folder picture was shortened. */
+export const PROJECT_CONTEXT_CUT_LINE = 'This folder is very large, so we work from a shortened picture of it.';
 /**
  * Returns the rendered <project_context> block for splicing into the
  * user message, or '' when the flag is off / no context was detectable.
@@ -94,7 +96,14 @@ export async function maybeBuildProjectContext(options) {
         const ctx = await getProjectContext(options.cwd, {
             sapConnection: options.sapConnection ?? null,
         });
-        cachedBlock = ctx ? renderProjectContext(ctx) : '';
+        const rendered = ctx ? renderProjectContextCapped(ctx) : { block: '', cut: false };
+        cachedBlock = rendered.block;
+        if (rendered.cut) {
+            try {
+                options.emit?.(PROJECT_CONTEXT_CUT_LINE);
+            }
+            catch { /* a display failure never drops the block */ }
+        }
     }
     catch (err) {
         // getProjectContext is documented as never-throws; reaching this

package/dist/agent/repair-partial.js

@@ -210,6 +210,15 @@ export const INTERRUPTED_TOOL_RESULT = 'This tool call did not complete — the
  * SAP change. Same shape and flags as INTERRUPTED_TOOL_RESULT (is_error: true).
  */
 export const STOPPED_BEFORE_START_RESULT = 'This tool call was stopped before anything ran — no change was made in SAP. Ask again if it is still needed.';
+/**
+ * 1.1.53 item 10 — the dim line shown when healOrphanToolUses closed off steps
+ * cut by an earlier stop. Plain words for the person; no internals.
+ */
+export function closedOffStepsLine(n) {
+    return n === 1
+        ? '(we closed off a step that was stopped earlier)'
+        : `(we closed off ${n} steps that were stopped earlier)`;
+}
 /**
  * LT-15 D6 (review M5) — the same, for the write pipeline's second guard: by
  * then the approval was spent and SAP was read (a local snapshot may exist),

package/dist/agent/tool-dispatch.js

@@ -12,6 +12,8 @@ import { riskOf } from './risk-gate.js';
 import { NOT_ON_THIS_RELEASE, gateWithVerify } from '../sap/profile-gate.js';
 import { INTERRUPTED_TOOL_RESULT, STOPPED_BEFORE_START_RESULT } from './repair-partial.js';
 import { WRITE_TOOLS } from '../tools/write-mode.js';
+import { seatRefusal } from '../tools/seat-gate.js';
+import { getSeatKind } from '../licence/seat-state.js';
 const READER_TOOL_SET = new Set(READER_TOOLS);
 /** Chat lane (spec 2026-10-17 D4) — the model-facing reason; names hand_off. */
 export const CHAT_READ_ONLY_REASON = 'This chat reads but never changes SAP. To make this change, call hand_off with the right workflow (for example abap-refactor, abap-generate, abap-transport) and a clear request — the workflow shows its plan and asks before it writes.';
@@ -70,6 +72,15 @@ export async function dispatchTool(name, args, ctx) {
     if (ctx.readerMode && !READER_TOOL_SET.has(name)) {
         return { content: `error: read-only reader — ${name} is not allowed here`, is_error: true };
     }
+    // Team build Task 6 — a functional seat reads SAP and never changes it, in
+    // every lane (skill, chat, and an agent_run child, which shares the process
+    // seat) whatever write_mode, role or /mode says. The refused tools are not
+    // offered (agent/loop.ts toolsForSeat); THIS is the guarantee for a call the
+    // model makes anyway. Before the chat gate and every card below. Developers:
+    // seatRefusal is null, so today's dispatch is untouched.
+    const seat = seatRefusal(getSeatKind(), tool, args);
+    if (seat)
+        return { content: JSON.stringify({ error: 'seat_read_only', tool: name, message: seat }), is_error: true };
     // Chat lane (spec 2026-10-17 D4, §6.3) — chat reads freely and never changes
     // SAP. The prompt says so; THIS is the guarantee: every SAP-mutating tool and
     // request_approval are refused while the session's last turn ran in chat,
@@ -113,8 +124,12 @@ export async function dispatchTool(name, args, ctx) {
     }
     // Final review I-3 — the D11 re-check can take seconds of SAP reads; an Esc
     // in that window must stop the call here, not let the handler run "as unknown".
-    if (ctx.signal?.aborted)
-        return { content: INTERRUPTED_TOOL_RESULT, is_error: true };
+    // 1.1.53 item 10 — the handler has not run (the gate only reads). A tool
+    // that cannot change SAP (hand_off, reads, local files) says so plainly; a
+    // tool that can change SAP keeps the "effect unknown, check" safety text.
+    if (ctx.signal?.aborted) {
+        return { content: isChatRefusedTool(tool) ? INTERRUPTED_TOOL_RESULT : STOPPED_BEFORE_START_RESULT, is_error: true };
+    }
     // L1-6 R1-6 (owner decision 2026-09-21) — a call that hands the stored SAP
     // login to a local child process ALWAYS asks a human, once per session per
     // alias, even as the first mutating call of a turn (where Rule 8 below stays

package/dist/approvals/op-labels.js

@@ -3,6 +3,7 @@ import { sanitizeControlChars } from '../renderer/sanitize.js';
 import { wrapRows } from '../renderer/wrap-rows.js';
 import { shownUpTo } from '../register/atc-file.js';
 import { transportForWrite } from '../register/project-transport.js';
+import { decodeDisplayEntities, decodeDisplayBlock } from '../renderer/html-entities.js';
 /**
  * Human-readable operation + object labels for the approval surfaces.
  *
@@ -103,7 +104,7 @@ export function affectsLine(change) {
     // line comes from the change's op and type, never from a model-supplied field.
     if (change.op === 'delete' && typeCode(change.type) === 'FUGR')
         return FUGR_DELETE_LINE;
-    const t = sanitizeControlChars(String(change.affects ?? '')).trim();
+    const t = decodeDisplayEntities(sanitizeControlChars(String(change.affects ?? ''))).trim();
     return t ? `Affects: ${t}` : null;
 }
 /** Task 7 — the longest behaviour text a card shows, and the most rows it takes. */
@@ -121,7 +122,8 @@ export function behaviourText(change) {
     // shownUpTo drops whole escape sequences first (a lone sanitizeControlChars
     // pass would leave their '[31m' tails), then every control character.
     // The cut counts code points, so it never leaves half a surrogate pair.
-    const flat = Array.from(shownUpTo(String(change.behaviour ?? ''), Number.POSITIVE_INFINITY));
+    // 1.1.53 item 5: entities decode before the cut, so the cut counts what shows.
+    const flat = Array.from(decodeDisplayEntities(shownUpTo(String(change.behaviour ?? ''), Number.POSITIVE_INFINITY)));
     const t = flat.length > BEHAVIOUR_MAX ? `${flat.slice(0, BEHAVIOUR_MAX).join('')}…` : flat.join('');
     if (!t || NOTHING_CHANGES.test(t))
         return null;
@@ -209,7 +211,8 @@ export function displayTransport(op, explicit, session, owning, project) {
  * modal's [v] view and the classic prompt's View source branch.
  */
 export function toSourceLines(content) {
-    return content
+    // 1.1.53 item 5: display decode of the whole block (kept as written when it has a raw field symbol or markup).
+    return decodeDisplayBlock(content)
         .split('\n')
         .filter((l) => !l.startsWith('@@') && !l.startsWith('+++') && !l.startsWith('---'))
         .map((l) => l.replace(/^[+-] ?/, ''));

package/dist/approvals/render.js

@@ -14,6 +14,7 @@ import { paint } from '../renderer/theme.js';
 import { sanitizeControlChars } from '../renderer/sanitize.js';
 import { planRows, looksLikeUnifiedDiff } from './visible-changes.js';
 import { withSpinnerSuspended } from '../renderer/tool-widget.js';
+import { decodeDisplayEntities, decodeDisplayBlock } from '../renderer/html-entities.js';
 // Piece 2 §1.1 — the brand accent comes from the theme role, not a legacy hex.
 const peach = (s) => paint('brand', s);
 /**
@@ -294,11 +295,11 @@ export async function renderPerChangeApproval(change, effectiveRisk, transport)
     // proper diff content.
     if (change.diff) {
         if (looksLikeUnifiedDiff(change.diff)) {
-            console.log('\n' + colorizeDiff(change.diff) + '\n');
+            console.log('\n' + colorizeDiff(decodeDisplayBlock(change.diff)) + '\n');
         }
         else {
             console.log('\n' + chalk.yellow(`${getGlyphs().attention}  Model did not provide a unified diff — only a description:`));
-            console.log(chalk.dim(change.diff) + '\n');
+            console.log(chalk.dim(decodeDisplayEntities(change.diff)) + '\n');
         }
     }
     else {

package/dist/auth/auth-file.js

@@ -40,6 +40,8 @@ export async function readAuthFile() {
             out.apiKey = parsed.apiKey;
         if (typeof parsed.savedAt === 'string')
             out.savedAt = parsed.savedAt;
+        if (typeof parsed.signedInWith === 'string')
+            out.signedInWith = parsed.signedInWith;
         return out;
     }
     catch {
@@ -54,6 +56,7 @@ export async function writeAuthFile(auth) {
         ...(auth.apiKey !== undefined ? { apiKey: auth.apiKey } : {}),
         customerId: auth.customerId,
         ...(auth.savedAt !== undefined ? { savedAt: auth.savedAt } : {}),
+        ...(auth.signedInWith !== undefined ? { signedInWith: auth.signedInWith } : {}),
     };
     await writeAtomic0600(p, JSON.stringify(body, null, 2));
 }

package/dist/auth/key-resolver.js

@@ -27,6 +27,7 @@ import { promises as fs } from 'node:fs';
 import { cspeachRoot, defaultCspeachRoot } from '../config/paths.js';
 import { readAuthFile, writeAuthFile, deleteAuthFile, authFileMtimeMs, authFileDir } from './auth-file.js';
 import { licenceCachePath } from '../licence/paths.js';
+import { CLI_VERSION } from '../lib/version.js';
 export const KEYCHAIN_SERVICE = 'cspeach';
 export const DEFAULT_ACCOUNT = 'api-key';
 async function defaultIo() {
@@ -181,7 +182,8 @@ export async function migrateSignIn(deps = {}) {
         return auth?.apiKey ? 'store-unavailable' : 'none';
     }
     try {
-        await writeAuthFile({ customerId: auth.customerId, ...(auth.savedAt ? { savedAt: auth.savedAt } : {}) });
+        // Team build: signedInWith stays, so a new sign-in never turns "legacy".
+        await writeAuthFile({ customerId: auth.customerId, ...(auth.savedAt ? { savedAt: auth.savedAt } : {}), ...(auth.signedInWith !== undefined ? { signedInWith: auth.signedInWith } : {}) });
     }
     catch {
         return 'failed'; // the store holds the key; the next start removes the copy ('removed')
@@ -217,12 +219,15 @@ export async function saveSignIn(a, deps = {}) {
     catch {
         stored = false;
     }
+    // Team build: signedInWith marks a sign-in made by this CLI or newer; an
+    // auth.json without it is a pre-release sign-in (a developer seat).
+    const signedInWith = CLI_VERSION;
     if (!stored) {
-        await writeAuthFile({ apiKey: a.apiKey, customerId: a.customerId, savedAt });
+        await writeAuthFile({ apiKey: a.apiKey, customerId: a.customerId, savedAt, signedInWith });
         return 'file';
     }
     await recordStoreWrite(account, savedAt).catch(() => { }); // bookkeeping only, no secret
-    await writeAuthFile({ customerId: a.customerId, savedAt });
+    await writeAuthFile({ customerId: a.customerId, savedAt, signedInWith });
     return 'store';
 }
 /**

package/dist/auth/me.js

@@ -2,6 +2,7 @@
  * Fetch /v1/me — customer profile + entitlements + usage.
  * Result envelope so the REPL doesn't need try/catch.
  */
+import { CLI_VERSION } from '../lib/version.js';
 /** Default /v1/me budget. The panels brand line waits for this call (D5), so a
  *  hung proxy must not mean a blank screen. */
 export const FETCH_ME_TIMEOUT_MS = 5000;
@@ -18,8 +19,11 @@ export async function fetchMe(opts) {
     try {
         return await Promise.race([
             (async () => {
-                // No extra headers → exactly `{ Authorization }`, as before the batch.
-                const r = await fetch(url, { headers: { ...(opts.headers ?? {}), Authorization: `Bearer ${opts.apiKey}` }, signal });
+                // No extra headers → exactly `{ User-Agent, Authorization }`. Team build
+                // (R5): every /v1/me call names this CLI, so the proxy can tell a
+                // current CLI from one too old for a functional seat. Set after the
+                // caller's headers, so no caller can drop it.
+                const r = await fetch(url, { headers: { ...(opts.headers ?? {}), 'User-Agent': `cspeach/${CLI_VERSION}`, Authorization: `Bearer ${opts.apiKey}` }, signal });
                 const serverDate = r.headers.get('date');
                 if (!r.ok) {
                     const body = await r.json().catch(() => ({}));

package/dist/cli.js

@@ -52,6 +52,13 @@ export async function main(argv) {
         printHelp();
         return 0;
     }
+    // Team build (Task 12): `cspeach help team-build` prints the how-to. Above the
+    // one-shot fallback, so the words are never sent to the model as a prompt.
+    if (args[0] === 'help' && args[1] === 'team-build' && args.length === 2) {
+        const { printTeamBuildHelp } = await import('./commands/team-build-help.js');
+        printTeamBuildHelp();
+        return 0;
+    }
     if (args[0] === '--version') {
         console.log(CLI_VERSION);
         return 0;
@@ -248,6 +255,14 @@ export async function main(argv) {
                 const { input } = await import('@inquirer/prompts');
                 return input({ message: question });
             },
+            // Team build (ruling R2, final review F2): the terminal verbs run no
+            // start-up, so the seat is resolved here — the verified record, else one
+            // /v1/me when there is none, else the offline rule. Asked only before a
+            // verb that records work.
+            seat: async () => {
+                const { resolveTerminalSeatNow } = await import('./licence/terminal-seat.js');
+                return resolveTerminalSeatNow();
+            },
         });
     }
     // CAP phase 2 — run the SAP link in the foreground for a local CAP app.
@@ -256,6 +271,11 @@ export async function main(argv) {
         return runSapLinkCommand(args.slice(2), {
             print: (s) => console.log(s),
             defaultAlias: sapAlias,
+            // Final review F3: resolved as the team verbs do; a functional seat's link reads and never writes.
+            seat: async () => {
+                const { resolveTerminalSeatNow } = await import('./licence/terminal-seat.js');
+                return resolveTerminalSeatNow();
+            },
             standalone: async () => {
                 const { loadConfig, resolveStandalone } = await import('./config/loader.js');
                 return resolveStandalone(await loadConfig(), noSap);
@@ -334,10 +354,12 @@ Usage:
   cspeach login azure               Sign in to Microsoft for your company's Azure (--device-code: use a code instead of the browser)
   cspeach logout                    Sign out (removes the CSPeach key from this home)
   cspeach whoami                    Print current account info
+  cspeach help team-build            How two people share one folder: the functional writes the spec, the developer builds it
   cspeach team discover            Read the whole estate from SAP into this folder (read only)
   cspeach team start <packages>     Start a team project in this folder: object list, first check, you own it all
   cspeach team start --for "FI and SD" --developers "James Miller, me"   Lead: set up by name from this folder's discovery; one lane each
   cspeach team init <folder>        Lead: pull the object list from SAP, start a team project
+  cspeach team spec list|ready [<slug>]   Team build: the specs in this folder; mark one ready for the developer
   cspeach team join <folder> [--as "<name>"]   Record your results against a team project (on this laptop only), under the lane owner's name
   cspeach team lane add|list        Lead: who owns which packages
   cspeach team lane move --packages <names> --to <developer>   Lead: move packages by name (lanes of names only)