@cspeach/cli 0.6.2 → 0.6.4

package/README.md

@@ -1,108 +1,116 @@
-# CSPeach
-
-AI-assisted ABAP development CLI. 34 skills, direct SAP access, safety
-gates the model cannot bypass.
-
-## Install
-
-```bash
-npm install -g @cspeach/cli
-```
-
-Requires Node.js 20+. After install:
-
-```bash
-cspeach login         # opens browser, authorizes this machine
-cspeach config add-sap
-cspeach               # interactive REPL
-```
-
-## What it does
-
-CSPeach runs an AI consultant against your own SAP. Pick a skill (or type a
-prompt — the classifier picks one for you):
-
-```text
-/abap-spec-gap        find missing questions before any code is written
-/abap-design          object list + dependency DAG
-/abap-estimate        component-level hours with optimistic / realistic /
-                      pessimistic ranges
-/abap-cca             estate-wide custom-code analysis for S/4HANA
-/abap-upgrade-scan    baseline scan against the readiness variant
-/abap-upgrade-fix     interactive fix loop with per-object approval
-/abap-incident        short dump → fix → verify → handover
-cspeach --help        full skill list (34 total)
-```
-
-Every turn runs locally on your machine. SAP source and SAP data flow through
-`api.cspeach.dev` to the LLM. The proxy logs request metadata (skill, model,
-token counts, latency) for billing; the message body is forwarded to
-Anthropic and not stored on the proxy. SAP credentials never leave your
-machine.
-
-## Safety
-
-- **Snapshot gate** — every write auto-snapshots first
-- **Approval gate** — mutating tools require a single-use JWT bound to
-  (object, operation); the model sees a plan, you see each change
-- **Verify gate** — every write is syntax-checked; activation blocked on errors
-- **Transport discipline** — all writes land in your session transport; `$TMP`
-  is opt-in
-
-Ten Forge Rules are non-negotiable. Full philosophy in the `CSPeach Principles`
-preamble shown to the model every turn.
-
-## Configuration
-
-`~/.cspeach/config.toml` is created on first `cspeach config add-sap`:
-
-```toml
-proxy_url     = "https://api.cspeach.dev"
-default_model = "claude-opus-4-7"
-
-[sap.S4H-DEV]
-host     = "sap-dev.company.com"
-port     = 44300
-client   = "100"
-useSsl   = true
-username = "S.LAEEQ"
-```
-
-SAP passwords are stored in your OS keychain.
-
-## Common commands
-
-```text
-cspeach login                    sign in to api.cspeach.dev
-cspeach whoami                   show signed-in identity + plan/trial
-cspeach logout                   clear local auth
-cspeach config add-sap           add a SAP system
-cspeach doctor                   diagnose install + connectivity
-cspeach --resume                 resume a prior session
-cspeach --upgrade                pull the latest CLI release
-cspeach --version
-```
-
-## Troubleshooting
-
-If `cspeach doctor` fails:
-
-- **`auth`** — run `cspeach login` again
-- **`keychain`** — Windows Credential Manager / libsecret missing; CSPeach
-  falls back to per-session prompts, slower but functional
-- **`sap`** — host unreachable; check VPN + the host/port in config
-
-If the REPL hangs on first prompt, check `https://api.cspeach.dev/health`.
-
-## Links
-
-- **Landing**: https://cspeach.dev
-- **Contact**: laeeq.siddique@cremencing.com
-- **LinkedIn**: @laeeqsiddique
-
-## License
-
-Proprietary. Copyright (c) 2026 Cremencing Solutions. All rights reserved.
-Free to use under your active [CSPeach plan](https://cspeach.dev); not free
-to redistribute, fork, or sublicense. Commercial / OEM licensing:
-laeeq.siddique@cremencing.com.
+# CSPeach
+
+AI-assisted ABAP development CLI. 34 skills, direct SAP access, safety
+gates the model cannot bypass.
+
+## Install
+
+```bash
+npm install -g @cspeach/cli
+```
+
+Requires Node.js 20+. After install:
+
+```bash
+cspeach login         # opens browser, authorizes this machine
+cspeach config add-sap
+cspeach               # interactive REPL
+```
+
+## What it does
+
+CSPeach runs an AI consultant against your own SAP. Pick a skill (or type a
+prompt — the classifier picks one for you):
+
+```text
+/abap-spec-gap        find missing questions before any code is written
+/abap-design          object list + dependency DAG
+/abap-estimate        component-level hours with optimistic / realistic /
+                      pessimistic ranges
+/abap-cca             estate-wide custom-code analysis for S/4HANA
+/abap-upgrade-scan    baseline scan against the readiness variant
+/abap-upgrade-fix     interactive fix loop with per-object approval
+/abap-incident        short dump → fix → verify → handover
+cspeach --help        full skill list (34 total)
+```
+
+Every turn runs locally on your machine. SAP source and SAP data flow through
+`api.cspeach.dev` to the LLM. The proxy logs request metadata (skill, model,
+token counts, latency) for billing; the message body is forwarded to
+Anthropic and not stored on the proxy. SAP credentials never leave your
+machine.
+
+## Safety
+
+- **Snapshot gate** — every SAP write auto-snapshots first
+- **SAP approval gate** — SAP-write and transport tools (`sap_set_source`,
+  `sap_create_object`, `sap_delete_object`, `sap_update_method`,
+  `sap_activate`, `sap_transport_*`) require a single-use JWT bound to
+  (object, operation); the model sees a plan, you approve each change
+- **Optional tools default OFF** — filesystem, shell, web, and subagent
+  tools are invisible to the model unless you set `CSPEACH_TOOL_<NAME>=on`
+  in the environment
+- **Batch-write interrupt** — any second mutating call in a single turn
+  (Rule 8, any tool category) pauses for an explicit yes/no before it runs
+- **Verify gate** — every SAP write is syntax-checked; activation blocked on
+  errors
+- **Transport discipline** — all SAP writes land in your session transport;
+  `$TMP` is opt-in
+
+Ten Forge Rules are non-negotiable. Full philosophy in the `CSPeach Principles`
+preamble shown to the model every turn.
+
+## Configuration
+
+`~/.cspeach/config.toml` is created on first `cspeach config add-sap`:
+
+```toml
+proxy_url     = "https://api.cspeach.dev"
+default_model = "claude-opus-4-7"
+
+[sap.S4H-DEV]
+host     = "sap-dev.company.com"
+port     = 44300
+client   = "100"
+useSsl   = true
+username = "S.LAEEQ"
+```
+
+SAP passwords are stored in your OS keychain.
+
+## Common commands
+
+```text
+cspeach login                    sign in to api.cspeach.dev
+cspeach whoami                   show signed-in identity + plan/trial
+cspeach logout                   clear local auth
+cspeach config add-sap           add a SAP system
+cspeach doctor                   diagnose install + connectivity
+cspeach --resume                 resume a prior session
+cspeach --upgrade                pull the latest CLI release
+cspeach --version
+```
+
+## Troubleshooting
+
+If `cspeach doctor` fails:
+
+- **`auth`** — run `cspeach login` again
+- **`keychain`** — Windows Credential Manager / libsecret missing; CSPeach
+  falls back to per-session prompts, slower but functional
+- **`sap`** — host unreachable; check VPN + the host/port in config
+
+If the REPL hangs on first prompt, check `https://api.cspeach.dev/health`.
+
+## Links
+
+- **Landing**: https://cspeach.dev
+- **Contact**: laeeq.siddique@cremencing.com
+- **LinkedIn**: @laeeqsiddique
+
+## License
+
+Proprietary. Copyright (c) 2026 Cremencing Solutions. All rights reserved.
+Free to use under your active [CSPeach plan](https://cspeach.dev); not free
+to redistribute, fork, or sublicense. Commercial / OEM licensing:
+laeeq.siddique@cremencing.com.

package/dist/agent/__tests__/crash-recover.integration.test.js

@@ -0,0 +1,254 @@
+/**
+ * Round B integration test — crash + recover round-trip.
+ *
+ * Exercises the same try/catch + repair + persist pattern that lives in
+ * agent/loop.ts (lines ~327-460) without spinning up a real LLMProvider or
+ * inquirer prompts. The harness below mirrors the loop's structure exactly:
+ *
+ *   try {
+ *     for await (event of stream) { accumulate into currentAssistantContent }
+ *   } catch (err) {
+ *     interruptedError = err;
+ *   }
+ *   if (interruptedError) currentAssistantContent = repairPartialBlocks(...);
+ *   session.messages.push({ role: 'assistant', content: currentAssistantContent });
+ *   session.turnInterrupted = (interruptedError != null);
+ *   await saveSession(session);
+ *
+ * If the loop's actual code drifts from this contract, the diff between the
+ * two will surface in code review. This test guarantees that whichever code
+ * follows the contract behaves correctly under crash conditions.
+ *
+ * The key assertion: the LOST 200K-token report from /abap-cca on
+ * ZDPR_PAYMENTS — partial assistant text streamed before the Undici stream
+ * "terminated" mid-flight — IS recoverable from disk after this contract
+ * runs.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { newSession } from '../../session/schema.js';
+import { saveSession, loadSession } from '../../session/store.js';
+import { repairPartialBlocks } from '../repair-partial.js';
+const ORIGINAL_HOME = os.homedir();
+describe('crash + recover round-trip (Round B)', () => {
+    let tempHome;
+    beforeEach(async () => {
+        tempHome = await fs.mkdtemp(path.join(os.tmpdir(), 'crash-recover-'));
+        process.env.HOME = tempHome;
+        process.env.USERPROFILE = tempHome;
+    });
+    afterEach(async () => {
+        process.env.HOME = ORIGINAL_HOME;
+        process.env.USERPROFILE = ORIGINAL_HOME;
+        await fs.rm(tempHome, { recursive: true, force: true });
+    });
+    /**
+     * Build a fake provider stream that yields the supplied events and then
+     * either completes normally OR throws the supplied error before exhausting
+     * the iterable. Mirrors the shape of the Anthropic SDK's MessageStream.
+     */
+    function makeFakeStream(events, throwAfter, error) {
+        return {
+            async *[Symbol.asyncIterator]() {
+                let i = 0;
+                for (const ev of events) {
+                    if (i >= throwAfter && error) {
+                        throw error;
+                    }
+                    yield ev;
+                    i++;
+                }
+                if (error)
+                    throw error;
+            },
+        };
+    }
+    /**
+     * Mini-harness that mirrors the agent loop's for-await + try/catch + repair
+     * + persist pattern. Returns the accumulated content + the interrupted
+     * error so tests can assert on both. Crucially, it ALWAYS saves the
+     * session — same contract as the real loop.
+     */
+    async function runTurnHarness(session, stream) {
+        let currentAssistantContent = [];
+        let interruptedError = null;
+        try {
+            for await (const event of stream) {
+                if (event.type === 'content_block_start') {
+                    currentAssistantContent.push(event.content_block);
+                }
+                else if (event.type === 'content_block_delta') {
+                    const last = currentAssistantContent[currentAssistantContent.length - 1];
+                    const d = event.delta;
+                    if (d.type === 'text_delta' && last?.type === 'text') {
+                        last.text = (last.text ?? '') + d.text;
+                    }
+                    else if (d.type === 'thinking_delta' && last?.type === 'thinking') {
+                        last.thinking = (last.thinking ?? '') + d.thinking;
+                    }
+                    else if (d.type === 'input_json_delta') {
+                        if (last)
+                            last.partial_json = (last.partial_json ?? '') + d.partial_json;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            interruptedError = err;
+        }
+        if (interruptedError !== null) {
+            currentAssistantContent = repairPartialBlocks(currentAssistantContent);
+        }
+        if (currentAssistantContent.length > 0) {
+            session.messages.push({ role: 'assistant', content: currentAssistantContent });
+        }
+        session.last_turn_at = new Date().toISOString();
+        if (interruptedError !== null) {
+            session.turnInterrupted = true;
+            const msg = interruptedError instanceof Error ? interruptedError.message : String(interruptedError);
+            session.turnInterruptedReason = msg.slice(0, 200);
+        }
+        else {
+            session.turnInterrupted = false;
+            session.turnInterruptedReason = undefined;
+        }
+        await saveSession(session);
+        return { assistantContent: currentAssistantContent, interruptedError };
+    }
+    it('persists partial assistant content when the stream throws after a thinking + text block', async () => {
+        const session = newSession('crash-1', 'S4H', 'abap-cca', 'claude-opus-4-7');
+        session.messages.push({ role: 'user', content: '/abap-cca on ZDPR_PAYMENTS' });
+        const events = [
+            { type: 'content_block_start', content_block: { type: 'thinking', thinking: '' } },
+            { type: 'content_block_delta', delta: { type: 'thinking_delta', thinking: 'Plan probes...' } },
+            { type: 'content_block_start', content_block: { type: 'text', text: '' } },
+            { type: 'content_block_delta', delta: { type: 'text_delta', text: '## ABAP CCA — ZDPR_PAYMENTS\n\n## TL;DR\n\n13-object package' } },
+            { type: 'content_block_delta', delta: { type: 'text_delta', text: ', 5+ years untouched...' } },
+        ];
+        const stream = makeFakeStream(events, events.length, new Error('terminated'));
+        const result = await runTurnHarness(session, stream);
+        expect(result.interruptedError).toBeInstanceOf(Error);
+        expect(result.interruptedError.message).toBe('terminated');
+        expect(session.turnInterrupted).toBe(true);
+        expect(session.turnInterruptedReason).toBe('terminated');
+        // The partial assistant message WAS saved.
+        expect(session.messages).toHaveLength(2);
+        const assistant = session.messages[1];
+        expect(assistant.role).toBe('assistant');
+        const content = assistant.content;
+        expect(content).toHaveLength(2); // thinking + text
+        expect(content[0].type).toBe('thinking');
+        expect(content[0].thinking).toContain('Plan probes...');
+        expect(content[1].type).toBe('text');
+        expect(content[1].text).toContain('ZDPR_PAYMENTS');
+        expect(content[1].text).toContain('5+ years untouched');
+    });
+    it('drops incomplete tool_use blocks (partial_json) when the stream throws mid-input_json_delta', async () => {
+        const session = newSession('crash-2', 'S4H', 'abap-cca', 'claude-opus-4-7');
+        session.messages.push({ role: 'user', content: '/abap-cca' });
+        const events = [
+            { type: 'content_block_start', content_block: { type: 'text', text: '' } },
+            { type: 'content_block_delta', delta: { type: 'text_delta', text: 'Querying TADIR...' } },
+            // A tool_use block whose JSON never finished arriving.
+            { type: 'content_block_start', content_block: { type: 'tool_use', id: 'tu_1', name: 'sap_sql_query' } },
+            { type: 'content_block_delta', delta: { type: 'input_json_delta', partial_json: '{"query":"SEL' } },
+        ];
+        const stream = makeFakeStream(events, events.length, new Error('terminated'));
+        await runTurnHarness(session, stream);
+        expect(session.turnInterrupted).toBe(true);
+        const assistant = session.messages[1];
+        const content = assistant.content;
+        // text block survived; the partial tool_use was dropped by repair.
+        expect(content).toHaveLength(1);
+        expect(content[0].type).toBe('text');
+        expect(content[0].text).toBe('Querying TADIR...');
+    });
+    it('round-trips the saved session through loadSession with all partial work intact', async () => {
+        const session = newSession('crash-3', 'S4H', 'abap-cca', 'claude-opus-4-7');
+        session.messages.push({ role: 'user', content: '/abap-cca on ZDPR_PAYMENTS' });
+        const events = [
+            { type: 'content_block_start', content_block: { type: 'text', text: '' } },
+            { type: 'content_block_delta', delta: { type: 'text_delta', text: 'Headline: 13 objects.' } },
+        ];
+        const stream = makeFakeStream(events, events.length, new Error('terminated'));
+        await runTurnHarness(session, stream);
+        // Round-trip through disk.
+        const reloaded = await loadSession('crash-3');
+        expect(reloaded.id).toBe('crash-3');
+        expect(reloaded.turnInterrupted).toBe(true);
+        expect(reloaded.turnInterruptedReason).toBe('terminated');
+        expect(reloaded.messages).toHaveLength(2);
+        const assistant = reloaded.messages[1];
+        const content = assistant.content;
+        expect(content[0].text).toBe('Headline: 13 objects.');
+    });
+    it('clean-completion path saves with turnInterrupted=false (clears stale flag)', async () => {
+        const session = newSession('clean-1', 'S4H', 'abap-cca', 'claude-opus-4-7');
+        // Simulate a session that was previously interrupted...
+        session.turnInterrupted = true;
+        session.turnInterruptedReason = 'old';
+        session.messages.push({ role: 'user', content: 'continue' });
+        const events = [
+            { type: 'content_block_start', content_block: { type: 'text', text: '' } },
+            { type: 'content_block_delta', delta: { type: 'text_delta', text: 'OK done.' } },
+        ];
+        const stream = makeFakeStream(events, events.length); // no error → clean run
+        await runTurnHarness(session, stream);
+        // Stale flag cleared on clean completion.
+        expect(session.turnInterrupted).toBe(false);
+        expect(session.turnInterruptedReason).toBeUndefined();
+    });
+    it('REGRESSION: the lost ZDPR_PAYMENTS scenario — 200K-equivalent partial report survives', async () => {
+        // Simulates the actual incident: model emits a thinking block, then a
+        // long final report, then the provider stream "terminated" mid-text.
+        const session = newSession('17c04ce8-sim', 'S4H', 'abap-cca', 'claude-opus-4-7');
+        session.messages.push({ role: 'user', content: '/abap-cca on ZDPR_PAYMENTS' });
+        // Build a 200KB-ish text payload across many deltas — same shape the real
+        // model would produce streaming a long consulting report.
+        const events = [
+            { type: 'content_block_start', content_block: { type: 'thinking', thinking: '' } },
+            { type: 'content_block_delta', delta: { type: 'thinking_delta', thinking: 'Synthesise findings.' } },
+            { type: 'content_block_start', content_block: { type: 'text', text: '' } },
+        ];
+        for (let i = 0; i < 1000; i++) {
+            events.push({
+                type: 'content_block_delta',
+                delta: { type: 'text_delta', text: `paragraph ${i}: ${'lorem ipsum '.repeat(15)}\n` },
+            });
+        }
+        const stream = makeFakeStream(events, events.length, new Error('terminated'));
+        await runTurnHarness(session, stream);
+        expect(session.turnInterrupted).toBe(true);
+        const assistant = session.messages[1];
+        const content = assistant.content;
+        expect(content).toHaveLength(2);
+        expect(content[1].type).toBe('text');
+        // All 1000 paragraphs landed on session.messages — nothing lost.
+        expect(content[1].text).toContain('paragraph 0:');
+        expect(content[1].text).toContain('paragraph 500:');
+        expect(content[1].text).toContain('paragraph 999:');
+        expect(content[1].text.length).toBeGreaterThan(150_000);
+    });
+    it('produces a session that "continue" can read — prior context is intact for the next turn', async () => {
+        const session = newSession('continue-1', 'S4H', 'abap-cca', 'claude-opus-4-7');
+        session.messages.push({ role: 'user', content: '/abap-cca on ZDPR_PAYMENTS' });
+        const events = [
+            { type: 'content_block_start', content_block: { type: 'text', text: '' } },
+            { type: 'content_block_delta', delta: { type: 'text_delta', text: 'Findings so far: 13 objects, 5 years stale.' } },
+        ];
+        const stream = makeFakeStream(events, events.length, new Error('terminated'));
+        await runTurnHarness(session, stream);
+        // Now simulate the "continue" turn: load the session, push a user
+        // message, verify the model would see all prior context.
+        const reloaded = await loadSession('continue-1');
+        reloaded.messages.push({ role: 'user', content: 'continue and emit the full report' });
+        // The model's input is reloaded.messages — verify it contains the full
+        // prior context: original prompt + the partial assistant findings.
+        expect(reloaded.messages).toHaveLength(3);
+        expect(reloaded.messages[0]?.content).toBe('/abap-cca on ZDPR_PAYMENTS');
+        expect((reloaded.messages[1]?.content)[0].text).toContain('5 years stale');
+        expect(reloaded.messages[2]?.content).toBe('continue and emit the full report');
+    });
+});

package/dist/agent/__tests__/loop-save-hook.test.js

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// Mock @inquirer/prompts so the test never blocks on stdin. The save hook's
+// `prompt` callback wraps inquirer's `input`, but the runSaveCommand mock
+// below short-circuits before that callback fires — this is just defence
+// in depth in case the gating logic ever regresses.
+vi.mock('@inquirer/prompts', () => ({
+    input: vi.fn(async () => 'n'),
+}));
+// Mock the projects barrel so we can spy on runSaveCommand calls without
+// touching the filesystem or invoking the real extract/save pipeline.
+// vi.hoisted is required because vi.mock factories run before module-level
+// initialisers, so a plain `const runSaveCommandMock = vi.fn(...)` outside
+// of hoisted() would be undefined inside the factory.
+const { runSaveCommandMock } = vi.hoisted(() => ({
+    runSaveCommandMock: vi.fn(async () => null),
+}));
+vi.mock('../../projects/index.js', () => ({
+    runSaveCommand: runSaveCommandMock,
+}));
+// Import AFTER mocks are registered. ESM module evaluation order matters —
+// imports above must resolve to the mocks, not the real modules.
+import { maybeOfferSave, getAuthorIdentity } from '../loop.js';
+describe('getAuthorIdentity', () => {
+    const ORIG_ENV = { ...process.env };
+    beforeEach(() => {
+        delete process.env.CSPEACH_AUTHOR_NAME;
+        delete process.env.USER;
+        delete process.env.USERNAME;
+    });
+    afterEach(() => {
+        process.env = { ...ORIG_ENV };
+    });
+    it('prefers CSPEACH_AUTHOR_NAME when set', () => {
+        process.env.CSPEACH_AUTHOR_NAME = 'Laeeq';
+        process.env.USER = 'someone-else';
+        expect(getAuthorIdentity()).toEqual({ name: 'Laeeq', role: 'consultant' });
+    });
+    it('falls back to USER, then USERNAME', () => {
+        process.env.USERNAME = 'win-user';
+        expect(getAuthorIdentity()).toEqual({ name: 'win-user', role: 'consultant' });
+        process.env.USER = 'unix-user';
+        expect(getAuthorIdentity()).toEqual({ name: 'unix-user', role: 'consultant' });
+    });
+    it('returns "consultant" when no env vars are set', () => {
+        expect(getAuthorIdentity()).toEqual({ name: 'consultant', role: 'consultant' });
+    });
+});
+describe('maybeOfferSave', () => {
+    beforeEach(() => {
+        runSaveCommandMock.mockClear();
+    });
+    it('invokes runSaveCommand for abap-spec-gap with non-empty text', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-spec-gap',
+            assistantText: '## Found 3 gaps...\n- Q1: ...\n',
+            userMessage: 'Build a customer aging report',
+            tokensUsed: 1234,
+            model: 'claude-opus-4-7',
+            emit,
+        });
+        expect(runSaveCommandMock).toHaveBeenCalledTimes(1);
+        const args = runSaveCommandMock.mock.calls[0][0];
+        expect(args.skillName).toBe('abap-spec-gap');
+        expect(args.skillOutput).toBe('## Found 3 gaps...\n- Q1: ...\n');
+        expect(args.skillInput).toBe('Build a customer aging report');
+        expect(args.tokensUsed).toBe(1234);
+        expect(args.model).toBe('claude-opus-4-7');
+        expect(args.skillVersion).toBe('1.0');
+        expect(args.author).toEqual({
+            name: expect.any(String),
+            role: 'consultant',
+        });
+        expect(typeof args.prompt).toBe('function');
+        expect(typeof args.log).toBe('function');
+        expect(typeof args.cwd).toBe('string');
+    });
+    it('does NOT invoke runSaveCommand for non-spec-gap skills', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-radar',
+            assistantText: 'Some lengthy radar output',
+            userMessage: 'analyze ZCL_FOO',
+            tokensUsed: 100,
+            model: 'm',
+            emit,
+        });
+        expect(runSaveCommandMock).not.toHaveBeenCalled();
+    });
+    it('does NOT invoke runSaveCommand when assistantText is empty', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-spec-gap',
+            assistantText: '',
+            userMessage: 'something',
+            tokensUsed: 0,
+            model: 'm',
+            emit,
+        });
+        expect(runSaveCommandMock).not.toHaveBeenCalled();
+    });
+    it('does NOT invoke runSaveCommand when assistantText is whitespace only', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-spec-gap',
+            assistantText: '   \n\n   ',
+            userMessage: 'something',
+            tokensUsed: 0,
+            model: 'm',
+            emit,
+        });
+        expect(runSaveCommandMock).not.toHaveBeenCalled();
+    });
+    it('swallows errors from runSaveCommand and emits a [save] warning', async () => {
+        runSaveCommandMock.mockRejectedValueOnce(new Error('parse blew up'));
+        const emit = vi.fn();
+        await expect(maybeOfferSave({
+            skill: 'abap-spec-gap',
+            assistantText: '## gaps',
+            userMessage: 'x',
+            tokensUsed: 1,
+            model: 'm',
+            emit,
+        })).resolves.toBeUndefined();
+        const emitted = emit.mock.calls.flat().join('\n');
+        expect(emitted).toContain('[save]');
+        expect(emitted).toContain('parse blew up');
+    });
+    // v0.5: design + estimate join the save-hook list
+    it('invokes runSaveCommand for abap-design', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-design',
+            assistantText: '## ABAP Design — X\n\n### Objects to Create\n| # | Name | Type | Purpose | Transport |\n|---|---|---|---|---|\n| 1 | ZCL_X | CLAS | x | $TMP |\n',
+            userMessage: 'design X',
+            tokensUsed: 5000,
+            model: 'm',
+            emit,
+        });
+        expect(runSaveCommandMock).toHaveBeenCalledTimes(1);
+        expect(runSaveCommandMock.mock.calls[0][0].skillName).toBe('abap-design');
+    });
+    it('invokes runSaveCommand for abap-estimate', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-estimate',
+            assistantText: '## Effort Estimate — X\n\n### Component Breakdown\n| # | Component | Objects | Optimistic (h) | Realistic (h) | Pessimistic (h) | Notes |\n|---|---|---|---|---|---|---|\n| 1 | x | y | 1 | 2 | 3 | n |\n',
+            userMessage: 'estimate X',
+            tokensUsed: 4000,
+            model: 'm',
+            emit,
+        });
+        expect(runSaveCommandMock).toHaveBeenCalledTimes(1);
+        expect(runSaveCommandMock.mock.calls[0][0].skillName).toBe('abap-estimate');
+    });
+    it('threads promotedFrom into runSaveCommand when supplied', async () => {
+        const emit = vi.fn();
+        const promotedFrom = {
+            id: 'src-uuid', title: 'Src', artefactType: 'spec-gap', version: 3,
+            sha256: 'a'.repeat(64), snapshottedAt: '2026-05-05T10:00:00Z',
+            snapshot: { items: [{ id: 'gap-001', text: 'Q', severity: 'BLOCKER', status: 'answered', answer: 'A' }] },
+        };
+        await maybeOfferSave({
+            skill: 'abap-design',
+            assistantText: '## ABAP Design — X',
+            userMessage: 'x',
+            tokensUsed: 1,
+            model: 'm',
+            emit,
+            promotedFrom,
+        });
+        const args = runSaveCommandMock.mock.calls[0][0];
+        expect(args.promotedFrom).toEqual(promotedFrom);
+    });
+    it('passes promotedFrom: null when omitted (non-promoted runs)', async () => {
+        const emit = vi.fn();
+        await maybeOfferSave({
+            skill: 'abap-spec-gap',
+            assistantText: '## Gaps',
+            userMessage: 'x',
+            tokensUsed: 1,
+            model: 'm',
+            emit,
+        });
+        const args = runSaveCommandMock.mock.calls[0][0];
+        expect(args.promotedFrom).toBeNull();
+    });
+});