@cspeach/cli 1.1.34 → 1.1.35

package/dist/renderer/wrap-rows.js

@@ -0,0 +1,87 @@
+// src/renderer/wrap-rows.ts
+//
+// The one wrap helper for card content (fix batch 2026-10-12, Task 2).
+//
+// THE RULE: card content wraps; chrome may cut. Text a person reads to make
+// a decision — card titles, facts, option labels and descriptions, risk and
+// failure reasons, SAP error details — is pre-wrapped here into a KNOWN
+// number of rows. Ink never soft-wraps a live-frame row (its erase
+// accounting counts rows), so callers draw each returned row as its own
+// truncate-end <Text> and count every row in their height estimate. Status
+// rows, hints, palettes, spinners, traces and "… N more" counters stay one
+// row and cut with truncateToWidth.
+//
+// Replaces factRows (confirm-card) and wrapCardText (ask-card), which did the
+// same job twice.
+import stringWidth from 'string-width';
+import { truncateToWidth } from './ui-width.js';
+import { sanitizeControlChars } from './sanitize.js';
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** The longest grapheme-whole prefix of `word` that fits `cells` (at least one grapheme). */
+function takeCells(word, cells) {
+    let out = '';
+    let used = 0;
+    for (const { segment } of GRAPHEMES.segment(word)) {
+        const w = stringWidth(segment);
+        if (used + w > cells && out.length > 0)
+            break;
+        out += segment;
+        used += w;
+        if (used >= cells)
+            break;
+    }
+    return out;
+}
+/**
+ * `text` as the rows it is drawn on, each at most `cells` terminal cells.
+ * Control characters are neutralised, tabs become two spaces and newlines
+ * one space. Text that fits is one row, unchanged. Otherwise it wraps at
+ * spaces (a word wider than the row is cut where it must be; wide characters
+ * count two cells and are never split) onto at most `maxRows` rows; when
+ * more is left, the last row ends with the `more` glyph (… / ...). With
+ * `maxRows` 1 this is truncateToWidth: one row, cut.
+ */
+export function wrapRows(text, cells, maxRows = 1) {
+    const flat = sanitizeControlChars(text).replace(/\t/g, '  ').replace(/\r?\n/g, ' ');
+    const width = Math.max(1, cells);
+    const max = Math.max(1, Math.floor(maxRows));
+    if (stringWidth(flat) <= width)
+        return [flat];
+    if (max === 1)
+        return [truncateToWidth(flat, width)];
+    const indent = /^ */.exec(flat)[0].slice(0, Math.max(0, width - 1));
+    const rows = [];
+    let cur = indent;
+    const curEmpty = () => cur.length === 0 || cur === indent;
+    for (let word of flat.trim().split(/ +/).filter((w) => w.length > 0)) {
+        while (stringWidth(word) > width) {
+            if (!curEmpty()) {
+                rows.push(cur);
+                cur = '';
+            }
+            const head = takeCells(word, width - stringWidth(cur));
+            rows.push(cur + head);
+            cur = '';
+            word = word.slice(head.length);
+        }
+        if (word.length === 0)
+            continue;
+        if (curEmpty())
+            cur += word;
+        else if (stringWidth(cur) + 1 + stringWidth(word) <= width)
+            cur += ` ${word}`;
+        else {
+            rows.push(cur);
+            cur = word;
+        }
+    }
+    if (!curEmpty() || rows.length === 0)
+        rows.push(cur);
+    if (rows.length <= max)
+        return rows;
+    const kept = rows.slice(0, max);
+    // The trailing space guarantees a cut (and so the more glyph) even when the
+    // joined rest would happen to fit.
+    kept[max - 1] = truncateToWidth(`${rows.slice(max - 1).join(' ')} `, width);
+    return kept;
+}

package/dist/repl.js

@@ -144,6 +144,7 @@ import { maybeExpandNumberSelection, lastAssistantText } from './repl/numbered-m
 import { attachEarlyLineBuffer, noopEarlyLineBuffer } from './repl/early-line-buffer.js';
 import { createRestoreGuard } from './repl/restore-guard.js';
 import { gracefulExit } from './lib/graceful-exit.js';
+import { endSapSessionAfterTurn } from './sap/session-end.js';
 import { snapshotTurnStart, pushPostTurnStatus, seedFooterSpend } from './repl/post-turn-status.js';
 import { looksLikeCspeachShellCommand, CSPEACH_SHELL_NUDGE } from './repl/cspeach-shell-detect.js';
 import { applyLocalBuildConfig, applyStandaloneFileTools } from './tools/local-build.js';
