@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/shell/shell_exec.js

@@ -8,11 +8,26 @@
  *   allow = ["docker", "make"]
  * block in ~/.cspeach/config.toml.
  *
- * Cross-platform: on Windows resolves the .cmd / .bat / .exe shim
- * via PATH walk before spawning (Node's spawn with shell:false can't
- * directly invoke .cmd files; using shell:true reopens shell-injection
- * + CVE-2024-27980). On Unix the bare name is passed straight through
- * — spawn finds it on PATH.
+ * Cross-platform spawn via cross-spawn (the library npm itself uses).
+ * The actual spawn is handed the ABSOLUTE PATH-resolved executable path
+ * (from resolveExecutable's PATH-only walk) + argv ARRAY. cross-spawn
+ * still inspects the file extension and, on Windows, invokes .cmd / .bat
+ * through cmd.exe with correct per-arg escaping. This satisfies Node's
+ * CVE-2024-27980 restriction (spawn with shell:false refuses to launch
+ * .cmd/.bat directly) WITHOUT ever setting shell:true — args stay an
+ * array, so shell metacharacters are inert and there is no injection
+ * surface. On Unix cross-spawn is a near-passthrough to
+ * child_process.spawn (unchanged behavior).
+ *
+ * SECURITY — why the absolute path, not the bare name: cross-spawn
+ * resolves a BARE command name cwd-FIRST on Windows (node_modules/which
+ * checks process.cwd() before PATH on win32). A model with an in-tree
+ * write primitive could plant `<safelisted>.cmd` in the project tree and
+ * have cross-spawn pick it up ahead of the real PATH binary → arbitrary
+ * code execution, safelist bypassed. Spawning the absolute PATH-resolved
+ * path (which never consults cwd/PATH for a path-bearing command) closes
+ * that vector. The pre-flight resolveExecutable() PATH walk and the spawn
+ * now use the SAME binary — no pre-flight/spawn divergence.
  *
  * Operational caps:
  *   - 30 s wall-clock timeout (overridable up to 300 s via timeout_ms arg)
@@ -24,7 +39,7 @@
  * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_SHELL_EXEC=on.
  * isMutating: true — hooks into the existing approval gate.
  */
-import { spawn } from 'node:child_process';
+import spawn from 'cross-spawn';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
@@ -80,6 +95,9 @@ export async function shellExecHandler(args, ctx) {
     catch {
         return { content: `error: cwd "${args.cwd ?? '.'}" does not exist`, is_error: true };
     }
+    // Resolve the bare safelisted name to an absolute executable path via a
+    // PATH-only walk (no cwd-first). This is BOTH the friendly "not installed"
+    // pre-flight check AND the spawn target below — same binary, no divergence.
     const resolved = await resolveExecutable(args.command);
     if (resolved === null) {
         return {
@@ -101,6 +119,23 @@ export async function shellExecHandler(args, ctx) {
             settled = true;
             resolve(result);
         };
+        // Pass the already-validated absolute `resolved` path (from
+        // resolveExecutable's PATH-only walk) — NOT the bare command name.
+        //
+        // SECURITY: cross-spawn resolves a BARE name cwd-first on Windows
+        // (node_modules/which checks process.cwd() before PATH on win32, and
+        // it chdir's into options.cwd first). A model with a write primitive
+        // could plant `<safelisted>.cmd` (e.g. git.cmd) in the project tree and
+        // have cross-spawn pick it up cwd-first → arbitrary code execution,
+        // safelist bypassed. Handing cross-spawn the absolute PATH-resolved
+        // path closes that: `which` short-circuits to the literal file when the
+        // command contains a path separator (pathEnv=['']), so cwd/PATH are
+        // never consulted. cross-spawn STILL inspects the file extension and
+        // wraps an absolute `.cmd`/`.bat` through cmd.exe with proper per-arg
+        // escaping (parse.js isExecutableRegExp only matches .com/.exe), so the
+        // Windows shim handling + CVE-2024-27980 .cmd restriction handling are
+        // preserved. shell:false stays (argv-only; metacharacters inert). The
+        // existence check above and this spawn now target the SAME binary.
         const child = spawn(resolved, argv, {
             cwd,
             env: buildSafeEnv(),

package/dist/tools/snapshot.js

@@ -14,7 +14,18 @@
  *   cleanup(retentionHours?)          → Promise<number>
  */
 import { registerTool } from './index.js';
-import { snapshots } from '@cspeach/sap-client';
+import { snapshots, SapError } from '@cspeach/sap-client';
+/** True only for a genuine ADT 404 — the object does not exist. Any other
+ *  failure (network, auth, 5xx, timeout) is a READ failure, not proof of
+ *  absence, and must never be labelled "object not found". */
+function isNotFound(err) {
+    return err instanceof SapError && err.httpStatus === 404;
+}
+/** Short single-line failure message for transcripts / error envelopes. */
+function shortErrorMessage(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.replace(/\s+/g, ' ').trim();
+}
 registerTool({
     name: 'sap_snapshot_take',
     description: "Take a snapshot of an object's current source before modification. Usually invoked automatically by the CLI before any write — rarely called directly by the model.",
@@ -28,25 +39,63 @@ registerTool({
         required: ['name', 'type'],
     },
     handler: async (args, ctx) => {
-        const source = await ctx.adt.getSource(args.type, args.name).catch(() => null);
-        if (source === null) {
-            return { content: JSON.stringify({ skipped: true, reason: 'object_not_found' }) };
+        let source;
+        try {
+            source = await ctx.adt.getSource(args.type, args.name);
+        }
+        catch (err) {
+            if (isNotFound(err)) {
+                return { content: JSON.stringify({ skipped: true, reason: 'object_not_found' }) };
+            }
+            // Read failed for some OTHER reason — the object may well exist.
+            // Claiming "object_not_found" here would be a lie; surface the failure.
+            return {
+                content: JSON.stringify({ error: 'source_read_failed', detail: shortErrorMessage(err) }),
+                is_error: true,
+            };
         }
         const entry = await snapshots.take(args.type, args.name, source, 'manual');
         return { content: JSON.stringify({ snapshot: entry, size: source.length }) };
     },
 });
-/**
- * Auto-snapshot helper called by write tools before mutating an object.
- * Silently skips if the object does not exist yet (first write after create).
- *
- * snapshots.take expects (type, name, source, reason).
- */
 export async function autoSnapshot(objectName, objectType, adt) {
-    const src = await adt.getSource(objectType, objectName).catch(() => null);
-    if (src === null)
-        return; // new object — nothing to snapshot
-    await snapshots.take(objectType, objectName, src, 'before_write');
+    let src;
+    try {
+        src = await adt.getSource(objectType, objectName);
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { taken: false, reason: 'object_not_found' }; // new object
+        // The DEFAULT read failed for a non-404 reason. Before treating this as a
+        // hard read failure (which blocks the write, Rule 7), distinguish an
+        // empty/never-activated SHELL from a real object whose source we couldn't
+        // read. A freshly-created behaviour-pool CLAS (ZBP … FOR BEHAVIOR OF …)
+        // EXISTS but has no committed source yet, so the default read returns HTTP
+        // 400 — not 404. Such a shell has NO committed ACTIVE version. Probe for one:
+        //   - active read 404      → no active version ⇒ fresh shell, nothing to
+        //                             snapshot ⇒ proceed ('new_shell').
+        //   - active read succeeds → there IS committed source to protect ⇒
+        //                             snapshot THAT active source and proceed.
+        //   - active read fails otherwise → can't confirm emptiness ⇒ conservative
+        //                             block ('source_read_failed', unchanged).
+        let activeSrc;
+        try {
+            activeSrc = await adt.getSource(objectType, objectName, 'active');
+        }
+        catch (activeErr) {
+            if (isNotFound(activeErr))
+                return { taken: false, reason: 'new_shell' };
+            // Could not confirm the object is empty — keep the safety property: a
+            // real object with source we couldn't read must still block the write.
+            return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+        }
+        // Committed active version exists — snapshot it. A snapshots.take failure
+        // still THROWS (Rule 7 hard-fail), same as the clean-read path below.
+        const activeEntry = await snapshots.take(objectType, objectName, activeSrc, 'before_write');
+        return { taken: true, entry: activeEntry };
+    }
+    const entry = await snapshots.take(objectType, objectName, src, 'before_write');
+    return { taken: true, entry };
 }
 // ── sap_snapshot_list ─────────────────────────────────────────────────────────
 registerTool({

package/dist/tools/subagent/agent_run.js

@@ -28,6 +28,7 @@
  */
 import { EventEmitter } from 'node:events';
 import { registerTool } from '../index.js';
+import { isPlanPhaseActive, notePlanPhaseSubagentDispatch, } from '../../commands/plan-gate.js';
 import { runTurn } from '../../agent/loop.js';
 import { collectTurnAssistantText } from '../../agent/turn-assistant-text.js';
 export const MAX_AGENT_DEPTH = 3;
@@ -98,12 +99,20 @@ export async function agentRunHandler(args, ctx) {
         // not parent's start time. Avoids surprising file timestamps.
         started_at: new Date().toISOString(),
         last_turn_at: new Date().toISOString(),
+        // Task 5 (ux-wave2): a fresh subagent has no task list — without this
+        // the spread above would leak the PARENT's todos into the child's
+        // session file.
+        todos: undefined,
     };
     // Build an isolated child ctx. Crucial differences vs parent ctx:
     //   - session: the fresh child session above (independent usage counters)
     //   - previewHook: undefined — subagent must NOT auto-approve writes
     //   - pendingDispatch / currentTransport: cleared — subagent doesn't
     //     mutate parent REPL state
+    //   - todoEmitter: omitted (Task 5) — todo_set emits via
+    //     ctx.todoEmitter?.emit, so a child's todo_set updates only
+    //     childSession.todos and never repaints the PARENT's Ctrl+T panel /
+    //     turn-status strip. Same seam as chunkEmitter suppression.
     // chunkEmitter is passed via the RunTurn params (not the ctx) as a
     // null-sink EventEmitter — see I2 fix below.
     const childCtx = {
@@ -113,7 +122,8 @@ export async function agentRunHandler(args, ctx) {
         cwd: ctx.cwd,
         provider: ctx.provider,
         skillSource: ctx.skillSource,
-        // previewHook + pendingDispatch + currentTransport intentionally omitted.
+        // previewHook + pendingDispatch + currentTransport + todoEmitter
+        // intentionally omitted.
     };
     // I2 fix: a null-sink EventEmitter suppresses all subagent output. Every
     // stdout-write site in loop.ts is guarded by `if (params.chunkEmitter)`,
@@ -128,9 +138,23 @@ export async function agentRunHandler(args, ctx) {
     // mutating tool from the subagent's tool list. Saves tokens on the
     // sub-agent invocation (smaller tools array = less input cost) AND
     // hard-prevents accidental writes from the subagent.
-    const toolFilter = args.read_only
+    //
+    // Task 7 (agentic-flow, 2026-07-03) — inside a plan phase the filter is
+    // FORCED regardless of args.read_only: subagents can read, never write,
+    // and the model cannot opt out (read_only:false is ignored). Outside plan
+    // phases the opt-in behaviour above is byte-identical to before.
+    const planPhase = isPlanPhaseActive();
+    const readOnly = planPhase || Boolean(args.read_only);
+    const toolFilter = readOnly
         ? (t) => !t.isMutating
         : undefined;
+    if (planPhase)
+        notePlanPhaseSubagentDispatch();
+    // Task 7 — per-dispatch announce on the PARENT's emitter (childCtx
+    // deliberately omits chunkEmitter, so this is the one line the user sees
+    // for each dispatch). 'info' renders dim in both the Ink and classic REPLs.
+    const taskPreview = args.task.length > 60 ? `${args.task.slice(0, 60)}…` : args.task;
+    ctx.chunkEmitter?.emit('info', `↳ subagent: ${args.skill}${readOnly ? ' — read-only' : ''} — ${taskPreview}`);
     try {
         await runTurn({
             provider: ctx.provider,
@@ -189,7 +213,7 @@ registerTool({
             },
             read_only: {
                 type: 'boolean',
-                description: 'When true, the subagent only sees read-only tools (no sap_set_source, no file-write, no shell_exec, etc.). Use this for research / analysis subagents that should not make changes — e.g. spawning a subagent to read code, run greps, or summarise findings. Smaller tools array = lower per-call cost; also a hard guard against accidental writes.',
+                description: 'When true, the subagent only sees read-only tools (no sap_set_source, no file-write, no shell_exec, etc.). Use this for research / analysis subagents that should not make changes — e.g. spawning a subagent to read code, run greps, or summarise findings. Smaller tools array = lower per-call cost; also a hard guard against accidental writes. NOTE: during plan phases the read-only filter is ALWAYS enforced regardless of this argument.',
             },
         },
         required: ['skill', 'task'],

package/dist/tools/subagent/background_run.js

@@ -16,7 +16,7 @@
  * CSPEACH_TOOL_BACKGROUND_RUN=on. isMutating: true — hooks the existing
  * approval gate (same UX as shell_exec).
  */
-import { spawn } from 'node:child_process';
+import spawn from 'cross-spawn';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -69,6 +69,9 @@ export async function backgroundRunHandler(args, ctx) {
     catch {
         return { content: `error: cwd "${args.cwd ?? '.'}" does not exist`, is_error: true };
     }
+    // Resolve the bare safelisted name to an absolute executable path via a
+    // PATH-only walk (no cwd-first). Both the friendly "not installed"
+    // pre-flight check AND the spawn target below — same binary, no divergence.
     const resolved = await resolveExecutable(args.command);
     if (resolved === null) {
         return {
@@ -78,6 +81,19 @@ export async function backgroundRunHandler(args, ctx) {
     }
     let child;
     try {
+        // Absolute PATH-resolved `resolved` (NOT the bare command name).
+        //
+        // SECURITY: cross-spawn resolves a BARE name cwd-first on Windows
+        // (node_modules/which checks process.cwd() before PATH and chdir's into
+        // options.cwd first). A model with a write primitive could plant
+        // `<safelisted>.cmd` in the project tree and have it picked up cwd-first
+        // → arbitrary code execution, safelist bypassed. Handing cross-spawn the
+        // absolute PATH-resolved path closes that (`which` short-circuits to the
+        // literal file for path-bearing commands, pathEnv=['']). cross-spawn
+        // still wraps an absolute `.cmd`/`.bat` through cmd.exe with per-arg
+        // escaping, so Windows shim + CVE-2024-27980 handling stay. shell:false
+        // → metacharacters inert. Existence check + spawn now target the SAME
+        // binary. See shell_exec.ts for the full rationale.
         child = spawn(resolved, argv, {
             cwd,
             env: buildSafeEnv(),

package/dist/tools/todo.js

@@ -0,0 +1,144 @@
+/**
+ * todo_set — UX Wave 2 / Task 4. CC's TodoWrite adapted for CSPeach: the
+ * model maintains a visible task list on long multi-step jobs (RAP stacks,
+ * upgrade batches, plan phases). Task 5 renders it (Ctrl+T panel +
+ * turn-status strip) via todoEmitter; /compact appends it to the summary
+ * block so the plan survives compaction (commands/compact.ts).
+ *
+ * Semantics: FULL-LIST REPLACE on every call — never a delta. 1..20 items.
+ *
+ * Transcript render (CC-style, 2026-07): on every successful set the
+ * handler also emits the FULL checklist as a scrollback block via
+ * ctx.chunkEmitter (renderer/todo-block.ts). The raw ⏺/⎿ todo_set rows are
+ * widget-suppressed (renderer/tool-widget.ts) so the block is the sole
+ * visible representation — the transcript now shows the whole plan
+ * advancing, not a raw `⏺ todo_set({"todos":[…])` JSON line. This is the
+ * Claude-Code parity the owner asked for; the turn-status strip (single ▶
+ * row) and Ctrl+T panel stay exactly as they were.
+ *
+ * Session-write route (chosen with evidence, 2026-07-05): the tool mutates
+ * `ctx.session.todos` directly. ToolContext.session IS the live
+ * SessionState object (tools/index.ts) — the same instance repl.tsx /
+ * one-shot.ts construct the ctx from — and agent/loop.ts already calls
+ * saveSession(session) end-of-turn (and session/pending.ts saves per
+ * mutating-tool WAL entry), so no extra save call is needed here. The
+ * emitter-plus-repl-side-subscriber alternative was rejected: it would
+ * add a second writer for state the tool already owns, and headless /
+ * one-shot paths (no subscriber mounted) would silently lose persistence.
+ *
+ * Validation discipline: structured error results (is_error: true), never
+ * throws — caps at 20 items, rejects empty lists, empty text, unknown
+ * status. MULTIPLE in_progress items are a WARNING in the result, not an
+ * error: blocking the model mid-job over a presentation nit would stall
+ * long workflows, and the list is still coherent and renderable — the
+ * warning text steers the model to fix it on its next call instead.
+ *
+ * isMutating: false — writes CLI-side session state only, never SAP.
+ * Headless: identical behaviour (session write + emitter absent/no-op;
+ * no prompt involved).
+ *
+ * Emitter seam (Task 5, 2026-07-05): the panel channel arrives via
+ * `ctx.todoEmitter` — NOT a module-level import — mirroring how
+ * chunkEmitter is ctx-carried. agent_run's child ctx omits it, so a
+ * subagent's todo_set updates only the CHILD session and can never
+ * clobber the parent's Ctrl+T panel.
+ */
+import { registerTool } from './index.js';
+import { formatTodoChecklistBlock } from '../renderer/todo-block.js';
+/** Hard cap on list length — past this the list stops being a glanceable plan. */
+export const TODO_MAX_ITEMS = 20;
+const VALID_STATUSES = new Set(['pending', 'in_progress', 'completed']);
+function errorResult(message) {
+    return { content: `error: ${message}`, is_error: true };
+}
+export async function todoSetHandler(args, ctx) {
+    const raw = args?.todos;
+    if (!Array.isArray(raw)) {
+        return errorResult("todos must be an array of { text, status } items (status: 'pending' | 'in_progress' | 'completed').");
+    }
+    if (raw.length === 0) {
+        return errorResult('todos must contain at least 1 item — this is a full-list replace, never call it with an empty list.');
+    }
+    if (raw.length > TODO_MAX_ITEMS) {
+        return errorResult(`todos exceeds the ${TODO_MAX_ITEMS}-item cap (got ${raw.length}). Collapse completed work or group related steps into one item.`);
+    }
+    // Validate + normalise BEFORE touching session state — a rejected call
+    // must leave the previous list fully intact.
+    const todos = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        const text = typeof item?.text === 'string' ? item.text.trim() : '';
+        if (!text) {
+            return errorResult(`todos[${i}].text must be a non-empty string.`);
+        }
+        if (typeof item?.status !== 'string' || !VALID_STATUSES.has(item.status)) {
+            return errorResult(`todos[${i}].status must be one of 'pending' | 'in_progress' | 'completed' (got ${JSON.stringify(item?.status ?? null)}).`);
+        }
+        todos.push({ text, status: item.status });
+    }
+    const inProgress = todos.filter((t) => t.status === 'in_progress');
+    // Full-list replace on the LIVE session object — persisted by the loop's
+    // existing end-of-turn saveSession (see module doc for the evidence).
+    ctx.session.todos = todos;
+    // UI fan-out (Task 5) — via the ctx-carried emitter (absent on subagent
+    // ctxs → suppressed; absent listener → harmless no-op). Emit a defensive
+    // copy so a consumer mutating the payload can never corrupt the
+    // persisted session state.
+    ctx.todoEmitter?.emit('update', todos.map((t) => ({ ...t })));
+    // Transcript render (CC-style, 2026-07): drop the FULL checklist into
+    // scrollback on every successful set. The raw ⏺/⎿ todo_set rows are
+    // widget-suppressed (renderer/tool-widget.ts), so this block is the sole
+    // visible representation — mirroring ask_question. ctx.chunkEmitter routes
+    // to Ink Static scrollback AND the classic 'chunk'→stdout path
+    // (renderer/notices.ts). Subagent ctxs deliberately omit chunkEmitter
+    // (tools/subagent/agent_run.ts), so a child turn's todo_set can never
+    // print its checklist into the PARENT transcript — same seam as the
+    // todoEmitter suppression above.
+    ctx.chunkEmitter?.emit('chunk', formatTodoChecklistBlock(todos));
+    const result = {
+        count: todos.length,
+        in_progress: inProgress[0]?.text ?? null,
+    };
+    if (inProgress.length > 1) {
+        result.warning =
+            `${inProgress.length} items are in_progress — exactly one item should be in_progress at a time. ` +
+                'Mark the others pending or completed on your next todo_set call.';
+    }
+    return { content: JSON.stringify(result) };
+}
+registerTool({
+    name: 'todo_set',
+    // Model-behavior lever — this exact framing is binding (task-4 brief).
+    description: 'Maintain your task list for multi-step work. Call with the FULL updated list whenever you ' +
+        'complete a step, start a new one, or discover new work. Exactly one item should be ' +
+        'in_progress at a time. The user sees this list — keep items short and outcome-shaped.',
+    isMutating: false,
+    category: 'session',
+    input_schema: {
+        type: 'object',
+        properties: {
+            todos: {
+                type: 'array',
+                minItems: 1,
+                maxItems: TODO_MAX_ITEMS,
+                description: 'The full task list — replaces the previous list entirely.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        text: {
+                            type: 'string',
+                            description: 'Short, outcome-shaped item, e.g. "Activate ZCL_ORDER_API".',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['pending', 'in_progress', 'completed'],
+                        },
+                    },
+                    required: ['text', 'status'],
+                },
+            },
+        },
+        required: ['todos'],
+    },
+    handler: (args, ctx) => todoSetHandler(args, ctx),
+});

package/dist/tools/transport-resolution.js

@@ -0,0 +1,86 @@
+/**
+ * transport-resolution — owning-transport check before SAP writes (Rule 9,
+ * battery defects D15/D20).
+ *
+ * The trap this kills: an object (or one of its LIMU pieces) is already
+ * locked in an open transport request. Writing under ANY other transport is
+ * guaranteed to fail with a CTS lock conflict (CTS_WBO_API 020 — observed
+ * live: "Object LIMU CINC ZBP_I_DOWNTIMELOG…CCIMP is already locked in
+ * request S4HK903431"). Asking the human to pick from N open transports
+ * (D15: 89 of them) or creating a fresh junk transport (D20) cannot succeed.
+ *
+ * Correct flow, now structural instead of prose-only:
+ *   - object locked in exactly one open request → USE that transport
+ *     silently, overriding a conflicting supplied transport (with a notice);
+ *   - object locked in several open requests → ambiguous, never force —
+ *     keep the supplied transport and surface the candidates;
+ *   - object free / lookup failed → current behaviour (supplied transport).
+ *
+ * The lookup is one E071+E070 query pair (AdtClient.transportForObject) and
+ * is strictly best-effort: a failed lookup (VPN drop, data-preview auth,
+ * older mocks without the method) must NEVER block the write.
+ */
+import { wasTransportCreatedThisSession } from './transport.js';
+/**
+ * Resolve the transport for a write against the owning-transport ledger.
+ *
+ * @param ctx        tool context (uses ctx.adt + ctx.chunkEmitter)
+ * @param objectType ABAP object type of the write target (CLAS, PROG, …)
+ * @param objectName ABAP object name of the write target
+ * @param supplied   the transport the tool would use today (each tool keeps
+ *                   its own args/session fallback semantics and passes the
+ *                   outcome here)
+ */
+export async function resolveWriteTransport(ctx, objectType, objectName, supplied) {
+    // TODO(perf): per-turn memo. Every write funnels through this lookup
+    // (2 datapreview SQL queries inside transportForObject), so a multi-method
+    // turn — N sap_update_method calls against the same class — amplifies to
+    // N×2 queries for an answer that cannot change mid-turn. Memoise per turn,
+    // keyed `${objectType}:${objectName}`, before the battery grows
+    // write-heavy scenarios. No implementation yet.
+    let owning = null;
+    try {
+        owning = await ctx.adt.transportForObject(objectType, objectName);
+    }
+    catch (err) {
+        // Best-effort only — never block or delay the write on a failed lookup,
+        // but leave a dim trace so "why didn't it auto-resolve?" is diagnosable
+        // ('info' channel = non-fatal diagnostics; 'warn' is reserved for the
+        // conflicting-override case below).
+        ctx.chunkEmitter?.emit('info', `owning-transport lookup failed for ${objectType} ${objectName} — `
+            + `proceeding with ${supplied ?? 'no transport'} `
+            + `(${err instanceof Error ? err.message : String(err)})`);
+        return { transport: supplied };
+    }
+    if (owning?.transport) {
+        const conflicting = !!supplied && supplied !== owning.transport;
+        const note = conflicting
+            ? `${objectName} is already locked in ${owning.transport} — writing under the owning transport and ignoring transport=${supplied} (SAP would refuse with a CTS lock conflict)`
+            : `object locked in ${owning.transport} — writing under owning transport`;
+        // warn only when we OVERRIDE what the caller asked for; the happy match
+        // (supplied === owning, or nothing supplied) is informational.
+        ctx.chunkEmitter?.emit(conflicting ? 'warn' : 'info', note);
+        // Orphan hint (third junk TR this month, 2026-06-12): the session's
+        // current transport was created by sap_transport_create THIS session, yet
+        // this write was forced into a different (owning) request — the created
+        // TR is probably an empty orphan. Warn only; deleting a TR is destructive
+        // and stays with the human.
+        const sessionCurrent = ctx.currentTransport?.get() ?? null;
+        if (sessionCurrent
+            && sessionCurrent !== owning.transport
+            && wasTransportCreatedThisSession(sessionCurrent)) {
+            ctx.chunkEmitter?.emit('warn', `transport ${sessionCurrent} created this session was not used by this write — `
+                + 'it may be an empty orphan (delete via SE09 or ask me)');
+        }
+        return { transport: owning.transport, owning: owning.transport, note };
+    }
+    if (owning && owning.candidates.length > 1) {
+        const note = `${objectName} pieces are locked in ${owning.candidates.length} open transports `
+            + `(${owning.candidates.join(', ')}) — cannot auto-resolve the owning request; `
+            + `using ${supplied ?? 'no transport'}`;
+        ctx.chunkEmitter?.emit('warn', note);
+        return { transport: supplied, note };
+    }
+    // Object is free — current behaviour.
+    return { transport: supplied };
+}