@cspeach/cli 1.1.31 → 1.1.33

package/dist/journey/flow.js

@@ -94,6 +94,12 @@ export function setJourneyQueued(session, step) {
         f.queued = { ...step };
     else
         delete f.queued;
+    // The step the chain is at is now this object's (ruling on follow-up a).
+    if (step)
+        lastAt.set(session, { stage: step.stage, ...(step.key ? { key: step.key } : {}) });
+    // Review M2: a step queued is a step the chain got through: the stop count starts over.
+    if (step)
+        stops.delete(session);
 }
 /** End the journey: the flow goes, the guarded run ends; skips stay for the session. */
 export function clearJourneyFlow(session) {
@@ -113,6 +119,43 @@ export function pauseJourneyFlow(session, offset = 0) {
     paused.set(session, userTurnCount(session) + offset);
 }
 export const isJourneyPaused = (session) => !!session && paused.has(session);
+/**
+ * The stage the chain last reached (set each round by `drive`). Kept for the
+ * session across a pause or an ended run: an error that stops the chain before
+ * it can read the folder again still belongs to the step it last reached.
+ */
+const lastAt = new WeakMap();
+/** A new stage drops the object; the same stage keeps it until another object is queued. */
+export function setJourneyAt(session, stage) {
+    const cur = lastAt.get(session);
+    // Review M2: a new stage is progress: the stop count starts over.
+    if (cur?.stage !== stage)
+        stops.delete(session);
+    lastAt.set(session, cur?.stage === stage ? cur : { stage });
+}
+export const journeyAt = (session) => lastAt.get(session)?.stage;
+/**
+ * The step an error stopped: the stage on the object it was working on (a FIX
+ * on ZCL_A is not a FIX on ZCL_B), or the stage alone when it has no object.
+ */
+export function journeyStepKey(session) {
+    const at = lastAt.get(session);
+    return at ? (at.key ? `${at.stage} ${at.key}` : at.stage) : undefined;
+}
+/**
+ * Stops on an error, by step, for the session (must-fix follow-up a): kept
+ * across a pause and an ended run, so a step that fails again after "carry on"
+ * is told apart from a new failure. Counted only IN A ROW: a stop at another
+ * step, a new stage reached, or a step queued (the chain got through) starts over.
+ */
+const stops = new WeakMap();
+/** Count this stop: how many times in a row the chain has stopped at `step`. */
+export function noteJourneyStop(session, step) {
+    const last = stops.get(session);
+    const count = last && last.step === step ? last.count + 1 : 1;
+    stops.set(session, { step, count });
+    return count;
+}
 /** Paused, and no turn of the person's has run since the pause line. */
 export const isJourneyPausedJustNow = (session) => !!session && paused.has(session) && paused.get(session) === userTurnCount(session);
 /** The session skips as the stage machine reads them. */
@@ -126,6 +169,7 @@ export function journeySkips(session) {
         ...(s.fix.size ? { fix: new Set(s.fix) } : {}),
         ...(s.prove ? { prove: true } : {}),
         ...(s.report ? { report: true } : {}),
+        ...(s.rebuild?.size ? { rebuild: new Set(s.rebuild) } : {}),
     };
 }
 export function addJourneySkips(session, add) {
@@ -140,6 +184,11 @@ export function addJourneySkips(session, add) {
         s.prove = true;
     if (add.report)
         s.report = true;
+    if (add.rebuild?.size) {
+        s.rebuild ??= new Set();
+        for (const k of add.rebuild)
+            s.rebuild.add(k);
+    }
     skips.set(session, s);
 }
 /**
@@ -155,12 +204,13 @@ export function addJourneyLeftOut(session, keys) {
         s.leftOut.add(k);
     skips.set(session, s);
 }
-/** "Carry on" asks the check, the report and the rows the triage left out again; fixes and rows skipped stay put off. */
+/** "Carry on" asks the check, the report, the rebuild hand-offs and the rows the triage left out again; fixes and rows skipped stay put off. */
 export function forgetNotNow(session) {
     const s = skips.get(session);
     if (!s)
         return;
     delete s.prove;
     delete s.report;
+    delete s.rebuild;
     delete s.leftOut;
 }

package/dist/journey/rebuild.js

@@ -0,0 +1,464 @@
+/**
+ * Step 2, Task 5 — the chained rebuild hand-off (spec §3.5, D3; reviews F1, F2,
+ * F4, F5, F6, F9, F17; plan review C5, I6, I7, cut 4).
+ *
+ * A rebuild never runs inside the clean-core fix loop. At the journey's end
+ * (DONE) CSPeach proposes the KIND per object (or per `app` label) on one card;
+ * Yes writes the `handed-off` row on the old object, ENDS the journey (F1),
+ * and only then queues the chain for that kind:
+ *
+ *   app    /abap-app @rebuilds/<APP>/rebuild-brief.md   (the app lane routes RAP / CAP / SEGW)
+ *   class  /abap-modernize <TYPE> <NAME> — <reason>
+ *   api    /abap-modernize <TYPE> <NAME> — <reason>; API service, no UI   (tonight, F2)
+ *
+ * Every command is built here from the register (names upper-cased and checked
+ * like refactorCommand, the reason through cleanReason); the model never
+ * authors one. The brief is written by code from the fixed F5 template: the
+ * card's "Why" is never copied into it.
+ *
+ * The `rebuild` row then moves on from the existing hooks, never from session
+ * memory alone: `started` when a plan is saved for a spec under
+ * `<project>/rebuilds/<APP>/` (afterPlanSave, I6) or — for /abap-modernize —
+ * on the first successful SAP write of its turns; `built` when that plan
+ * completes (afterPlanComplete, C5) or by `cspeach team rebuild built`.
+ * `proven` (a code-run ATC over the new objects) is not written tonight: the
+ * status stops at "built, not yet checked".
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { APP_LABEL, isAppLabel, objectKey, proposeRebuildKind, } from '@cspeach/register-core';
+import { activeProject } from '../register/store.js';
+import { registerFor } from '../register/picture.js';
+import { writeRecord } from '../register/records.js';
+import { writeWhole } from '../register/write-whole.js';
+import { cspeachWritesThisSession } from '../register/offer.js';
+import { shown } from '../register/atc-file.js';
+import { cleanReason, OBJECT_NAME, OBJECT_TYPE, objectShown } from './run.js';
+import { clearJourneyFlow } from './flow.js';
+import { whoAmI } from '../commands/team.js';
+import { setRebuildRunActive } from '../commands/plan-gate.js';
+/* ── words ──────────────────────────────────────────────────────────────── */
+export const KIND_WORDS = {
+    app: 'an app', class: 'a clean class on released APIs', api: 'an API service',
+};
+const KIND_CHOICES = [
+    { value: 'app', label: 'An app' }, { value: 'class', label: 'A clean class' }, { value: 'api', label: 'An API service' },
+];
+/** F1: said once, as the journey ends for the rebuild. */
+export const HAND_OFF_LINE = (name) => `${name}'s rebuild goes on in its own run. Say carry on with clean core later for the rest.`;
+/** Audit M-2 — the queued rebuild on screen: CSPeach's own step, never "You › /abap-modernize …". */
+export const REBUILD_STEP_LINE = (name) => `CSPeach is starting the rebuild of ${shown(name).trim()}…`;
+export const UNSURE_LINE = 'CSPeach cannot tell the kind from what it read. Change it if it is wrong.';
+/** Where the brief is written, relative to the project folder (the journey's cwd). */
+export const REBUILD_BRIEF_REL = (app) => `rebuilds/${app}/rebuild-brief.md`;
+const SID = /^[A-Z][A-Z0-9]{2}$/;
+const PACKAGE = /^(\/[A-Z0-9_]{1,10}\/)?[A-Z0-9_$]{1,30}$/;
+const LEVEL = /^[A-D]$/;
+const MODERNIZE = 'abap-modernize';
+const nameOk = (type, name) => OBJECT_TYPE.test(type) && OBJECT_NAME.test(name);
+/* ── names and commands ─────────────────────────────────────────────────── */
+/** The app label: the decision's, else the object name (a namespace folded in); null when it is not a label. */
+export function appLabelFor(o) {
+    const own = o.decision?.app;
+    if (own && isAppLabel(own))
+        return own;
+    const name = o.name.trim().toUpperCase().replace(/^\/([A-Z0-9_]+)\//, '$1_');
+    return isAppLabel(name) ? name : null;
+}
+/** The command a hand-off queues, built here; null when a name or the label is not one CSPeach passes on. */
+export function rebuildCommand(kind, o, app) {
+    const type = o.type.trim().toUpperCase();
+    const name = o.name.trim().toUpperCase();
+    if (!nameOk(type, name))
+        return null;
+    if (kind === 'app')
+        return isAppLabel(app) ? `/abap-app @${REBUILD_BRIEF_REL(app)}` : null;
+    const reason = cleanReason(o.reason);
+    if (kind === 'class')
+        return `/abap-modernize ${type} ${name}${reason ? ` — ${reason}` : ''}`;
+    return `/abap-modernize ${type} ${name} — ${reason ? `${reason}; ` : ''}API service, no UI`;
+}
+/**
+ * The fixed template (F5). The words report / list / ALV / download never
+ * stand as the ask; the card's "Why" is not copied. Every name is an ABAP
+ * name (checked by the caller); anything else here is cleaned or left out.
+ */
+export function rebuildBrief(b) {
+    const objs = b.objects.map((o) => ({ type: o.type.toUpperCase(), name: o.name.toUpperCase(), pkg: o.package && PACKAGE.test(o.package.toUpperCase()) ? o.package.toUpperCase() : undefined }));
+    const sid = b.sid && SID.test(b.sid.toUpperCase()) ? b.sid.toUpperCase() : 'the SAP system';
+    const names = objs.map((o) => o.name).join(', ');
+    const why = screenedReason(b.reason);
+    const target = b.target && LEVEL.test(b.target) ? b.target : 'not set';
+    return [
+        `# Rebuild of ${objs.map((o) => `${o.name} (${o.type}${o.pkg ? `, package ${o.pkg}` : ''})`).join(', ')} on ${sid}`,
+        ...(b.kind === 'app' ? [`Build an app that replaces the old program ${names}. Users create, change and view the same data the old program handles today.`] : []),
+        ...(b.kind === 'api' ? [`Build an API service that replaces ${names}: no UI, OData service.`] : []),
+        ...objs.map((o) => `Read the old program's behaviour from the SAP system (${o.type} ${o.name}) before designing: its selection fields, its output columns, its checks.`),
+        `Target clean-core level: ${target}.`,
+        ...(why ? [`Why it was decided (context only, not a requirement): ${why.text}.`] : []),
+        ...(why?.marked ? [MARKED_NOTE] : []),
+        // Ruling (fix round 1 follow-up): no quotable "report" phrase anywhere in the ask.
+        b.kind === 'api'
+            ? 'The result is a new API service with no UI that replaces the old program; the app lane chooses how to build it.'
+            : 'The result is a new app with a modern UI that replaces the old program; the app lane chooses how to build it.',
+        `Do not change ${names}.`,
+        '',
+    ].join('\n');
+}
+/** Words that, as an ask, would send the app lane to a classic report (report_only). */
+const REPORT_WORDS = /\b(reports?|reporting|lists?|listing|alv|downloads?|downloaded|downloading|write|writes|output)\b/gi;
+export const MARKED_NOTE = 'Words marked * describe the old program today, not what to build.';
+/**
+ * The decision's reason as context for the brief (review fix 2): cleaned to
+ * one line, and every report-like word kept but marked with `*`, so no quote
+ * of the reason as written ("download the ALV list") is found in the brief and
+ * the lane cannot read it as a report_only request.
+ */
+export function screenedReason(reason) {
+    const text = cleanReason(reason).replace(/\*/g, '').replace(/[\s.]+$/, '');
+    if (!text)
+        return null;
+    let marked = false;
+    const out = text.replace(REPORT_WORDS, (w) => { marked = true; return `${w}*`; });
+    return { text: out, marked };
+}
+/** Write the brief whole, then rename, under `<projectDir>/rebuilds/<APP>/`. Returns the file. */
+export function writeRebuildBrief(projectDir, app, text) {
+    if (!isAppLabel(app))
+        throw new Error('the app name cannot be used for a folder');
+    const file = path.join(projectDir, ...REBUILD_BRIEF_REL(app).split('/'));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeWhole(file, text);
+    return file;
+}
+/* ── the record ─────────────────────────────────────────────────────────── */
+/** The seat name: `whoAmI` over the author identity, as the journey's session deps read it. */
+async function seatName() {
+    const { getAuthorIdentity } = await import('../agent/loop.js');
+    return whoAmI({ identity: getAuthorIdentity });
+}
+/** One evidence record: the `rebuild` row on each OLD object's key (additive; older readers drop it). */
+export function writeRebuildRows(joined, keys, row, by, now = new Date()) {
+    const at = now.toISOString();
+    return writeRecord(joined, 'evidence', keys.map((key) => ({ key, rebuild: { ...(typeof row === 'function' ? row(key) : row), by, at } })), { name: by }, { now });
+}
+function registerNow(joined) {
+    return registerFor(joined.projectDir, joined.outboxDir).register;
+}
+/**
+ * "<NAME> → rebuild as <kind>." Why: <fact>. [Yes] [Change kind] [Later].
+ * Change kind shows the three kinds, then the card again with the new one.
+ */
+export async function rebuildCard(confirm, g) {
+    let kind = g.kind;
+    let sure = g.sure;
+    const who = g.objects.length === 1 ? g.objects[0].name.toUpperCase() : g.app;
+    for (let tries = 0; tries < 5; tries++) {
+        const res = await confirm({
+            id: 'journey-rebuild',
+            tag: 'QUESTION',
+            title: `${who} → rebuild as ${KIND_WORDS[kind]}.`,
+            facts: [
+                ...(g.objects.length > 1 ? [`Old objects: ${g.objects.map((o) => o.name.toUpperCase()).join(', ')}.`] : []),
+                ...g.whys.map((w) => `Why: ${w}.`),
+                ...(sure ? [] : [UNSURE_LINE]),
+                'The rebuild runs on its own, outside these clean-core steps.',
+                'CSPeach asks before it writes to SAP.',
+            ],
+            choices: [{ value: 'yes', label: 'Yes' }, { value: 'change', label: 'Change kind' }, { value: 'later', label: 'Later' }],
+            initial: 0,
+            aliases: { y: 'yes', c: 'change', l: 'later' },
+        });
+        if (res.cancelled || res.value === null)
+            return { kind: 'cancel' };
+        if (res.value === 'later')
+            return { kind: 'later' };
+        if (res.value === 'yes')
+            return { kind: 'yes', rebuild: kind };
+        const pick = await confirm({
+            id: 'journey-rebuild-kind',
+            tag: 'QUESTION',
+            title: `Rebuild ${who} as?`,
+            choices: KIND_CHOICES,
+            initial: KIND_CHOICES.findIndex((c) => c.value === kind),
+            aliases: { a: 'app', c: 'class', s: 'api' },
+        });
+        if (pick.cancelled || pick.value === null)
+            return { kind: 'cancel' };
+        if (pick.value === 'app' || pick.value === 'class' || pick.value === 'api') {
+            kind = pick.value;
+            sure = true;
+        }
+    }
+    return { kind: 'cancel' };
+}
+/**
+ * My rebuild decisions with no `rebuild` row yet, in name order. The kind is
+ * the person's (`rebuildKind`) when one is recorded, else the proposal (F6,
+ * from the type and the newest check's rule ids). Objects that share an app
+ * label make ONE group only when their kind is `app` (one app replaces them
+ * all); a class or an API service is one card per object (review fix 3).
+ * `passed` names each rebuild CSPeach cannot hand off, with why.
+ */
+export function rebuildGroups(mine, skip, rulesOf = () => []) {
+    const groups = new Map();
+    const passed = [];
+    for (const o of mine) {
+        if (o.decision?.classification !== 'redesign' || o.evidence.rebuild || skip?.has(o.key))
+            continue;
+        if (!nameOk(o.type.toUpperCase(), o.name.toUpperCase())) {
+            passed.push({ key: o.key, line: `${objectShown(o.name)}: the name is not an ABAP name, so CSPeach passed its rebuild over.` });
+            continue;
+        }
+        const app = appLabelFor(o);
+        if (!app) {
+            const folded = o.name.trim().toUpperCase().replace(/^\/([A-Z0-9_]+)\//, '$1_');
+            const why = APP_LABEL.test(folded)
+                ? 'the name is reserved by Windows and cannot be a folder, so CSPeach passed its rebuild over. Give it another app name.'
+                : 'the name is too long for a rebuild folder, so CSPeach passed its rebuild over. Give it a shorter app name.';
+            passed.push({ key: o.key, line: `${o.name.toUpperCase()}: ${why}` });
+            continue;
+        }
+        const p = proposeRebuildKind({ type: o.type, name: o.name, rules: rulesOf(o.key) });
+        const own = o.decision.rebuildKind;
+        const kind = own ?? p.kind;
+        const entry = {
+            type: o.type.toUpperCase(), name: o.name.toUpperCase(), key: o.key, package: o.package,
+            ...(o.decision.reason ? { reason: o.decision.reason } : {}), target: o.proof?.target?.level ?? null,
+        };
+        const id = kind === 'app' ? `app|${app}` : `one|${o.key}`;
+        const g = groups.get(id);
+        if (g) {
+            g.objects.push(entry);
+            g.whys.push(p.why);
+            continue;
+        }
+        groups.set(id, { app, objects: [entry], kind, sure: own ? true : p.sure, whys: [p.why] });
+    }
+    return Object.assign([...groups.values()], { passed });
+}
+/** Review fix 3: the objects of a label that a class/API hand-off leaves for later. */
+export const STAY_PLANNED_LINE = (names) => names.length === 1 ? `${names[0]} stays planned — it comes back on the next card.` : `${names.join(', ')} stay planned — they come back on the next card.`;
+/**
+ * Yes on the card: the brief (app/api), the `handed-off` row, the journey
+ * ENDED with the F1 line, then — only then — the command queued (never as a
+ * journey step: `flow.queued` is not set). Returns false when nothing was
+ * handed off (a name CSPeach does not pass on, a record that could not be
+ * written): the line is said, and the journey ends all the same.
+ */
+export function handOffRebuild(h, g, kind) {
+    const joined = activeProject();
+    // One app replaces every object of the label; a class or an API is one object per run.
+    const objects = kind === 'app' ? g.objects : g.objects.slice(0, 1);
+    const rest = g.objects.slice(objects.length).map((o) => o.name);
+    const first = objects[0];
+    const command = rebuildCommand(kind, first, g.app);
+    const who = objects.length === 1 ? first.name : g.app;
+    if (!joined || !command) {
+        clearJourneyFlow(h.session);
+        h.emit(`${who}: the name cannot be used in a command, so nothing was handed off.`);
+        return false;
+    }
+    const now = (h.now ?? (() => new Date()))();
+    try {
+        if (kind !== 'class') {
+            writeRebuildBrief(joined.projectDir, g.app, rebuildBrief({
+                kind, ...(h.sid ? { sid: h.sid } : {}), target: first.target ?? null,
+                ...(first.reason ? { reason: first.reason } : {}), objects,
+            }));
+        }
+        const keys = objects.map((o) => o.key ?? objectKey(o.type, o.name));
+        const res = writeRebuildRows(joined, keys, { kind, app: g.app, status: 'handed-off' }, h.by, now);
+        if (!res.written)
+            throw new Error("the object is not in the project's object list");
+        if (kind !== 'app')
+            rememberModernizeHandOff(h.session, { keys, kind, app: g.app, ...(h.callsAt !== undefined ? { callsAt: h.callsAt } : {}) });
+    }
+    catch (e) {
+        clearJourneyFlow(h.session);
+        const why = shown(e instanceof Error ? e.message : String(e)).replace(/[\s.]+$/, '');
+        h.emit(`Not recorded: ${why || 'the record could not be written to this folder'}. Nothing was handed off.`);
+        return false;
+    }
+    // F1: the journey ends BEFORE the rebuild is queued.
+    clearJourneyFlow(h.session);
+    h.emit(HAND_OFF_LINE(who));
+    if (rest.length)
+        h.emit(STAY_PLANNED_LINE(rest));
+    if (h.queueNext) {
+        // Final review I2: the queued turn runs with no keypress, so auto_approve never applies to its SAP writes.
+        guardedHandOff.set(h.session, turnSeqOf(h.session));
+        setRebuildRunActive(true);
+        h.queueNext(command, { by: 'rebuild', line: REBUILD_STEP_LINE(who) });
+    }
+    else
+        h.emit(`Next: ${command}`);
+    return true;
+}
+/* ── started / built ────────────────────────────────────────────────────── */
+const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+/**
+ * I6 — in afterPlanSave, inside an app flow: when the flow's spec resolves
+ * (realpath) under `<joined project>/rebuilds/<APP>/`, write `started` with
+ * the saved plan's basename on every old object whose newest rebuild is for
+ * that APP. Never on a rebuild already built (a plan saved again after the
+ * build does not reopen it: `started` never downgrades `built`), and never
+ * twice for the same plan. A failure is one line; the app chain goes on.
+ */
+export async function rebuildStartedAfterPlanSave(a) {
+    try {
+        const joined = activeProject();
+        if (!joined)
+            return;
+        const tok = a.specToken.trim().replace(/^@/, '');
+        let real;
+        let root;
+        try {
+            real = fs.realpathSync.native(path.resolve(a.cwd, tok));
+            root = fs.realpathSync.native(joined.projectDir) + path.sep + 'rebuilds' + path.sep;
+        }
+        catch {
+            return;
+        }
+        if (!fold(real).startsWith(fold(root)))
+            return;
+        const app = real.slice(root.length).split(path.sep)[0] ?? '';
+        if (!isAppLabel(app))
+            return;
+        const plan = path.basename(a.savedPath);
+        const old = registerNow(joined).objects.filter((o) => {
+            const r = o.evidence.rebuild;
+            return r?.app === app && (r.status === 'handed-off' || (r.status === 'started' && r.plan !== plan));
+        });
+        if (!old.length)
+            return;
+        const kinds = new Map(old.map((o) => [o.key, o.evidence.rebuild.kind]));
+        writeRebuildRows(joined, old.map((o) => o.key), (key) => ({ kind: kinds.get(key), app, status: 'started', plan }), a.by ?? await seatName(), a.now);
+    }
+    catch (e) {
+        a.emit(`The rebuild record could not be written: ${shown(e instanceof Error ? e.message : String(e))}`);
+    }
+}
+/**
+ * C5 — the plan at `planPath` finished (plan-chain's continuous run and
+ * finishPlanResume's live run; never a re-opened complete plan). Writes
+ * `built` only on old objects whose newest rebuild names this plan and is not
+ * built yet, so a second call writes nothing. No session state is read.
+ */
+export async function afterPlanComplete(planPath, opts = {}) {
+    try {
+        const joined = activeProject();
+        if (!joined)
+            return;
+        const plan = path.basename(planPath);
+        const old = registerNow(joined).objects.filter((o) => o.evidence.rebuild?.plan === plan
+            && o.evidence.rebuild.status !== 'built' && o.evidence.rebuild.status !== 'proven');
+        if (!old.length)
+            return;
+        const of = new Map(old.map((o) => [o.key, o.evidence.rebuild]));
+        writeRebuildRows(joined, old.map((o) => o.key), (key) => ({ kind: of.get(key).kind, app: of.get(key).app, status: 'built', plan }), opts.by ?? await seatName(), opts.now);
+    }
+    catch { /* a completion line is never held up by a record */ }
+}
+/**
+ * The session's turn sequence (loop.ts `session.turn_seq`): one up at the
+ * start of every turn, never lowered by a compaction — unlike the message
+ * count, which /compact and auto-compact shrink (re-review N1). 0 when the
+ * session keeps none (it then never passes the hand-off's own turn).
+ */
+const turnSeqOf = (session) => {
+    const t = session.turn_seq;
+    return typeof t === 'number' && Number.isFinite(t) ? t : 0;
+};
+const modernizing = new WeakMap();
+/** The hand-off turn's sequence, while the queued rebuild turn runs under the guarded-run override (I2). */
+const guardedHandOff = new WeakMap();
+const callsOf = (session) => {
+    const c = session.toolCalls;
+    return Array.isArray(c) ? c : [];
+};
+/**
+ * A /abap-modernize hand-off waits for its first SAP write to read `started`
+ * (F9). The session's turn sequence is kept, so the turn the hand-off happened in
+ * (the refactor or triage turn whose post-turn hook showed the card) is never
+ * read as the rebuild's own turn (review fix 1).
+ */
+export function rememberModernizeHandOff(session, p) {
+    modernizing.set(session, {
+        keys: [...p.keys], kind: p.kind, app: p.app, callsAt: p.callsAt ?? callsOf(session).length, turnAt: turnSeqOf(session),
+    });
+}
+/**
+ * After a top-level turn: while the session stays in /abap-modernize, the
+ * first successful SAP write since the hand-off writes `started` (once). The
+ * hand-off's own turn is passed over; any other skill after it forgets the
+ * hand-off, and the row stays `handed-off`.
+ */
+export async function afterRebuildTurn(session, skill, opts = {}) {
+    const handedAt = guardedHandOff.get(session);
+    // The queued rebuild turn is done (whatever skill ran), or a turn of another session ran
+    // (a /clear before it): the guarded-run share ends (I2). The hand-off turn itself keeps it.
+    if (handedAt === undefined || turnSeqOf(session) > handedAt) {
+        guardedHandOff.delete(session);
+        setRebuildRunActive(false);
+    }
+    const p = modernizing.get(session);
+    if (!p)
+        return;
+    if (turnSeqOf(session) <= p.turnAt)
+        return; // the turn the hand-off happened in (N1: the turn sequence, not the messages)
+    if (skill !== MODERNIZE) {
+        modernizing.delete(session);
+        return;
+    }
+    if (cspeachWritesThisSession(callsOf(session).slice(p.callsAt)).size === 0)
+        return;
+    modernizing.delete(session);
+    try {
+        const joined = activeProject();
+        if (!joined)
+            return;
+        const objects = registerNow(joined).objects;
+        const keys = p.keys.filter((k) => {
+            const r = objects.find((o) => o.key === k)?.evidence.rebuild;
+            return r?.app === p.app && r.status === 'handed-off';
+        });
+        if (keys.length)
+            writeRebuildRows(joined, keys, { kind: p.kind, app: p.app, status: 'started' }, opts.by ?? await seatName(), opts.now);
+    }
+    catch { /* the rebuild goes on; the row stays handed-off */ }
+}
+/* ── cspeach team rebuild built ─────────────────────────────────────────── */
+export const REBUILD_USAGE = 'Usage: cspeach team rebuild built <TYPE> <NAME> --app <APP>';
+export const APP_WORDS = '--app is a name of letters, digits and underscores, for example AR_COCKPIT (not CON, NUL, AUX, PRN, COM1-9 or LPT1-9).';
+/**
+ * F9 — a /abap-modernize rebuild reaches `built` by hand. Only for an object
+ * decided "rebuild", or with a rebuild row already. The kind is the newest
+ * rebuild row's, else the decision's, else the proposal. Returns the line to
+ * print, or throws with the reason.
+ */
+export function recordRebuildBuilt(args, by, now = new Date()) {
+    const type = args.type.trim().toUpperCase();
+    const name = args.name.trim().toUpperCase();
+    const app = args.app.trim().toUpperCase();
+    if (!nameOk(type, name))
+        throw new Error(`${shown(type)} ${shown(name)} is not an ABAP object name.`);
+    if (!isAppLabel(app))
+        throw new Error(APP_WORDS);
+    const joined = activeProject();
+    if (!joined)
+        throw new Error('This laptop has not joined a team project. Run: cspeach team join <folder>');
+    const key = objectKey(type, name);
+    const o = registerNow(joined).objects.find((x) => x.key === key);
+    if (!o)
+        throw new Error(`${type} ${name} is not in this team project's object list.`);
+    const before = o.evidence.rebuild;
+    if (!before && o.decision?.classification !== 'redesign') {
+        throw new Error(`${type} ${name} is not marked for a rebuild. Record that first: cspeach team decide ${type} ${name} rebuild`);
+    }
+    const kind = before?.kind ?? o.decision?.rebuildKind ?? proposeRebuildKind({ type, name }).kind;
+    const res = writeRebuildRows(joined, [key], { kind, app, status: 'built', ...(before?.app === app && before.plan ? { plan: before.plan } : {}) }, by, now);
+    if (!res.written)
+        throw new Error(`${type} ${name} is not in this team project's object list.`);
+    return `✓ Recorded: ${type} ${name} — rebuilt as ${app}, built, not yet checked.`;
+}