@@ -2118,6 +2119,9 @@ export async function runRepl(opts) {
                         planSubagentDispatches = getAndResetPlanPhaseSubagentDispatches();
                     }
                 }
+                // 2026-10-13 — end the stateful SAP session between turns, so a lock
+                // a failed write left behind does not outlive the turn (SM12).
+                await endSapSessionAfterTurn(adt);
             }
             // B3 — persist the plan revision from the resume turn's manifest
             // block (runs even after a turn error: partial assistant content is
@@ -4117,6 +4121,8 @@ export async function runRepl(opts) {
                     planSubagentDispatches = getAndResetPlanPhaseSubagentDispatches();
                 }
             }
+            // 2026-10-13 — end the stateful SAP session between turns (Ink mirror).
+            await endSapSessionAfterTurn(adt);
         }
         // B3 — persist the plan revision from the resume turn's manifest block.
         // FALLBACK: skipped when the mid-turn onPlanManifest hook already saved it

package/dist/sap/connection-manager.js

@@ -3,8 +3,22 @@ import { SapConnection } from '@cspeach/sap-client';
 import { resolveSapTls } from '../config/loader.js';
 import { password as promptPassword } from '@inquirer/prompts';
 import { isHeadless } from '../renderer/tty.js';
+import { registerExitTask } from '../lib/graceful-exit.js';
+import { endSapSessions } from './session-end.js';
 const SAP_SERVICE = 'cspeach-sap';
 const cache = new Map();
