@cspeach/cli 1.1.22 → 1.1.24

package/dist/tools/cap/service-catalog.js

@@ -0,0 +1,248 @@
+// cspeach-cli/src/tools/cap/service-catalog.ts
+//
+// CAP phase 2, Task 9 — `sap_service_catalog`: list the OData services ACTIVE on
+// the connected SAP system, from the Gateway V2 and V4 catalogs. The design
+// step uses it to map a spec's S/4 data to a service that really exists.
+//
+// Read-only: the only requests are GETs to V2_CATALOG_BASE and V4_CATALOG_URL.
+// Field names follow the real S4H captures (probe note P3, fixtures/catalog-*.json):
+// - V2: on that box `TechnicalServiceName` is Z-prefixed (ZAPI_…) while
+//   `ServiceUrl` (absolute) ends in the real name, so the name comes from the
+//   last ServiceUrl segment (matrix `;v=..` ignored), then Title, then
+//   TechnicalServiceName.
+// - V4: `ServiceUrl` is RELATIVE and carries `?sap-client=…`; the query is dropped.
+import { registerTool } from '../index.js';
+import { loadConfig } from '../../config/loader.js';
+import { PlainFetchError, plainSapFetchError } from './_fetch-errors.js';
+const V2_CATALOG_BASE = '/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/ServiceCollection?$format=json' +
+    '&$select=ID,TechnicalServiceName,TechnicalServiceVersion,Title,ServiceUrl';
+export const V4_CATALOG_URL = '/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0002/ServiceGroups?$expand=DefaultSystem($expand=Services)';
+/** V2 page size and the safety cap on pages (321 `API_` services on S4H → 4 pages). */
+export const V2_PAGE_SIZE = 100;
+export const V2_MAX_PAGES = 20;
+const DEFAULT_MAX = 50;
+const MAX_MAX = 500;
+const SEARCH_MAX_LEN = 60;
+const SEARCH_RE = /^[A-Za-z0-9_ /-]*$/;
+/** Pathname of an absolute or relative URL: no scheme, host, port, query or fragment; no trailing slash. */
+function pathOf(u) {
+    try {
+        return new URL(u, 'http://catalog.invalid').pathname.replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Last path segment, matrix parameters (`;v=0002`) removed. */
+function lastSegment(p) {
+    const seg = p.split('/').pop() ?? '';
+    return seg.split(';')[0] ?? '';
+}
+/** One row, one line: SAP-supplied text loses control characters (tabs, newlines, ESC). */
+// eslint-disable-next-line no-control-regex
+const oneLine = (s) => String(s ?? '').replace(/[\u0000-\u001F\u007F]+/g, ' ').replace(/\s+/g, ' ').trim();
+const str = (v) => (typeof v === 'string' ? v : '');
+/**
+ * The V2 catalog URL for one page. `search` is escaped for an OData string
+ * literal (single quotes doubled) and percent-encoded; `$` stays literal the way
+ * sap_odata_test does. The handler validates the term before it gets here.
+ */
+export function v2CatalogUrl(search, skip = 0) {
+    let url = `${V2_CATALOG_BASE}&$top=${V2_PAGE_SIZE}&$skip=${Math.max(0, Math.floor(skip))}`;
+    if (search) {
+        const filter = `substringof('${search.replace(/'/g, "''")}',TechnicalServiceName)`;
+        url += `&$filter=${encodeURIComponent(filter)}`;
+    }
+    return url;
+}
+export function parseV2Catalog(json) {
+    return parseV2Page(json).rows;
+}
+/** Rows plus the raw result count; paging decides on the raw count, not the kept rows. */
+function parseV2Page(json) {
+    const d = JSON.parse(json);
+    const results = Array.isArray(d?.d?.results) ? d.d.results : [];
+    const out = [];
+    for (const r of results) {
+        if (!r || typeof r !== 'object')
+            continue;
+        const servicePath = pathOf(str(r.ServiceUrl));
+        if (!servicePath || !servicePath.startsWith('/sap/opu/odata/'))
+            continue;
+        const name = lastSegment(servicePath) || str(r.Title) || str(r.TechnicalServiceName);
+        if (!name)
+            continue;
+        const v = r.TechnicalServiceVersion;
+        out.push({
+            name: oneLine(name),
+            version: v === undefined || v === null || v === '' ? '' : oneLine(v).padStart(4, '0'),
+            title: oneLine(r.Title),
+            servicePath,
+            odata: 'v2',
+        });
+    }
+    return { rows: out, raw: results.length };
+}
+export function parseV4Catalog(json) {
+    const d = JSON.parse(json);
+    const groups = Array.isArray(d?.value) ? d.value : [];
+    const out = [];
+    for (const g of groups) {
+        const sys = g?.DefaultSystem;
+        const services = Array.isArray(sys?.Services) ? sys.Services : [];
+        for (const s of services) {
+            if (!s || typeof s !== 'object')
+                continue;
+            const servicePath = pathOf(str(s.ServiceUrl));
+            if (!servicePath || !servicePath.startsWith('/sap/opu/odata4/'))
+                continue;
+            const name = str(s.ServiceId);
+            if (!name)
+                continue;
+            out.push({
+                name: oneLine(name),
+                version: oneLine(s.ServiceVersion),
+                title: oneLine(str(s.Description) || str(g.GroupId)),
+                servicePath,
+                odata: 'v4',
+            });
+        }
+    }
+    return out;
+}
+export async function sapServiceCatalogHandler(args, ctx, deps = {}) {
+    const rawSearch = typeof args.search === 'string' ? args.search.trim() : '';
+    if (rawSearch.length > SEARCH_MAX_LEN) {
+        return { content: `The search term is too long. Use at most ${SEARCH_MAX_LEN} characters.`, is_error: true };
+    }
+    if (!SEARCH_RE.test(rawSearch)) {
+        return {
+            content: 'The search term may only use letters, digits, underscore, space, slash and hyphen.',
+            is_error: true,
+        };
+    }
+    const want = args.version ?? 'both';
+    if (want !== 'v2' && want !== 'v4' && want !== 'both') {
+        return { content: 'version must be "v2", "v4" or "both".', is_error: true };
+    }
+    const n = Number(args.max);
+    const max = Number.isFinite(n) && n >= 1 ? Math.min(Math.floor(n), MAX_MAX) : DEFAULT_MAX;
+    const term = rawSearch.toLowerCase();
+    const get = deps.get ?? (async (p) => {
+        const { getConnection } = await import('../../sap/connection-manager.js');
+        const cfg = await loadConfig();
+        const sys = cfg.sap[ctx.sapAlias];
+        if (!sys)
+            throw new PlainFetchError(`No SAP system "${ctx.sapAlias}" is configured.`);
+        try {
+            const conn = await getConnection(ctx.sapAlias, sys);
+            const r = await conn.get(p, 'application/json');
+            return { status: r.status, body: r.body };
+        }
+        catch (err) {
+            // Never the raw message: connection errors can carry headers, cookies or the user name.
+            // An empty fallback lets fetchRows use its own per-catalog sentence.
+            throw new PlainFetchError(plainSapFetchError(err, ctx.sapAlias, sys.host, sys.port, ''));
+        }
+    });
+    const matches = (x) => !term || x.name.toLowerCase().includes(term) || x.title.toLowerCase().includes(term);
+    /** One GET → rows, or a plain one-line error. Never echoes the answer body or a stack. */
+    const fetchRows = async (label, url, parse) => {
+        let r;
+        try {
+            r = await get(url);
+        }
+        catch (err) {
+            // Only a PlainFetchError's own fixed line is shown; anything else gets a fixed sentence.
+            if (err instanceof PlainFetchError && err.message)
+                return err.message;
+            return `${label} catalog could not be read from ${ctx.sapAlias}. Check the SAP login for this system and try again.`;
+        }
+        if (r.status !== 200)
+            return `${label} catalog answered HTTP ${r.status}.`;
+        try {
+            return parse(r.body);
+        }
+        catch {
+            return `${label} catalog answer was not JSON.`;
+        }
+    };
+    const out = [];
+    const notes = [];
+    const errors = [];
+    const emit = (rows) => {
+        for (const x of rows)
+            out.push(`${x.servicePath}\t${x.name}\t${x.odata}\t${x.version}\t${x.title}`);
+    };
+    if (want !== 'v4') {
+        // The server filter matches TechnicalServiceName, which is upper case (and
+        // Z-prefixed on some boxes, e.g. ZAPI_…); substringof still finds the name.
+        const serverTerm = rawSearch ? rawSearch.toUpperCase() : undefined;
+        const rows = [];
+        let page = 0;
+        let failed = false;
+        let lastFull = false;
+        while (page < V2_MAX_PAGES && rows.length < max) {
+            const res = await fetchRows('V2', v2CatalogUrl(serverTerm, page * V2_PAGE_SIZE), parseV2Page);
+            page++;
+            if (typeof res === 'string') {
+                errors.push(res);
+                failed = true;
+                break;
+            }
+            rows.push(...res.rows.filter(matches));
+            lastFull = res.raw >= V2_PAGE_SIZE;
+            if (!lastFull)
+                break;
+        }
+        if (!failed && page >= V2_MAX_PAGES && lastFull && rows.length < max) {
+            notes.push(`Stopped after ${V2_MAX_PAGES} pages of the V2 catalog. The V2 list may be incomplete; narrow the search.`);
+        }
+        if (rows.length > max)
+            notes.push(`V2: showing the first ${max}. Narrow the search or raise max.`);
+        emit(rows.slice(0, max));
+    }
+    if (want !== 'v2') {
+        const res = await fetchRows('V4', V4_CATALOG_URL, parseV4Catalog);
+        if (typeof res === 'string')
+            errors.push(res);
+        else {
+            const rows = res.filter(matches);
+            if (rows.length > max)
+                notes.push(`V4: showing the first ${max} of ${rows.length}. Narrow the search or raise max.`);
+            emit(rows.slice(0, max));
+        }
+    }
+    const content = [
+        'PATH\tNAME\tODATA\tVERSION\tTITLE',
+        ...out,
+        `(${out.length} active services${rawSearch ? ` matching "${rawSearch}"` : ''}. Active means registered in the ` +
+            'Gateway catalog. Release state is separate; check it before you use a service.)',
+        ...notes,
+        ...[...new Set(errors)], // one reach line, not one per catalog
+    ].join('\n');
+    return { content, ...(out.length === 0 && errors.length ? { is_error: true } : {}) };
+}
+registerTool({
+    name: 'sap_service_catalog',
+    description: 'List OData services ACTIVE on the connected SAP system (Gateway catalog, V2 and V4): path, service name, ' +
+        'OData version, service version, title. Use it in design to map a spec\'s S/4 data to a service that really ' +
+        'exists on this system. Active is not the same as released: check release state separately. Read-only.',
+    isMutating: false,
+    requiresSap: true,
+    // R25: visible only with local_build on (the CAP lane already needs it), so
+    // the tool list of non-CAP users stays unchanged.
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            search: {
+                type: 'string',
+                description: 'Part of the service name or title, e.g. "BUSINESS_PARTNER". Letters, digits, _ space / - only; max 60.',
+            },
+            version: { type: 'string', enum: ['v2', 'v4', 'both'], description: 'Which catalog to read. Default both.' },
+            max: { type: 'number', description: 'Rows per catalog, default 50, max 500.' },
+        },
+    },
+    handler: (args, ctx) => sapServiceCatalogHandler(args, ctx),
+});

