@cspeach/cli 1.1.30 → 1.1.31

package/dist/journey/chain.js

@@ -0,0 +1,728 @@
+/**
+ * Guided clean-core journey, Task 3 — the harness-owned chain (the /abap-app
+ * shape: lane/app-chain.ts).
+ *
+ *   enterJourney      a start sentence / "carry on" (REPL, before the classifier)
+ *   drive             derive the stage from the folder, ask the step card,
+ *                     run the code stage, derive again … until a model step
+ *                     (queued through the pending-dispatch slot), a stop, or done
+ *   afterJourneyTurn  the queued model turn ended (runTurn's post-turn hook):
+ *                     derive again and go on
+ *   gateJourneyForTurn any other turn ends the chain with one line
+ *
+ * Every queued command is built by code (run.ts triageCommand / refactorCommand).
+ * Headless runs nothing and queues nothing: runJourneyStage says the next step.
+ */
+import { estateSummaryOf } from '@cspeach/register-core';
+import { DEFAULT_ATC_VARIANT, runTeamCommand, whoAmI } from '../commands/team.js';
+import { activeProject, readEstate, readProjectFile, VARIANT_NAME } from '../register/store.js';
+import { findingsByObject } from '../register/findings.js';
+import { shown, shownUpTo } from '../register/atc-file.js';
+import { cspeachWritesThisSession } from '../register/offer.js';
+import { cardSlotEmitter } from '../ui/card-slot.js';
+import { claimedSinceCheck, decidePage, fixFailedCheck, readJourneyFacts, stageOf, stepOf, STEPS, toDecide, toFix } from './clean-core.js';
+import { addJourneyLeftOut, addJourneySkips, clearJourneyFlow, forgetNotNow, getJourneyFlow, journeySkips, pauseJourneyFlow, setJourneyPage, setJourneyQueued, startJourneyFlow, } from './flow.js';
+import { notRecordedLine, passedOverLine, refactorCommand, runJourneyStage, shownReason } from './run.js';
+import { cleanKeepReason, FACT_ROWS, KEEP_QUESTION } from '../projects/clean-core-confirm.js';
+import { sessionTeamDeps } from './session-deps.js';
+/* ── words ──────────────────────────────────────────────────────────────── */
+export const PAUSED_LINE = (step) => step ? `Paused at step ${step}. Say carry on to continue.` : 'Paused. Say carry on to continue.';
+export const LOOK_TITLE = 'Look at the system?';
+export const START_TITLE = 'Start the project here?';
+export const NOTHING_READ_LINE = 'Nothing was read from the system.';
+export const NOT_STARTED_LINE = 'No project was started.';
+/** A discovery this many days old is used as it is; an older one asks again. */
+export const FRESH_DAYS = 7;
+const plural = (count, one, many) => `${count.toLocaleString('en-US')} ${count === 1 ? one : many}`;
+/** About 25 objects a minute (run.ts, live measurement 2026-10-07). */
+const aboutMinutes = (objects) => {
+    const m = Math.max(1, Math.ceil(objects / 25));
+    return m === 1 ? 'about a minute' : `about ${m} minutes`;
+};
+const footnote = (stage) => `Step ${stepOf(stage)} of 6`;
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** "09:12 on 7 Oct", local time. */
+export function shownTime(iso) {
+    const d = new Date(iso);
+    if (!Number.isFinite(d.getTime()))
+        return 'an earlier time';
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    return `${hh}:${mm} on ${d.getDate()} ${MONTHS[d.getMonth()]}`;
+}
+const CANCELLED = { value: null, cancelled: true };
+/**
+ * The classic REPL has no card listener: each journey card becomes one typed
+ * line ("Fix X now? Yes (y) / Pick another (p) / Later (l)"), its facts printed
+ * above it. Empty or unknown → put away.
+ */
+export function lineConfirm(prompt, emit) {
+    return async (req) => {
+        for (const f of req.facts ?? [])
+            emit(`  ${f}`);
+        const keys = Object.entries(req.aliases ?? {});
+        const choices = req.choices.map((c) => {
+            const k = keys.find(([, v]) => v === c.value)?.[0];
+            return k ? `${c.label} (${k})` : c.label;
+        }).join(' / ');
+        const raw = (await prompt(`${req.title} ${choices}`)).trim().toLowerCase();
+        if (!raw)
+            return CANCELLED;
+        const alias = req.aliases?.[raw];
+        if (alias)
+            return { value: alias };
+        const hit = req.choices.find((c) => c.label.toLowerCase() === raw || c.value === raw);
+        return hit ? { value: hit.value } : CANCELLED;
+    };
+}
+/**
+ * The journey's card: the Ink card slot when it has a listener, else a typed
+ * line (classic REPL). Also the row cards of the triage save (Task 4).
+ */
+export function journeyCardConfirm(emit) {
+    return async (req) => {
+        if (cardSlotEmitter.listenerCount('confirm') > 0) {
+            const { askConfirm } = await import('../ui/confirm-request.js');
+            return askConfirm(req);
+        }
+        const { inkAwarePrompt } = await import('../agent/loop.js');
+        return lineConfirm(inkAwarePrompt, emit)(req);
+    };
+}
+/**
+ * The journey's free-text question ("Why keep it?"): the Ink prompt when it
+ * has a listener, else a typed line (classic). Esc on the Ink prompt puts the
+ * question away, as Esc on a card does — it throws, so the rows stop and the
+ * journey pauses, instead of the question coming back.
+ */
+export function journeyAsk() {
+    return async (question) => {
+        const { askQuestionEmitter } = await import('../ui/ask-question-emitter.js');
+        if (askQuestionEmitter.listenerCount('request') > 0) {
+            const res = await askQuestionEmitter.request({ id: 'journey-ask', question, kind: 'text', choices: [] });
+            if (res.cancelled || res.answer === null)
+                throw new Error('put away');
+            return res.answer;
+        }
+        const { inkAwarePrompt } = await import('../agent/loop.js');
+        return inkAwarePrompt(question);
+    };
+}
+const defaultConfirm = (h) => journeyCardConfirm(h.emit);
+async function teamFor(h) {
+    const base = {
+        ...(h.adt ? { adt: h.adt } : {}),
+        ...(h.sapAlias ? { sapAlias: h.sapAlias } : {}),
+        ...(h.noSap ? { noSap: true } : {}),
+        ...(h.identity ? { identity: h.identity } : {}),
+        ...(h.now ? { now: h.now } : {}),
+        ...(h.rand ? { rand: h.rand } : {}),
+        ...(h.machine ? { machine: h.machine } : {}),
+    };
+    return h.headless
+        ? sessionTeamDeps({ ...base, headless: true })
+        : sessionTeamDeps({ ...base, headless: false, signal: h.signal ?? new AbortController().signal, confirm: h.confirm ?? defaultConfirm(h) });
+}
+/**
+ * The line for a chain that cannot go on at `stage`: before a project exists
+ * there is nothing to carry on, so steps 1 and 2 say what did not happen.
+ */
+function stopAt(h, stage) {
+    if (stage === 'INVENTORY')
+        end(h, NOTHING_READ_LINE);
+    else if (stage === 'START')
+        end(h, NOT_STARTED_LINE);
+    else
+        pause(h, stepOf(stage));
+}
+/** The session's tool calls (the refactor's writes are read from them); none when the session keeps none. */
+function toolCallsOf(session) {
+    const calls = session.toolCalls;
+    return Array.isArray(calls) ? calls : [];
+}
+/** End the chain: optional last line, the guarded run off. */
+function end(h, line) {
+    clearJourneyFlow(h.session);
+    if (line)
+        h.emit(line);
+}
+/** Pause the chain: the pause line, and "carry on" (even bare) picks it up. */
+function pause(h, step) {
+    pauseJourneyFlow(h.session);
+    h.emit(PAUSED_LINE(step));
+}
+/* ── entry ──────────────────────────────────────────────────────────────── */
+/** A start sentence, a refused pattern, or "carry on" — from the REPL, before the classifier. */
+export async function enterJourney(trigger, h) {
+    if (trigger.kind === 'refuse') {
+        h.emit(trigger.line);
+        return;
+    }
+    startJourneyFlow(h.session, trigger.kind === 'start' ? trigger.packages : []);
+    forgetNotNow(h.session);
+    try {
+        await drive(h);
+    }
+    catch (e) {
+        end(h);
+        throw e;
+    }
+}
+/* ── the step cards ─────────────────────────────────────────────────────── */
+async function yesNo(confirm, req) {
+    const res = await confirm({
+        ...req, tag: 'QUESTION', choices: [{ value: 'yes', label: 'Yes' }, { value: 'no', label: 'No' }], initial: 0, aliases: { y: 'yes', n: 'no' },
+    });
+    return !res.cancelled && res.value === 'yes';
+}
+/** The folder's inventory: when it was taken, on which system; null when there is none. */
+function inventoryOf(cwd) {
+    const found = readEstate(cwd);
+    const s = found ? estateSummaryOf(found.estate) : null;
+    if (!s)
+        return null;
+    return {
+        takenAt: s.takenAt,
+        ...(s.system?.sid ? { sid: s.system.sid } : {}),
+        packages: new Map(s.packages.map((p) => [p.name.toUpperCase(), p.codeObjects])),
+    };
+}
+const PACKAGE = /^(\/[A-Z0-9_]{1,10}\/)?[A-Z0-9_]{1,30}$/;
+/** The named packages and their code objects, when all are names the system has; else null (the runner says why). */
+function startScope(cwd, packages) {
+    const names = [...new Set(packages.map((p) => p.trim().toUpperCase()).filter(Boolean))];
+    if (!names.length || names.some((p) => !PACKAGE.test(p)))
+        return null;
+    const inv = inventoryOf(cwd);
+    if (!inv || names.some((p) => !inv.packages.has(p)))
+        return null;
+    return { names, objects: names.reduce((n, p) => n + (inv.packages.get(p) ?? 0), 0) };
+}
+/** The card shows this much of a recorded reason, wrapped over up to FACT_ROWS rows. */
+export const CARD_REASON = 300;
+const LEVEL = /^[A-D]$/;
+/**
+ * Every fix or rebuild is recorded with target A when none was given
+ * (register/records.ts, `cspeach team decide`); register-core keeps what it is
+ * handed, so a recorded A cannot be told from a default. Only another level
+ * was set on purpose, and only that one is said.
+ */
+const DEFAULT_TARGET = 'A';
+/**
+ * The facts of the fix card, from the register only (no SAP call): the open
+ * findings, a failed check, why (the decision's reason as written, cleaned
+ * for the screen, at most 300 characters, wrapped on the card), the target level when one was set
+ * on purpose, the approval promise, and where this object stands in the list.
+ */
+export function fixFacts(o, at, of, open = []) {
+    const reason = shownReason(o.decision?.reason, CARD_REASON);
+    const set = o.decision?.targetLevel;
+    const target = set && LEVEL.test(set) && set !== DEFAULT_TARGET ? set : undefined;
+    const now = o.decision?.level && LEVEL.test(o.decision.level) ? o.decision.level : undefined;
+    return [
+        o.openFindings === null ? 'Not checked yet.' : `${plural(o.openFindings, 'open finding', 'open findings')}.`,
+        ...(fixFailedCheck(o) ? ['Its last fix failed the check.', ...open] : []),
+        ...(reason ? [`Why: ${reason}`] : []),
+        ...(target ? [`Target: level ${target}${now && now !== target ? `, now ${now}` : ''}.`] : []),
+        'CSPeach asks before it writes to SAP.',
+        `${at} of ${plural(of, 'object marked fix', 'objects marked fix')}.`,
+    ];
+}
+/** "Still open:" shows at most this many lines on a card. */
+const STILL_OPEN_ROWS = 3;
+/** A fact wraps onto at most this many rows on a card that also lists what is still open. */
+export const FACT_ROWS_BESIDE_OPEN = 3;
+/**
+ * What the newest measurement still finds in an object, in plain words, at
+ * most three lines: "Still open: Usage of not released application API
+ * (line 13)". Read from the folder's measurement records (findings.ts, the
+ * project's variant only); none when they cannot be read. The titles were
+ * written on another laptop, so they are cleaned for the screen.
+ */
+export function stillOpenLines(key) {
+    let latest = [];
+    try {
+        const joined = activeProject();
+        if (!joined)
+            return [];
+        latest = findingsByObject(joined.projectDir, joined.outboxDir, { lines: true }).get(key)?.latest ?? [];
+    }
+    catch {
+        return [];
+    }
+    const said = (r) => {
+        const what = shownUpTo(r.message || r.rule, 120).replace(/[\s.]+$/, '');
+        const where = r.count > 1 ? ` (${r.count} places${r.line ? `, first at line ${r.line}` : ''})` : r.line ? ` (line ${r.line})` : '';
+        return `Still open: ${what}${where}`;
+    };
+    if (latest.length <= STILL_OPEN_ROWS)
+        return latest.map(said);
+    // Findings, not rules: the same count the card's title gives.
+    const more = latest.slice(STILL_OPEN_ROWS - 1).reduce((sum, r) => sum + r.count, 0);
+    return [...latest.slice(0, STILL_OPEN_ROWS - 1).map(said), `And ${plural(more, 'other finding', 'other findings')}.`];
+}
+/**
+ * Step 4: "Fix <NAME> now?" [Yes] [Pick another] [Later], smallest first
+ * (toFix's order); a fix that failed the check asks "<NAME>'s fix failed the
+ * check — try again?". Pick another goes round the list; Later puts the
+ * object off for the session. Yes hands the runner a skip list that leaves
+ * only the chosen object first. Objects whose names are not ABAP names never
+ * reach this card: the chain passes them over first.
+ */
+export async function fixCard(confirm, objects, skips, openOf = () => []) {
+    const list = objects.filter((o) => refactorCommand({ type: o.type, name: o.name }) !== null);
+    if (!list.length)
+        return { kind: 'none' };
+    const many = list.length > 1;
+    for (let i = 0; i < list.length * 20; i++) {
+        const o = list[i % list.length];
+        const name = o.name.toUpperCase();
+        const open = fixFailedCheck(o) ? openOf(o) : [];
+        const res = await confirm({
+            id: 'journey-fix',
+            tag: 'QUESTION',
+            title: fixFailedCheck(o) ? `${name}'s fix failed the check — try again?` : `Fix ${name} now?`,
+            facts: fixFacts(o, (i % list.length) + 1, list.length, open),
+            choices: [{ value: 'yes', label: 'Yes' }, ...(many ? [{ value: 'another', label: 'Pick another' }] : []), { value: 'later', label: 'Later' }],
+            initial: 0,
+            aliases: { y: 'yes', ...(many ? { p: 'another' } : {}), l: 'later' },
+            footnote: footnote('FIX'),
+            // With what is still open on the card, the reason gets three rows, so the card stays short.
+            wrapFacts: open.length ? FACT_ROWS_BESIDE_OPEN : FACT_ROWS,
+        });
+        if (res.cancelled || res.value === null)
+            return { kind: 'cancel' };
+        if (res.value === 'another')
+            continue;
+        if (res.value === 'later')
+            return { kind: 'later', object: o };
+        const others = objects.filter((x) => x.key !== o.key).map((x) => x.key);
+        return { kind: 'yes', object: o, skips: { ...skips, fix: new Set([...(skips.fix ?? []), ...others]) } };
+    }
+    return { kind: 'cancel' };
+}
+/* ── the chain ──────────────────────────────────────────────────────────── */
+/** Where the chain is: the stage, and a print of what the session put off (no progress → stop). */
+const fingerprint = (stage, s) => `${stage}|${s.decide?.size ?? 0}|${s.fix?.size ?? 0}|${s.prove ? 1 : 0}|${s.report ? 1 : 0}`;
+async function drive(h) {
+    const flow = getJourneyFlow(h.session);
+    if (!flow)
+        return;
+    const team = await teamFor(h);
+    const confirm = team.confirm;
+    const now = () => (h.now ? h.now() : new Date());
+    let ranInventory = false;
+    let saidInventory = false;
+    let previous = '';
+    for (let round = 0; round < 24; round++) {
+        const me = whoAmI(team.deps);
+        const skips = journeySkips(h.session);
+        const facts = readJourneyFacts(h.cwd, me, skips);
+        const stage = stageOf(facts);
+        // Ctrl-C: what was measured is kept; "carry on" picks up from the folder.
+        if (h.signal?.aborted) {
+            stopAt(h, stage);
+            return;
+        }
+        const print = fingerprint(stage, skips);
+        // A code stage that changed nothing: never go round again.
+        if (print === previous) {
+            stopAt(h, stage);
+            return;
+        }
+        previous = print;
+        let runAs = stage;
+        let runSkips = skips;
+        if (!h.headless) {
+            // Step 1 — "Look at the system?": no inventory yet, or one older than a week.
+            const inv = stage === 'START' && !ranInventory ? inventoryOf(h.cwd) : null;
+            const stale = !!inv && now().getTime() - Date.parse(inv.takenAt) > FRESH_DAYS * 86_400_000;
+            if (stage === 'INVENTORY' || stale) {
+                const yes = await yesNo(confirm, {
+                    id: 'journey-look',
+                    title: LOOK_TITLE,
+                    facts: [
+                        ...(stale ? [`The last inventory is from ${shownTime(inv.takenAt)}.`] : []),
+                        'Reads packages, objects, usage sources and the caller index.',
+                        'About 2 minutes.',
+                        'Writes nothing to SAP.',
+                        'Saves the inventory in this folder.',
+                    ],
+                    footnote: footnote('INVENTORY'),
+                });
+                if (!yes && !stale) {
+                    end(h, NOTHING_READ_LINE);
+                    return;
+                }
+                if (yes)
+                    runAs = 'INVENTORY';
+                else {
+                    h.emit(`Using the inventory from ${shownTime(inv.takenAt)}.`);
+                    saidInventory = true;
+                }
+            }
+            else if (inv && !saidInventory) {
+                h.emit(`I took an inventory of ${inv.sid ?? h.sapAlias ?? 'the system'} at ${shownTime(inv.takenAt)}.`);
+                saidInventory = true;
+            }
+            // Step 2 — "Start the project here?", when the named packages are ones the system has.
+            if (runAs === 'START') {
+                const scope = startScope(h.cwd, flow.packages);
+                if (scope) {
+                    const n = scope.objects;
+                    const yes = await yesNo(confirm, {
+                        id: 'journey-start',
+                        title: START_TITLE,
+                        facts: [
+                            `${plural(n, 'object', 'objects')} in ${scope.names.join(', ')} in the inventory.`,
+                            "The start checks this against SAP's own count.",
+                            `First check: ${aboutMinutes(n)}.`,
+                            'Saved in this folder.',
+                            // Recording fix 5: the name every record is written under, seen before anything is written.
+                            `You: ${shown(me)}.`,
+                            `You own all ${n.toLocaleString('en-US')}.`,
+                            'Writes nothing to SAP.',
+                        ],
+                        footnote: footnote('START'),
+                    });
+                    if (!yes) {
+                        end(h, NOT_STARTED_LINE);
+                        return;
+                    }
+                }
+            }
+            // Step 4 — "Fix <NAME> now?".
+            if (runAs === 'FIX' && facts.register) {
+                // A name that is not an ABAP name never reaches a card or a command: one line, passed over.
+                const bad = toFix(facts.register, me, skips).filter((o) => refactorCommand({ type: o.type, name: o.name }) === null);
+                if (bad.length) {
+                    for (const o of bad)
+                        h.emit(passedOverLine(o.name));
+                    addJourneySkips(h.session, { fix: new Set(bad.map((o) => o.key)) });
+                    continue;
+                }
+                const pick = await fixCard(confirm, toFix(facts.register, me, skips), skips, (o) => stillOpenLines(o.key));
+                if (pick.kind === 'cancel') {
+                    pause(h, stepOf('FIX'));
+                    return;
+                }
+                if (pick.kind === 'later') {
+                    addJourneySkips(h.session, { fix: new Set([pick.object.key]) });
+                    h.emit(`${pick.object.name.toUpperCase()}: left for later.`);
+                    continue;
+                }
+                if (pick.kind === 'yes')
+                    runSkips = pick.skips;
+            }
+            // Step 3, from the second page on — "Next 40? [Yes] [Later]".
+            if (runAs === 'DECIDE' && facts.register && (getJourneyFlow(h.session)?.pages ?? 0) > 0) {
+                const left = toDecide(facts.register, me, skips);
+                const next = decidePage(facts.register, me, skips).length;
+                const res = await confirm({
+                    id: 'journey-next-page',
+                    tag: 'QUESTION',
+                    title: `Next ${next.toLocaleString('en-US')}?`,
+                    facts: [`${plural(left.length, 'object', 'objects')} left to decide.`],
+                    choices: [{ value: 'yes', label: 'Yes' }, { value: 'later', label: 'Later' }],
+                    initial: 0,
+                    aliases: { y: 'yes', l: 'later' },
+                    footnote: footnote('DECIDE'),
+                });
+                if (res.cancelled || res.value === null) {
+                    pause(h, stepOf('DECIDE'));
+                    return;
+                }
+                if (res.value === 'later') {
+                    // Left out, not skipped: "carry on" brings them back to deciding.
+                    addJourneyLeftOut(h.session, left.map((o) => o.key));
+                    h.emit('Left for later.');
+                    continue;
+                }
+            }
+        }
+        const r = await runJourneyStage(runAs, {
+            cwd: h.cwd, team, headless: h.headless, skips: runSkips, packages: flow.packages,
+            ...(h.openFile ? { openFile: h.openFile } : {}),
+        });
+        if (runAs === 'INVENTORY')
+            ranInventory = true;
+        for (const line of r.lines)
+            h.emit(line);
+        addJourneySkips(h.session, r.skip);
+        if (r.next.kind === 'continue') {
+            if (runAs !== stage)
+                previous = ''; // a fresh inventory is progress
+            continue;
+        }
+        if (r.next.kind === 'queue') {
+            const command = r.next.command;
+            if (!h.queueNext) {
+                end(h, `Next: ${command}`);
+                return;
+            }
+            const skill = /^\/(\S+)/.exec(command)[1];
+            if (runAs === 'DECIDE') {
+                setJourneyQueued(h.session, { command, skill, stage: 'DECIDE', left: facts.register ? toDecide(facts.register, me, skips).length : 0 });
+                // The page the triage is shown (team_findings reads it): at most 40, in the queued area.
+                setJourneyPage(h.session, facts.register ? decidePage(facts.register, me, skips).map((o) => o.key) : []);
+            }
+            else {
+                const key = r.next.key;
+                setJourneyQueued(h.session, { command, skill, stage: 'FIX', ...(key ? { key } : {}), callsAt: toolCallsOf(h.session).length, variant: projectVariant(h.cwd) });
+            }
+            h.queueNext(command);
+            return;
+        }
+        end(h); // stop or done: the runner said its last words
+        return;
+    }
+    pause(h);
+}
+/**
+ * runTurn's post-turn hook. A turn of the queued step's skill that moved
+ * nothing and ends on a question waits for the reply; one that moved nothing
+ * otherwise pauses the chain; anything that moved goes on.
+ */
+export async function afterJourneyTurn(h, t) {
+    const q = getJourneyFlow(h.session)?.queued;
+    if (!q || t.skill !== q.skill || t.awaitingAnswer)
+        return;
+    if (h.headless) {
+        end(h);
+        return;
+    }
+    const team = await teamFor(h);
+    const me = whoAmI(team.deps);
+    const skips = journeySkips(h.session);
+    const facts = readJourneyFacts(h.cwd, me, skips);
+    const stage = stageOf(facts);
+    let moved = stage !== q.stage;
+    if (!moved && facts.register && q.stage === 'DECIDE')
+        moved = toDecide(facts.register, me, skips).length < (q.left ?? Number.MAX_SAFE_INTEGER);
+    if (!moved && facts.register && q.stage === 'FIX')
+        moved = !toFix(facts.register, me).some((o) => o.key === q.key);
+    if (!moved) {
+        if (/\?\s*$/.test(t.assistantText.trim()))
+            return;
+        if (q.stage !== 'FIX' || !q.key) {
+            pause(h, stepOf(q.stage));
+            return;
+        }
+        // Recording fix 3b: a retry of a fix that failed the check ended with
+        // nothing recorded. "Left for later" alone hid what was still open: one
+        // card says it and asks what to do.
+        const o = facts.register?.objects.find((x) => x.key === q.key);
+        if (o && fixFailedCheck(o) && !claimedSinceCheck(o)) {
+            setJourneyQueued(h.session, undefined);
+            const goOn = await retryCard(h, team, o);
+            if (!goOn)
+                return;
+            try {
+                await drive(h);
+            }
+            catch (e) {
+                end(h);
+                throw e;
+            }
+            return;
+        }
+        // The refactor ended with no fix recorded (the approval card declined, or
+        // nothing written): never the same object again this session — one line,
+        // then the next fix or the next step.
+        const name = q.key.slice(q.key.indexOf('|') + 1).toUpperCase();
+        const written = cspeachWritesThisSession(toolCallsOf(h.session).slice(q.callsAt ?? 0)).has(name);
+        addJourneySkips(h.session, { fix: new Set([q.key]) });
+        h.emit(written ? `${name}: no fix was recorded — left for later.` : `${name} was not changed — left for later.`);
+    }
+    setJourneyQueued(h.session, undefined);
+    try {
+        await drive(h);
+    }
+    catch (e) {
+        end(h);
+        throw e;
+    }
+}
+/**
+ * After a retry that recorded nothing: "<NAME> still has <n> open findings."
+ * [Try another fix] queues the refactor of the same object again; [Keep as is]
+ * asks "Why keep it?" and records an accepted exception at its level with that
+ * reason — the record the row card's Keep as is writes (team decide <T> <N>
+ * exception --level <L> --reason "…"); [Later] puts it off for this session.
+ * Returns true when the chain goes on from the folder (drive), false when it
+ * stopped or a command was queued.
+ */
+async function retryCard(h, team, o) {
+    const name = o.name.toUpperCase();
+    const type = o.type.toUpperCase();
+    const level = o.decision?.level && LEVEL.test(o.decision.level) ? o.decision.level : undefined;
+    const n = o.openFindings ?? 0;
+    const ask = h.ask ?? journeyAsk();
+    for (let tries = 0; tries < 5; tries++) {
+        const res = await team.confirm({
+            id: 'journey-retry',
+            tag: 'QUESTION',
+            title: `${name} still has ${plural(n, 'open finding', 'open findings')}.`,
+            facts: [...stillOpenLines(o.key), 'CSPeach asks before it writes to SAP.'],
+            choices: [
+                { value: 'again', label: 'Try another fix' },
+                ...(level ? [{ value: 'keep', label: 'Keep as is' }] : []),
+                { value: 'later', label: 'Later' },
+            ],
+            initial: 0,
+            aliases: { t: 'again', ...(level ? { k: 'keep' } : {}), l: 'later' },
+            footnote: footnote('FIX'),
+            wrapFacts: FACT_ROWS_BESIDE_OPEN,
+        });
+        if (res.cancelled || res.value === null) {
+            pause(h, stepOf('FIX'));
+            return false;
+        }
+        if (res.value === 'later') {
+            addJourneySkips(h.session, { fix: new Set([o.key]) });
+            h.emit(`${name}: left for later.`);
+            return true;
+        }
+        if (res.value === 'again') {
+            const command = refactorCommand({ type: o.type, name: o.name, ...(o.decision?.reason ? { reason: o.decision.reason } : {}) });
+            if (!command) {
+                addJourneySkips(h.session, { fix: new Set([o.key]) });
+                h.emit(passedOverLine(o.name));
+                return true;
+            }
+            if (!h.queueNext) {
+                end(h, `Next: ${command}`);
+                return false;
+            }
+            h.emit(`Step ${stepOf('FIX')} of ${STEPS} — fix ${name} again.`);
+            setJourneyQueued(h.session, { command, skill: 'abap-refactor', stage: 'FIX', key: o.key, callsAt: toolCallsOf(h.session).length, variant: projectVariant(h.cwd) });
+            h.queueNext(command);
+            return false;
+        }
+        if (res.value === 'keep' && level) {
+            let said;
+            try {
+                said = await ask(KEEP_QUESTION);
+            }
+            catch {
+                pause(h, stepOf('FIX'));
+                return false;
+            }
+            const reason = cleanKeepReason(said);
+            if (!reason) {
+                h.emit(`A keep needs a reason. Nothing was recorded for ${type} ${name} yet.`);
+                continue;
+            }
+            team.said.length = 0;
+            const code = await runTeamCommand(['decide', type, name, 'exception', '--level', level, '--reason', reason], team.deps).catch(() => 1);
+            if (code !== 0) {
+                const why = team.said.find((l) => l.startsWith('✗'))?.replace(/^✗\s*/, '') ?? '';
+                h.emit(notRecordedLine(new Error(why || 'the record could not be written to this folder')));
+                addJourneySkips(h.session, { fix: new Set([o.key]) });
+                return true;
+            }
+            h.emit(`✓ Recorded: ${shown(type)} ${shown(name)} — kept at ${level}, reason recorded.`);
+            return true;
+        }
+    }
+    addJourneySkips(h.session, { fix: new Set([o.key]) });
+    h.emit(`${name}: left for later.`);
+    return true;
+}
+/**
+ * The queued step's turn was interrupted (Ctrl-C, a dropped stream): the
+ * journey pauses, so "carry on" picks it up on the first try. Returns the
+ * line to say, or undefined when no journey step was running.
+ */
+export function pauseJourneyForInterruptedTurn(session) {
+    const q = getJourneyFlow(session)?.queued;
+    if (!q)
+        return undefined;
+    pauseJourneyFlow(session);
+    return PAUSED_LINE(stepOf(q.stage));
+}
+/* ── the queued triage turn's prompt ────────────────────────────────────── */
+/**
+ * Final fix wave, ruling 3 — the "no commands" note in the turn's own prompt
+ * (the skill treats tool strings as data, so the team_findings note alone is
+ * not enough; it stays as belt-and-braces).
+ */
+export const JOURNEY_TURN_BLOCK = [
+    '<journey>',
+    "This triage is one step of CSPeach's guided clean-core run.",
+    'Do not suggest any cspeach command, and do not use the words team or lane.',
+    'After your table, CSPeach asks the person about each row, row by row.',
+    'End with the table and the manifest. No closing instructions.',
+    '</journey>',
+].join('\n');
+/**
+ * The check variant the journey proves a fix with (step 5): the project's own,
+ * else the one a project is started with. Never anything that is not a
+ * variant name — it goes into the model's prompt.
+ */
+export function projectVariant(cwd) {
+    let v = '';
+    try {
+        v = (readProjectFile(cwd).atcVariant ?? '').trim().toUpperCase();
+    }
+    catch {
+        v = '';
+    }
+    return VARIANT_NAME.test(v) ? v : DEFAULT_ATC_VARIANT;
+}
+/**
+ * Recording fix 3 (2026-10-07) — the queued fix turn checked with ATC's
+ * DEFAULT variant and said done, while the journey's proof uses the project's
+ * variant and found the fix had failed. The turn's own prompt now names that
+ * variant and when the fix is done.
+ */
+export function journeyFixBlock(variant) {
+    const v = VARIANT_NAME.test(variant) ? variant : DEFAULT_ATC_VARIANT;
+    return [
+        '<journey>',
+        "This fix is one step of CSPeach's guided clean-core run.",
+        `The project's check variant is ${v}.`,
+        `After you activate the object, run ATC on it with the variant ${v}, not the default one.`,
+        `The fix is done only when ${v} shows no findings for the object.`,
+        'If findings remain, fix them and check again. For example: do not type parameters with fields of views SAP has not released; use released data elements and classes.',
+        'Do at most 2 more rounds. Then say plainly what is still open.',
+        'Do not suggest any cspeach command, and do not use the words team or lane.',
+        '</journey>',
+    ].join('\n');
+}
+/**
+ * The block for the queued DECIDE triage turn, and for the queued FIX
+ * refactor turn; '' on every other turn (the prompt stays as it was).
+ */
+export function journeyTurnBlock(session, skill) {
+    const q = getJourneyFlow(session)?.queued;
+    if (q?.stage === 'DECIDE' && skill === 'abap-clean-core')
+        return JOURNEY_TURN_BLOCK;
+    if (q?.stage === 'FIX' && skill === 'abap-refactor')
+        return journeyFixBlock(q.variant ?? DEFAULT_ATC_VARIANT);
+    return '';
+}
+/* ── the gate ───────────────────────────────────────────────────────────── */
+const norm = (s) => s.trim().replace(/\s+/g, ' ');
+/**
+ * At the top of every top-level turn. The journey survives only its own step:
+ * the exact command it queued, or a plain reply that stays in that step's
+ * skill. Anything else — another slash command, a reply routed elsewhere —
+ * ends the chain: `line` is the one thing to say (interactive only).
+ */
+export function gateJourneyForTurn(session, t) {
+    const flow = getJourneyFlow(session);
+    if (!flow)
+        return { ended: false };
+    const q = flow.queued;
+    if (q) {
+        if (t.explicitSlash && norm(`/${t.skill} ${t.userMessage}`) === norm(q.command))
+            return { ended: false };
+        if (!t.explicitSlash && t.skill === q.skill && t.previousSkill === q.skill)
+            return { ended: false };
+    }
+    // The stray message is pushed after this gate: count it as seen, so "carry
+    // on" right after its answer resumes, as the pause line says.
+    pauseJourneyFlow(session, 1);
+    return { ended: true, line: PAUSED_LINE(q ? stepOf(q.stage) : undefined) };
+}