+let exitTaskRegistered = false;
+/**
+ * 2026-10-13 — on exit, end the stateful SAP session of every connection this
+ * process opened, so locks left in it leave SM12 now instead of when SAP times
+ * the session out. Registered once, on the first connection.
+ */
+function registerSessionEndOnExit() {
+    if (exitTaskRegistered)
+        return;
+    exitTaskRegistered = true;
+    registerExitTask(() => endSapSessions(cache.values()));
+}
 /**
  * The single place that reads an SAP alias password: keychain first, then a
  * masked prompt when interactive. Headless callers (and the SAP link, which
@@ -69,6 +83,7 @@ export async function getConnection(alias, cfg) {
     // our existing cookies belong to a different one.
     await conn.login();
     cache.set(alias, conn);
+    registerSessionEndOnExit();
     return conn;
 }
 export function clearConnectionCache() {

package/dist/sap/session-end.js

@@ -0,0 +1,66 @@
+/**
+ * Ending CSPeach's stateful SAP session (live finding 2026-10-13).
+ *
+ * Lock chains open a stateful ADT session on SAP. Nothing ended it, so any
+ * lock left inside it — after a failed write, or from a unit-test run — stayed
+ * in SM12 until SAP timed the session out, even after the CLI exited.
+ *
+ * When it is ended:
+ *   - after every TOP-LEVEL turn (the REPL), so a lock left by a failed write
+ *     never outlives the turn — except while a manual `sap_lock` is held,
+ *     because ending the session would silently drop that lock;
+ *   - on exit, for every connection, always (the process is going away).
+ *
+ * Both are capped so a slow or unreachable SAP never holds up the prompt or
+ * the exit, and neither ever throws. The next lock chain simply opens a fresh
+ * session (sap-client forgets the context cookie when it ends one).
+ */
+/** Longest we wait for SAP to confirm the session ended. */
+export const END_SESSION_CAP_MS = 3_000;
+let manualLocks = 0;
+/** A `sap_lock` call returned a handle. */
+export function noteManualLock() {
+    manualLocks += 1;
+}
+/** A `sap_unlock` call ran. */
+export function noteManualUnlock() {
+    manualLocks = Math.max(0, manualLocks - 1);
+}
+export function __resetManualLocksForTests() {
+    manualLocks = 0;
+}
+function capped(p, onTimeout) {
+    let timer;
+    return Promise.race([
+        p,
+        new Promise((r) => { timer = setTimeout(() => r(onTimeout), END_SESSION_CAP_MS); }),
+    ]).finally(() => { if (timer)
+        clearTimeout(timer); });
+}
+/** After a top-level turn: end the session unless a manual lock is still held. */
+export async function endSapSessionAfterTurn(client) {
+    // Duck-typed: the offline client and an older sap-client have no endSession.
+    const adt = client;
+    if (!adt || typeof adt.endSession !== 'function')
+        return { ended: false, skipped: 'no_client' };
+    if (manualLocks > 0)
+        return { ended: false, skipped: 'manual_lock' };
+    try {
+        return await capped(adt.endSession(), { ended: false, error: 'timeout' });
+    }
+    catch (e) {
+        return { ended: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** On exit: end the session of every connection, capped as a whole. */
+export async function endSapSessions(conns) {
+    const all = [...conns].map(async (c) => {
+        if (typeof c.endStatefulSession !== 'function')
+            return;
+        try {
+            await c.endStatefulSession();
+        }
+        catch { /* best effort on the way out */ }
+    });
+    await capped(Promise.all(all).then(() => undefined), undefined);
+}

package/dist/tools/ask-question.js

@@ -251,7 +251,7 @@ registerTool({
                         },
                         multiSelect: {
                             type: 'boolean',
-                            description: 'true = the user may pick several options; false/omitted = pick exactly one.',
+                            description: 'true = the user may pick several options; false/omitted = pick exactly one. When the user ticks options and also types an answer, it comes back as free text (custom: true): the ticked labels, then the typed text, comma-separated.',
                         },
                         options: {
                             type: 'array',

package/dist/tools/sap-read.js

@@ -644,29 +644,29 @@ registerTool({
     handler: async (args, ctx) => {
         // runUnitTest(type, name) — type first
         const result = await ctx.adt.runUnitTest(args.type, args.name);
-        // B2 false-green guard (project_aunit_run_gap): the ADT AUnit-run endpoint
-        // returns HTTP 200 with an EMPTY runResult (total:0, no programs) even for a
-        // class that is active + syntax-clean with a valid FOR TESTING local class —
-        // a known environmental gap, exhaustively probed (sap-client buildUnitTestXml
-        // comment). The raw {total:0} shape reads to a caller like "0 tests, nothing
-        // failed → green", so an unguarded pass-through risks a false-green test gate.
-        // When we detect that empty signature, wrap the (still-carried) raw result in
-        // an explicit UNVERIFIED envelope that names Eclipse "Run As → ABAP Unit" as
-        // the authoritative check. A genuine run (total > 0) passes through unchanged.
-        const summary = result?.summary;
-        const programs = result?.programs;
-        const noTestsRun = summary?.total === 0 && (!Array.isArray(programs) || programs.length === 0);
-        if (noTestsRun) {
+        // B2 false-green guard: a run in which no test actually ran reads to a
+        // caller like "nothing failed → green". Wrap the (still-carried) raw result
+        // in an explicit UNVERIFIED envelope when:
+        //   - total is 0, missing or not a number — even when programs are present
+        //     (a class with no methods, or only tolerable class alerts; review I1);
+        //   - every test was skipped (total > 0, passed 0, failed 0; review M1).
+        // It is no longer blamed on an ADT gap: the 2026-10-12 sap-client fix sends
+        // the request shape Eclipse sends. A run with a pass or a failure passes
+        // through unchanged.
+        const summary = result
+            ?.summary;
+        const total = summary?.total;
+        const noTestsRun = typeof total !== 'number' || !Number.isFinite(total) || total === 0;
+        const allSkipped = !noTestsRun && summary?.passed === 0 && summary?.failed === 0;
+        if (noTestsRun || allSkipped) {
+            const n = total;
+            const warning = noTestsRun
+                ? '0 tests ran — this is not a pass. Check that the object has an active test ' +
+                    'class (FOR TESTING) with active test methods, then run it again.'
+                : `${n === 1 ? '1 test was' : `${n} tests were`} skipped and none ran — this is not ` +
+                    'a pass. Check the risk level and duration of the test classes, then run it again.';
             return {
-                content: JSON.stringify({
-                    verification: 'UNVERIFIED',
-                    warning: 'ABAP Unit run enumerated 0 tests (empty runResult). This does NOT mean the tests ' +
-                        'passed — it means none executed. A FOR TESTING class that is active + syntax-clean ' +
-                        'still returning 0 is a known ADT AUnit-run gap (project_aunit_run_gap): the ' +
-                        'authoritative check is Eclipse "Run As → ABAP Unit" (Ctrl+Shift+F10). Do NOT treat ' +
-                        'this as a green test gate.',
-                    result,
-                }, null, 2),
+                content: JSON.stringify({ verification: 'UNVERIFIED', warning, result }, null, 2),
             };
         }
         return { content: JSON.stringify(result, null, 2) };

package/dist/tools/sap-write.js

@@ -16,7 +16,7 @@
  *   unlock(type, name, lockHandle)                   → Promise<void>             line 1949
  *   serviceBindingPublish(name)                      → Promise<{status,error?}>  line 2658
  *   serviceBindingUnpublish(name)                    → Promise<{status,error?}>
- *   messageMaintain (STUB — not yet in sap-client)
+ *   maintainMessages({name, messages, transport?})   → Promise<MaintainMessagesResult> (0.1.19)
  *   numberRangeIntervals (STUB — not yet in sap-client)
  *
  * auditLog aliased from safety/audit-log.ts#log via sap-client/src/index.ts.
@@ -26,7 +26,7 @@ import { readFileSync } from 'node:fs';
 import { registerTool } from './index.js';
 import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
 import { grantClaimMismatch, grantActivateMismatch, grantOwningTransportMismatch, grantOwningTransportDetail } from '../approvals/grant-claims.js';
-import { autoSnapshot, autoSnapshotClassInclude } from './snapshot.js';
+import { autoSnapshot, autoSnapshotClassInclude, autoSnapshotMessageClass } from './snapshot.js';
 import { includeSnapshotType } from './include-snapshot.js';
 import { buildWriteChainLine } from '../renderer/verify-chain.js';
 import { buildChangeCard } from '../renderer/change-card.js';
@@ -49,6 +49,7 @@ import { noteWriteTransport, setCurrentTransport } from '../repl/current-transpo
 import { markTransportCreatedThisSession } from './transport.js';
 import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
 import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.js';
+import { noteManualLock, noteManualUnlock } from '../sap/session-end.js';
 // ── Transcript visibility helpers (D16-display + tour slide-7, 2026-06-12) ──
 //
 // Rule 7 auto-snapshots always fired but the transcript never said so
@@ -868,7 +869,11 @@ registerTool({
                 object: result.objectName,
                 type: result.objectType,
                 package: result.packageName,
-                next_step: 'write_source_via_sap_set_source_then_activate',
+                // A message class has no source and is never activated: its messages
+                // go in through sap_message_maintain (bug 3, 2026-10-12).
+                next_step: String(result.objectType ?? '').toUpperCase() === 'MSAG'
+                    ? 'add_messages_via_sap_message_maintain (a message class has no source and no activation)'
+                    : 'write_source_via_sap_set_source_then_activate',
             }),
         };
     },
@@ -1573,6 +1578,9 @@ registerTool({
     },
     handler: async (args, ctx) => {
         const result = await ctx.adt.lock(args.type, args.name);
+        // The turn-end session close keeps the session while this lock is held.
+        if (result?.status === 'locked')
+            noteManualLock();
         return { content: JSON.stringify(result) };
     },
 });
@@ -1596,6 +1604,7 @@ registerTool({
     },
     handler: async (args, ctx) => {
         await ctx.adt.unlock(args.type, args.name, args.lockHandle);
+        noteManualUnlock();
         return { content: JSON.stringify({ status: 'ok' }) };
     },
 });
@@ -1644,34 +1653,256 @@ registerTool({
         return { content: JSON.stringify(result) };
     },
 });
-// ── sap_message_maintain (STUB) ───────────────────────────────────────────────
+// ── sap_message_maintain ──────────────────────────────────────────────────────
 //
-// STUB — MSAG message-class maintenance requires XML message-class-format
-// parsing not yet implemented in @cspeach/sap-client.
+// Signature (sap-client 0.1.19): maintainMessages({name, messages, transport?})
+//   → Promise<MaintainMessagesResult>
+// Adds or changes T100 messages in an existing message class, in one batch.
+// sap-client merges into the existing rows, locks, PUTs the whole class,
+// unlocks in a finally and READS BACK: success is `verified`, never HTTP 200.
+// Rule 7 snapshot = the class document (all messages) before the write.
+// No syntax check and no activation: a message class is not activatable.
+const MESSAGE_TEXT_MAX = 73;
+/** Same rule as sap-client's isValidMessageClassName (optional /NAMESPACE/). */
+const MESSAGE_CLASS_NAME_RE = /^(?:\/[A-Z0-9_]{1,10}\/)?[A-Z0-9_]{1,20}$/;
+/** Review M-1: a plain sentence when SAP may still hold a lock, else undefined. */
+function lockWarning(className, r) {
+    if (r.released !== false)
+        return undefined;
+    const what = (r.unlockFailures ?? []).join(', ') || 'unlock';
+    return `SAP may still hold a lock on message class ${className} (failed: ${what}). Check SM12 and remove it there, or it clears when the session ends.`;
+}
+/** The rows from the tool args (`messages`, or the single-message short form). */
+function messageRowsFromArgs(args) {
+    const list = Array.isArray(args['messages']) ? args['messages'] : [];
+    const rows = list.map((m) => ({
+        msgno: String(m?.['msgno'] ?? m?.['number'] ?? '').trim(),
+        text: typeof m?.['text'] === 'string' ? m['text'] : '',
+        ...(typeof m?.['selfExplanatory'] === 'boolean' ? { selfExplanatory: m['selfExplanatory'] } : {}),
+    }));
+    if (rows.length === 0 && args['messageNumber'] !== undefined) {
+        rows.push({
+            msgno: String(args['messageNumber']).trim(),
+            text: typeof args['messageText'] === 'string' ? args['messageText'] : '',
+        });
+    }
+    return rows;
+}
+/** Same rules as sap-client's validateMessageUpserts — checked here so a bad
+ *  request never spends the approval. A plain sentence, or null. */
+function messageRowsProblem(rows) {
+    if (rows.length === 0)
+        return 'Give at least one message to add or change.';
+    const seen = new Set();
+    for (const r of rows) {
+        if (!/^\d{3}$/.test(r.msgno))
+            return `Message number "${r.msgno}" is not valid. Use three digits, 000 to 999.`;
+        if (seen.has(r.msgno))
+            return `Message ${r.msgno} is in the request more than once.`;
+        seen.add(r.msgno);
+        if (r.text.trim().length === 0)
+            return `Message ${r.msgno} has an empty text.`;
+        const len = Array.from(r.text).length;
+        if (len > MESSAGE_TEXT_MAX)
+            return `Message ${r.msgno} is ${len} characters long. SAP allows ${MESSAGE_TEXT_MAX}.`;
+    }
+    return null;
+}
 registerTool({
     name: 'sap_message_maintain',
-    description: 'STUB — not currently implemented; do not call. '
-        + 'Maintaining MSAG message-class entries via ADT requires XML message-class-format '
-        + 'parsing not yet implemented in @cspeach/sap-client.',
+    description: 'Add or change messages in an existing message class (MSAG, the T100 texts behind SE91). '
+        + 'Create the class first with sap_create_object type MSAG. One call takes many messages. '
+        + 'Each message: msgno (three digits, 000-999) and text (up to 73 characters, &1-&4 placeholders allowed). '
+        + 'Messages not in the call are kept. No source, no syntax check, no activation. '
+        + 'The type (E, W, I, S) is not stored: it is chosen where the message is raised, e.g. MESSAGE e001(zfoo). '
+        + 'Requires approval_id.',
     isMutating: true,
     requiresSap: true,
     input_schema: {
         type: 'object',
         properties: {
-            messageClass: { type: 'string', description: 'Message class name (e.g. ZMSAG_FOO)' },
-            messageNumber: { type: 'string', description: 'Three-digit message number (e.g. 001)' },
-            messageText: { type: 'string', description: 'Message text (up to 73 characters)' },
-            messageType: { type: 'string', description: 'Message type: I, W, E, A, X, S' },
+            messageClass: { type: 'string', description: 'Message class name (e.g. ZSALES_MSG)' },
+            messages: {
+                type: 'array',
+                description: 'Messages to add or change',
+                items: {
+                    type: 'object',
+                    properties: {
+                        msgno: { type: 'string', description: 'Three-digit message number (e.g. 001)' },
+                        text: { type: 'string', description: 'Message text, up to 73 characters (e.g. "Order &1 not found")' },
+                        selfExplanatory: { type: 'boolean', description: 'Optional. New messages default to true (no long text).' },
+                    },
+                    required: ['msgno', 'text'],
+                },
+            },
+            messageNumber: { type: 'string', description: 'Short form for one message: the number (use messages for several)' },
+            messageText: { type: 'string', description: 'Short form for one message: the text' },
+            transport: { type: 'string', description: 'Transport request number (optional)' },
+            approval_id: { type: 'string', description: 'JWT from request_approval' },
         },
-        required: ['messageClass', 'messageNumber', 'messageText'],
+        required: ['messageClass', 'approval_id'],
     },
-    handler: async (_args, _ctx) => {
+    handler: async (args, ctx) => {
+        const className = String(args.messageClass ?? '').trim().toUpperCase();
+        // ── Input check — before the approval is spent ──────────────────────────
+        const rows = messageRowsFromArgs(args);
+        const problem = !className
+            ? 'Give the message class name.'
+            : !MESSAGE_CLASS_NAME_RE.test(className)
+                ? `"${String(args.messageClass)}" is not a valid message class name (letters, digits and _ only, 20 characters at most).`
+                : messageRowsProblem(rows);
+        if (problem) {
+            return { content: JSON.stringify({ error: 'invalid_messages', detail: problem }), is_error: true };
+        }
+        // ── Capability — before the approval is spent (review I-1) ──────────────
+        const adt = ctx.adt;
+        if (typeof adt.readMessageClass !== 'function' || typeof adt.maintainMessages !== 'function') {
+            return {
+                content: JSON.stringify({
+                    error: 'message_maintain_unavailable',
+                    detail: 'This CSPeach build cannot write messages yet. Update CSPeach and try again.',
+                }),
+                is_error: true,
+            };
+        }
+        const msagClient = adt;
+        // ── Gate 1: Approval ────────────────────────────────────────────────────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, args.messageClass, 'modify');
+        if (!verify.ok) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }),
+                is_error: true,
+            };
+        }
+        // 2026-10-04 — a plan-grant id holds the write to its claims (type, package, transport).
+        {
+            const claim = grantClaimMismatch(verify.payload, { type: 'MSAG', transport: args.transport ?? ctx.currentTransport?.get() ?? null });
+            if (claim)
+                return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: claim }), is_error: true };
+        }
+        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
+        const startedAt = Date.now();
+        // ── Rule 9 conflict warning + 3-tier transport fallback ──────────────────
+        {
+            const sessionTransport = ctx.currentTransport?.get() ?? null;
+            if (args.transport && sessionTransport && args.transport !== sessionTransport) {
+                ctx.chunkEmitter?.emit('warn', `LLM passed transport=${args.transport} but session current-transport=${sessionTransport}`);
+            }
+        }
+        const effectiveTransport = args.transport ?? ctx.currentTransport?.get() ?? undefined;
+        const resolved = await resolveWriteTransport(ctx, 'MSAG', className, effectiveTransport);
+        // 2026-10-04 — a plan-grant id never writes into a transport other than the grant's.
+        if (grantOwningTransportMismatch(verify.payload, resolved.owning)) {
+            return {
+                content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'transport_mismatch', detail: grantOwningTransportDetail(className, resolved.owning) }),
+                is_error: true,
+            };
+        }
+        // ── Gate 2: Snapshot (Rule 7) — HARD gate, of the whole class ────────────
+        let snapOutcome;
+        try {
+            snapOutcome = await autoSnapshotMessageClass(className, msagClient);
+        }
+        catch (err) {
+            return {
+                content: JSON.stringify({ error: ERR.SNAPSHOT_FAILED, detail: String(err) }),
+                is_error: true,
+            };
+        }
+        if (snapOutcome.reason === 'object_not_found') {
+            return {
+                content: JSON.stringify({
+                    error: 'message_class_not_found',
+                    detail: `Message class ${className} does not exist. Create it first with sap_create_object type MSAG, then add the messages.`,
+                }),
+                is_error: true,
+            };
+        }
+        if (!snapOutcome.taken) {
+            return {
+                content: JSON.stringify({
+                    error: ERR.SNAPSHOT_FAILED,
+                    reason: snapOutcome.reason ?? 'source_read_failed',
+                    detail: snapOutcome.detail,
+                    recovery: 'The message class could not be read, so no snapshot was possible and nothing was written. If this is a connection or sign-in problem, fix it and try again.',
+                }),
+                is_error: true,
+            };
+        }
+        emitSnapshotNotice(ctx, snapOutcome, 'MSAG', className);
+        // ── WAL: record pending entry ────────────────────────────────────────────
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_message_maintain',
+            args: { messageClass: className, messages: rows.map((r) => r.msgno) },
+            started_at: new Date().toISOString(),
+        });
+        // ── Write (sap-client locks, PUTs, unlocks and reads back) ───────────────
+        let result;
+        try {
+            result = await msagClient.maintainMessages({
+                name: className,
+                messages: rows,
+                ...(resolved.transport ? { transport: resolved.transport } : {}),
+            });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            await finalizeToolCall(ctx.session, toolUseId, detail, true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({ error: 'message_maintain_failed', detail }),
+                is_error: true,
+            };
+        }
+        const lockNote = lockWarning(className, result);
+        if (lockNote)
+            ctx.chunkEmitter?.emit('warn', lockNote);
+        if (!result.verified) {
+            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(result), true, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({
+                    error: 'message_maintain_failed',
+                    ...(lockNote ? { lock_warning: lockNote } : {}),
+                    detail: result.error ?? 'The messages could not be confirmed in SAP.',
+                    missing: result.missing,
+                    ...(result.httpStatus !== undefined ? { http_status: result.httpStatus } : {}),
+                    ...(result.lockedInTransport ? {
+                        locked_in_transport: result.lockedInTransport,
+                        recovery: `Retry this exact call with transport=${result.lockedInTransport} — that request already owns the message class.`,
+                    } : {}),
+                }),
+                is_error: true,
+            };
+        }
+        if (result.noChange) {
+            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ unchanged: true }), false, Date.now() - startedAt);
+            return {
+                content: JSON.stringify({
+                    written: false,
+                    unchanged: true,
+                    message_class: className,
+                    changes: result.changes,
+                    message: `Message class ${className} already has these texts. Nothing was changed.`,
+                }),
+            };
+        }
+        // Audit only after SAP's read-back confirmed every message.
+        await auditLog('maintainMessages', 'MSAG', className, 'success', Date.now() - startedAt, result.changes.map((c) => `${c.msgno}:${c.action}`).join(' '));
+        noteWriteTransport(resolved.transport); // F-L2-1 statusline wire
+        await finalizeToolCall(ctx.session, toolUseId, JSON.stringify({ written: true, verified: true, changes: result.changes }), false, Date.now() - startedAt);
+        const written = result.changes.filter((c) => c.action !== 'unchanged').map((c) => c.msgno);
+        ctx.chunkEmitter?.emit('info', `messages ✓ ${className} ${written.join(' ')} (no activation needed)`);
+        const first = written[0] ?? rows[0].msgno;
         return {
             content: JSON.stringify({
-                error: 'not_implemented',
-                detail: 'MSAG message maintenance via ADT requires XML message-class-format parsing not yet implemented in @cspeach/sap-client',
+                written: true,
+                verified: true,
+                message_class: className,
+                changes: result.changes,
+                ...(resolved.owning ? { transport_used: resolved.owning, transport_note: resolved.note } : {}),
+                ...(lockNote ? { lock_warning: lockNote } : {}),
+                next_step: `Done — no activation needed. Raise these from code by number, e.g. MESSAGE e${first}(${className.toLowerCase()}) WITH …, or a T100 textid in an exception class. Never hard-code the texts.`,
             }),
-            is_error: true,
         };
     },
 });