package/dist/tools/fiori/preview/registry.js

@@ -56,6 +56,7 @@ import * as net from 'node:net';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { KILL_GRACE_MS } from '../../_command-shared.js';
+import { registerShutdownHook } from '../../../lib/shutdown-hooks.js';
 /** appDirKey → tracked preview. At most one per directory, by construction. */
 const registry = new Map();
 /**
@@ -108,7 +109,7 @@ export function childIsLive(child) {
     return !!child && child.exitCode === null && child.signalCode === null;
 }
 /** A pid we are allowed to signal. 0 = own group / idle process, 1 = everything. */
-function killablePid(pid) {
+export function killablePid(pid) {
     return typeof pid === 'number' && Number.isInteger(pid) && pid > 1;
 }
 export function registerPreview(e, child) {
@@ -340,15 +341,30 @@ export async function stopPreview(previewId) {
     const portClosed = await waitForPortClosed(port);
     return { stopped: true, portClosed, port, ...outcome };
 }
+/**
+ * Windows only: kill `pid` and every descendant SYNCHRONOUSLY with the absolute
+ * taskkill (`/T /F`), minimal env, cwd = tmpdir. Safe inside `process.on('exit')`.
+ * The CALLER owns the identity rule — call it only for a live child handle this
+ * process holds, and with `killablePid(pid)` true. Shared with the background
+ * registry (subagent/_background-shared.ts).
+ *
+ * Returns true when taskkill ran and reported success — exit 0, or 128 ("no such
+ * process": already gone). spawnSync never throws; a spawn failure or timeout
+ * shows up as `error`, and the caller decides on a fallback.
+ */
+export function taskkillTreeSync(pid) {
+    const r = spawnSync(TASKKILL, ['/PID', String(pid), '/T', '/F'], {
+        windowsHide: true,
+        stdio: 'ignore',
+        cwd: os.tmpdir(),
+        env: TASKKILL_ENV,
+        timeout: TASKKILL_TIMEOUT_MS,
+    });
+    return !r.error && (r.status === 0 || r.status === 128);
+}
 function realSyncKill(pid) {
     if (process.platform === 'win32') {
-        spawnSync(TASKKILL, ['/PID', String(pid), '/T', '/F'], {
-            windowsHide: true,
-            stdio: 'ignore',
-            cwd: os.tmpdir(),
-            env: TASKKILL_ENV,
-            timeout: TASKKILL_TIMEOUT_MS,
-        });
+        taskkillTreeSync(pid);
     }
     else {
         process.kill(-pid, 'SIGTERM');
@@ -381,22 +397,12 @@ export function installPreviewExitHandler() {
     if (exitHandlerInstalled)
         return;
     exitHandlerInstalled = true;
-    process.on('exit', killAllPreviewsSync);
-    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-        // PREPEND: ui/alt-screen.ts re-raises with process.kill(process.pid, sig),
-        // which on Windows is an immediate TerminateProcess — a listener appended
-        // after it would never run, and 'exit' would never fire either.
-        process.prependListener(sig, () => {
-            killAllPreviewsSync();
-            // In one-shot/classic mode ours may be the ONLY listener, and merely
-            // having one removes Node's default exit-on-signal. Re-raise so Ctrl+C
-            // still stops the CLI.
-            if (process.listenerCount(sig) === 1) {
-                process.removeAllListeners(sig);
-                process.kill(process.pid, sig);
-            }
-        });
-    }
+    // One shared exit/signal handler for every managed resource (Task 8 fix
+    // round 1, I-1): it runs on 'exit' and on SIGINT/SIGTERM/SIGHUP (prepended,
+    // so ui/alt-screen.ts's re-raise cannot pre-empt it), and re-raises when every
+    // remaining listener is its own. Two registries with their own prepended
+    // listeners each saw a count of 2 and nobody re-raised — Ctrl+C hung.
+    registerShutdownHook(killAllPreviewsSync);
 }
 export function __resetPreviewRegistryForTests() {
     registry.clear();

package/dist/tools/lane/app-lane-resolve.js

@@ -0,0 +1,329 @@
+// cspeach-cli/src/tools/lane/app-lane-resolve.ts
+//
+// App lane routing, slice 1, Task 5 — `app_lane_resolve`. The model fills the
+// signal sheet (values + evidence quotes); everything else is CLI code:
+//
+//   sheet check → spec text + quote strength → system facts, pin, standards
+//   → resolveLane → lane card (or the headless STOP) → runtime card when a CAP
+//   lane has no runtime → sha-pinned decision file → app-flow state → the CLI
+//   queues `/abap-plan --from @<specGap>` through the harness slot.
+//
+// Security posture:
+// - The sheet is validated with the strict schema before anything else runs;
+//   errors name only the bad keys (sanitised), never values.
+// - The spec path goes through readSpecText (string + realpath containment,
+//   denylist, size caps). Errors name the path only, never spec content.
+// - Card strings come from card.ts (sanitised, capped). STOP / summary text
+//   passes every model-influenced line through cardLine.
+// - The decision file is written only by store.ts (validated, never overwrites).
+// - The runtime answer is written only by writeRuntimeAnswer, from a card value.
+// - pendingDispatch gets a CLI-built string only: a fixed prefix plus the
+//   session's spec-gap path, through the shared chainFromToken (lane/chain-token.ts).
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool, isStandalone } from '../index.js';
+import { PathOutsideRootError } from '../_filesystem-shared.js';
+import { assertNotCliHome, containSpecPath, laneRootFor, specDisplayPath } from '../../lane/roots.js';
+import { signalSheetSchema, withStrength } from '../../lane/signals.js';
+import { factsFromStandalone, factsFromSystemInfo, findQuote, readLanePin, readSpecText, readStandardsLane, writeRuntimeAnswer, } from '../../lane/inputs.js';
+import { BUILT_LANES, resolveLane, uiFor } from '../../lane/resolve.js';
+import { writeLaneDecision } from '../../lane/store.js';
+import { getAppFlow, setLane } from '../../lane/app-flow.js';
+import { chainFromToken } from '../../lane/chain-token.js';
+import { cardLine, interactiveRunLine, laneCardRequest, quoteNotFoundFacts, runtimeCardRequest, shownToken, } from '../../lane/card.js';
+import { cardSlotEmitter } from '../../ui/card-slot.js';
+import { askConfirm } from '../../ui/confirm-request.js';
+import { isHeadless } from '../../renderer/tty.js';
+import { loadConfig } from '../../config/loader.js';
+import { getSapSystemInfo } from '../../sap/system-info.js';
+const fail = (message) => ({ content: `error: ${message}`, is_error: true });
+const NOT_CHOSEN = 'Lane not chosen. Nothing was saved.';
+const STOP = 'STOP — lane needs your choice.';
+const UNKNOWN_FACTS = { source: 'unknown', tier: 'unknown', label: 'unknown' };
+const RUNTIMES = ['btp', 'own-server', 'none'];
+/** A sheet key for an error line: identifier characters only, capped. */
+const keyName = (k) => String(k).replace(/[^A-Za-z0-9_]/g, '').slice(0, 40) || '(unnamed)';
+function sheetError(issues) {
+    const bad = new Set();
+    let notObject = false;
+    for (const i of issues) {
+        if (i.code === 'unrecognized_keys' && i.path.length === 0) {
+            for (const k of i.keys ?? [])
+                bad.add(`${keyName(k)} (unknown key)`);
+        }
+        else if (i.path.length === 0) {
+            notObject = true;
+        }
+        else {
+            bad.add(keyName(i.path[0]));
+        }
+    }
+    if (notObject && bad.size === 0)
+        return 'signals must be an object with one entry per signal key.';
+    return `the signal sheet is not valid. Fix these keys and call again: ${[...bad].join(', ')}.`;
+}
+async function defaultFacts(ctx) {
+    try {
+        if (isStandalone(ctx)) {
+            return factsFromStandalone((await loadConfig()).standalone);
+        }
+        return factsFromSystemInfo(await getSapSystemInfo(ctx.adt, ctx.sapAlias));
+    }
+    catch {
+        return { ...UNKNOWN_FACTS };
+    }
+}
+/** Headless, or no Ink card slot (classic REPL / one-shot): a card could never be answered. */
+function defaultHeadless() {
+    return isHeadless() || cardSlotEmitter.listenerCount('confirm') === 0;
+}
+/** M1 — a person is at the terminal but no card can be shown (the classic REPL). */
+function defaultNoCardTerminal() {
+    return !isHeadless() && cardSlotEmitter.listenerCount('confirm') === 0;
+}
+/**
+ * True when the app flow's `@spec` token and the given absolute path are the
+ * same real file inside cwd or the workspace folder (I3: the same containment
+ * as readSpecText).
+ */
+async function sameFile(cwd, token, abs) {
+    const tok = token.trim().replace(/^@/, '');
+    if (tok === '')
+        return false;
+    try {
+        const { real: a } = await containSpecPath(cwd, tok);
+        const b = await fs.realpath(abs);
+        const norm = (p) => (process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p));
+        return norm(a) === norm(b);
+    }
+    catch {
+        return false;
+    }
+}
+const LANE_WORDS = {
+    rap: 'on-stack RAP', cap: 'CAP (side-by-side)', none: 'UI only', 'abap-report': 'classic report', segw: 'SEGW',
+};
+function stopText(d, extra, specLine) {
+    const lines = [STOP, specLine];
+    if (d.needsRuntime && !d.neutral && !d.noAppLane) {
+        lines.push(`Recommended lane: ${LANE_WORDS.cap}. The CAP lane needs to know where the app will run.`);
+    }
+    else if (d.backend && !d.noAppLane) {
+        lines.push(`Recommended lane: ${LANE_WORDS[d.backend]}.`);
+    }
+    else {
+        lines.push('No app lane is available on this system.');
+    }
+    lines.push('Why:');
+    for (const r of [...d.reasons, ...extra])
+        lines.push(`- ${cardLine(r)}`);
+    if (d.needsRuntime && !d.neutral && !d.noAppLane) {
+        lines.push('To confirm: add `[app-lane] runtime = "btp|own-server|none"` to .cspeach/conventions.toml and run /abap-app again.');
+    }
+    else if (d.backend && !d.noAppLane) {
+        lines.push(`To confirm: Add \`[app-lane] backend = "${d.backend}"\` to .cspeach/conventions.toml and run /abap-app again.`);
+    }
+    else {
+        const choices = d.allowed.filter((l) => l !== 'segw').join(', ');
+        lines.push(`To choose: add \`[app-lane] backend = "<lane>"\` (one of: ${choices}) to .cspeach/conventions.toml and run /abap-app again.`);
+    }
+    lines.push('Nothing was saved.');
+    return lines.join('\n');
+}
+export async function appLaneResolveHandler(args, ctx, deps = {}) {
+    // 0. Task 7 review round 2 — inside an /abap-app flow the lane is chosen
+    // only at the lane step (after the spec-gap save, before the plan). Nothing
+    // else runs: no card, no file, the flow and the queue stay as they are.
+    // No flow at all → today's behaviour.
+    const step = getAppFlow(ctx.session)?.expect;
+    if (step !== undefined && step !== 'lane') {
+        return fail(step === 'spec-gap'
+            ? 'the app flow is not at the lane step yet: save the spec-gap first.'
+            : 'the app flow is not at the lane step: the lane is already chosen and the plan is next.');
+    }
+    // 1. The sheet, strictly, before anything else.
+    const parsed = signalSheetSchema.safeParse(args?.signals);
+    if (!parsed.success)
+        return fail(sheetError(parsed.error.issues));
+    if (typeof args?.specPath !== 'string' || args.specPath.trim() === '') {
+        return fail('specPath must be the spec file path, relative to the workspace.');
+    }
+    const specPath = args.specPath;
+    // 2. Spec text (contained) and signal strength.
+    let spec;
+    try {
+        spec = await readSpecText(ctx.cwd, specPath);
+    }
+    catch (e) {
+        if (e instanceof PathOutsideRootError)
+            return fail('the spec path must be inside the workspace.');
+        return fail(cardLine(e instanceof Error ? e.message : 'the spec file cannot be read.'));
+    }
+    const specSha = spec.sha256;
+    const specRel = specDisplayPath(ctx.cwd, spec.abs);
+    // The lane check must use the spec /abap-app was started with: a model may
+    // not match its quotes against some other workspace file (one it just wrote).
+    const flow = getAppFlow(ctx.session);
+    if (flow && !(await sameFile(ctx.cwd, flow.specToken, spec.abs))) {
+        return fail(cardLine(`This lane check must use the spec you started /abap-app with: ${flow.specToken}`));
+    }
+    const specLine = cardLine(`Spec: ${specRel}`);
+    const signals = withStrength(parsed.data, spec.text, findQuote, spec.normalise);
+    // 3–4. Facts, pin, standards.
+    const facts = await (deps.facts ?? defaultFacts)(ctx).catch(() => ({ ...UNKNOWN_FACTS }));
+    // R18 — the project pin lives on the lane root, next to .cspeach/lane.
+    const laneRoot = await laneRootFor(ctx.cwd);
+    // Final residual 2 — a lane root that is the CLI home is refused before any read or card.
+    try {
+        await assertNotCliHome(laneRoot);
+    }
+    catch (e) {
+        return fail(cardLine(e instanceof Error ? e.message : String(e)));
+    }
+    const [pinR, stdR] = await Promise.all([readLanePin(laneRoot), readStandardsLane(ctx.cwd)]);
+    const warnings = [pinR.warning, stdR.warning].filter((w) => !!w);
+    const runtimeKnown = !!pinR.pin?.runtime || !!stdR.pin?.runtime;
+    // 5. Resolve.
+    const decision = resolveLane({ signals, facts, pin: pinR.pin, standards: stdR.pin, runtimeKnown });
+    const extraFacts = [...quoteNotFoundFacts(signals), ...warnings.map(cardLine)];
+    const cardFacts = [specLine, ...extraFacts];
+    let finalLane;
+    let decidedBy = decision.decidedBy;
+    let runtime = pinR.pin?.runtime ?? stdR.pin?.runtime;
+    const headless = (deps.headless ?? defaultHeadless)();
+    if (headless) {
+        // 6. Headless: never a card. Choices that need a person stop here.
+        if (decision.neutral || decision.noAppLane || decision.needsRuntime || !decision.backend) {
+            return { content: stopText(decision, extraFacts, specLine) };
+        }
+        finalLane = { backend: decision.backend, ui: decision.ui, ...(decision.floorplan ? { floorplan: decision.floorplan } : {}) };
+    }
+    else {
+        // 7. The lane card.
+        const confirm = deps.confirm ?? ((req) => askConfirm(req));
+        const card = laneCardRequest(decision);
+        const res = await confirm({ ...card, facts: [...(card.facts ?? []), ...cardFacts] });
+        const value = res.value;
+        const offered = new Set(card.choices.map((c) => c.value));
+        if (!value || value === 'cancel' || !offered.has(value))
+            return { content: NOT_CHOSEN };
+        if (value === 'confirm') {
+            if (!decision.backend || decision.noAppLane)
+                return { content: NOT_CHOSEN };
+            finalLane = { backend: decision.backend, ui: decision.ui, ...(decision.floorplan ? { floorplan: decision.floorplan } : {}) };
+        }
+        else {
+            const lane = value.slice('switch:'.length);
+            if (!value.startsWith('switch:') || !BUILT_LANES.includes(lane) || !decision.allowed.includes(lane)) {
+                return { content: NOT_CHOSEN };
+            }
+            const usable = (p) => (p && (!p.backend || decision.allowed.includes(p.backend)) ? p : undefined);
+            const { ui, floorplan } = uiFor(lane, signals, usable(pinR.pin)?.ui ?? usable(stdR.pin)?.ui);
+            finalLane = { backend: lane, ui, ...(floorplan ? { floorplan } : {}) };
+            decidedBy = 'developer';
+        }
+        // 8. A CAP lane needs a runtime.
+        if (finalLane.backend === 'cap' && !runtime) {
+            const rr = await confirm(runtimeCardRequest());
+            const answer = rr.value;
+            if (!answer || !RUNTIMES.includes(answer))
+                return { content: 'Runtime not chosen. Nothing was saved.' };
+            try {
+                await assertNotCliHome(laneRoot);
+                await writeRuntimeAnswer(laneRoot, answer);
+            }
+            catch (e) {
+                const why = e instanceof Error ? e.message : 'the runtime answer could not be saved';
+                return {
+                    content: `${cardLine(why)}\nThe runtime is still unknown, so the lane was not saved. Nothing was saved. ` +
+                        'Add the runtime to .cspeach/conventions.toml, then run /abap-app again.',
+                };
+            }
+            runtime = answer;
+        }
+    }
+    // 9. The decision file, the flow state, the queued plan.
+    if (finalLane.backend === 'cap' && runtime)
+        finalLane = { ...finalLane, runtime };
+    // Task 7 review R10 — the shared chain token: CLI state only (the app flow's
+    // saved spec-gap path, never a tool argument), contained to cwd or the save root.
+    const gap = flow?.specGapPath ? await chainFromToken(ctx.cwd, flow.specGapPath) : undefined;
+    const planCmd = gap ? `/abap-plan --from ${gap.token}` : undefined;
+    let written;
+    try {
+        // I3 — one lane root for the write, every pinned read and from.lane.path.
+        await assertNotCliHome(laneRoot);
+        written = await writeLaneDecision(laneRoot, {
+            spec: { path: specRel, sha256: specSha },
+            ...(gap ? { specGap: { path: gap.path } } : {}),
+            recommendation: decision,
+            final: finalLane,
+            decidedBy,
+        });
+    }
+    catch (e) {
+        return fail(`the lane decision could not be saved: ${e instanceof Error ? cardLine(e.message) : 'write failed'}`);
+    }
+    setLane(ctx.session, written.path, written.sha256, planCmd);
+    const who = decidedBy === 'developer' ? 'the developer'
+        : decidedBy === 'pin' ? `project pin (${decision.decidedByPath ?? '.cspeach/conventions.toml'})`
+            : decidedBy === 'standards' ? `standards file (${decision.decidedByPath ?? 'unknown file'})`
+                : 'the spec and the rules';
+    const ui = finalLane.ui === 'none' ? '' : ` + ${finalLane.ui}${finalLane.floorplan ? ` (${finalLane.floorplan})` : ''}`;
+    const lines = [
+        `Lane: ${finalLane.backend}${ui}${finalLane.runtime ? `, runtime ${finalLane.runtime}` : ''}.`,
+        `Decided by: ${cardLine(who)}.`,
+        `Decision file: ${written.path}`,
+    ];
+    if (warnings.length)
+        lines.push(...warnings.map((w) => `Warning: ${cardLine(w)}`));
+    // M1 — the classic REPL has no card listener, so the rules took the lane:
+    // tell the person at the terminal in one plain line (no inquirer fallback).
+    if (headless && (deps.noCardTerminal ?? defaultNoCardTerminal)()) {
+        const shown = `${finalLane.backend}${ui}${finalLane.runtime ? `, runtime ${finalLane.runtime}` : ''}`;
+        ctx.chunkEmitter?.emit('info', `Lane chosen by the rules (no confirm card in this terminal): ${shown}.`);
+    }
+    if (flow?.specGapPath && planCmd) {
+        ctx.pendingDispatch?.set(planCmd);
+        lines.push('Next: the plan is being created.');
+    }
+    else if (flow?.specGapPath && headless) {
+        // I4(c) — headless / one-shot: no flow reaches a later run.
+        lines.push(interactiveRunLine(flow.specToken));
+    }
+    else if (flow?.specGapPath) {
+        // I4(b) — the flow is at the plan step: this typed command keeps it.
+        lines.push(`The spec-gap file path could not be used to queue the plan. To go on, run: /abap-plan --from ${shownToken(path.basename(flow.specGapPath), 'spec-gap file')}`);
+    }
+    else {
+        lines.push('No spec-gap file in this session yet, so no plan was queued.');
+        if (headless)
+            lines.push(interactiveRunLine(specRel));
+    }
+    return { content: lines.join('\n') };
+}
+registerTool({
+    name: 'app_lane_resolve',
+    description: 'App lane routing for /abap-app. Pass the spec file path and the signal sheet: for each fixed key a value and, ' +
+        'when the value is true / a service name, an evidence quote copied word for word from the spec (max 300 chars). ' +
+        'The CLI checks the quotes, reads the system facts, the project pin and the standards file, picks the lane, ' +
+        'shows the lane card, saves the decision file and queues the plan. Never guess a lane yourself. ' +
+        'Keys: app_requested, ui_only_service (string|null), report_only, analytical, transactional, custom_ui, ' +
+        'cap_external_users, cap_multi_system, cap_own_release_cycle, cap_ui_on_released_api.',
+    isMutating: false,
+    requiresSap: false,
+    category: 'project',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            specPath: { type: 'string', description: 'Spec file, relative to the workspace (.md, .txt, .docx, .pdf, .xlsx).' },
+            signals: {
+                type: 'object',
+                description: 'One entry per key: { value, evidence? }. evidence = an exact quote from the spec.',
+            },
+        },
+        required: ['specPath', 'signals'],
+    },
+    handler: (args, ctx) => appLaneResolveHandler(args, ctx),
+});