package/dist/tools/snapshot.js

@@ -127,6 +127,32 @@ export async function autoSnapshotClassInclude(className, includeType, adt) {
     const entry = await snapshots.take(includeSnapshotType(includeType), className, src, 'before_write');
     return { taken: true, entry };
 }
+/**
+ * Rule-7 snapshot of a message class, taken before sap_message_maintain
+ * changes it. A message class has no source: the snapshot is the whole class
+ * document as SAP serves it (every message), stored under type MSAG.
+ *
+ *   404               → 'object_not_found' (no such class — the write cannot go ahead)
+ *   other read error  → 'source_read_failed' (+ detail) — the write is blocked
+ *   read OK           → snapshot taken
+ * A snapshots.take failure THROWS, like autoSnapshot.
+ */
+export async function autoSnapshotMessageClass(name, adt) {
+    let xml;
+    try {
+        xml = (await adt.readMessageClass(name)).xml;
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { taken: false, reason: 'object_not_found' };
+        return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+    }
+    if (typeof xml !== 'string' || xml.length === 0) {
+        return { taken: false, reason: 'source_read_failed', detail: 'the message class read returned no document' };
+    }
+    const entry = await snapshots.take('MSAG', name.toUpperCase(), xml, 'before_write');
+    return { taken: true, entry };
+}
 // ── sap_snapshot_list ─────────────────────────────────────────────────────────
 registerTool({
     name: 'sap_snapshot_list',