@cspeach/cli 0.6.3 → 0.6.4

package/dist/agent/__tests__/sap-connection-adapter.test.js

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest';
+import { buildSapConnectionContext } from '../sap-connection-adapter.js';
+const onPremS4 = {
+    alias: 'S4H',
+    platform: 'S/4HANA',
+    release: 'S/4HANA 2023',
+    abapVersion: '7.58',
+    deployment: 'on-prem-or-private-cloud',
+    components: { SAP_BASIS: '758' },
+    queriedAt: '2026-05-10T10:00:00Z',
+};
+const cloudInfo = {
+    alias: 'CLOUD',
+    platform: 'S/4HANA',
+    release: 'S/4HANA Cloud, public 2402',
+    abapVersion: 'cloud',
+    deployment: 'public-cloud',
+    components: { SAP_BASIS: '780' },
+    queriedAt: '2026-05-10T10:00:00Z',
+};
+describe('buildSapConnectionContext — alias + null system info', () => {
+    it('returns a context with the alias and unknown system summary', () => {
+        const ctx = buildSapConnectionContext('S4H', null);
+        expect(ctx.alias).toBe('S4H');
+        expect(ctx.system).toEqual({
+            sid: null,
+            release: null,
+            abapVersion: null,
+            platform: 'unknown',
+            host: null,
+        });
+        expect(ctx.currentTransport).toBeNull();
+        expect(ctx.activeScope).toBeNull();
+        expect(ctx.recentObjects).toEqual([]);
+    });
+});
+describe('buildSapConnectionContext — system info mapping', () => {
+    it('maps on-prem deployment + release + abapVersion', () => {
+        const ctx = buildSapConnectionContext('S4H', onPremS4);
+        expect(ctx.system).toMatchObject({
+            release: 'S/4HANA 2023',
+            abapVersion: '7.58',
+            platform: 'on-premise',
+            sid: null,
+            host: null,
+        });
+    });
+    it('maps public-cloud deployment to platform=cloud', () => {
+        const ctx = buildSapConnectionContext('CLOUD', cloudInfo);
+        expect(ctx.system.platform).toBe('cloud');
+        expect(ctx.system.release).toBe('S/4HANA Cloud, public 2402');
+    });
+    it('falls back to platform=unknown for unknown deployment', () => {
+        const info = { ...onPremS4, deployment: 'unknown' };
+        const ctx = buildSapConnectionContext('X', info);
+        expect(ctx.system.platform).toBe('unknown');
+    });
+    it('coerces empty release / abapVersion to null', () => {
+        const info = { ...onPremS4, release: '', abapVersion: '' };
+        const ctx = buildSapConnectionContext('X', info);
+        expect(ctx.system.release).toBeNull();
+        expect(ctx.system.abapVersion).toBeNull();
+    });
+});
+describe('buildSapConnectionContext — state passthrough', () => {
+    it('passes through currentTransport when provided', () => {
+        const ctx = buildSapConnectionContext('S4H', onPremS4, {
+            currentTransport: 'S4HK900123',
+        });
+        expect(ctx.currentTransport).toBe('S4HK900123');
+    });
+    it('builds activeScope when activePackage is set', () => {
+        const ctx = buildSapConnectionContext('S4H', onPremS4, {
+            activePackage: 'ZFI_PAYMENTS',
+        });
+        expect(ctx.activeScope).toEqual({
+            package: 'ZFI_PAYMENTS',
+            object: null,
+        });
+    });
+    it('builds activeScope when activeObject is set', () => {
+        const ctx = buildSapConnectionContext('S4H', onPremS4, {
+            activeObject: { name: 'ZCL_PAY', type: 'CLAS' },
+        });
+        expect(ctx.activeScope).toEqual({
+            package: null,
+            object: { name: 'ZCL_PAY', type: 'CLAS' },
+        });
+    });
+    it('returns activeScope=null when neither package nor object is set', () => {
+        const ctx = buildSapConnectionContext('S4H', onPremS4, {});
+        expect(ctx.activeScope).toBeNull();
+    });
+    it('passes through recentObjects (capped behavior is the renderer\'s job)', () => {
+        const refs = [
+            { name: 'ZCL_PAY', type: 'CLAS', lastTouchedAt: '2026-05-10T10:00:00Z', lastAction: 'read' },
+            { name: 'ZIF_PAY', type: 'INTF', lastTouchedAt: '2026-05-10T10:01:00Z', lastAction: 'write' },
+        ];
+        const ctx = buildSapConnectionContext('S4H', onPremS4, { recentObjects: refs });
+        expect(ctx.recentObjects).toEqual(refs);
+    });
+});
+describe('buildSapConnectionContext — composes correctly with everything', () => {
+    it('full live-SAP context end-to-end', () => {
+        const ctx = buildSapConnectionContext('S4H', onPremS4, {
+            currentTransport: 'S4HK900123',
+            activePackage: 'ZFI_PAYMENTS',
+            activeObject: { name: 'ZCL_PAY', type: 'CLAS' },
+            recentObjects: [
+                { name: 'ZCL_PAY', type: 'CLAS', lastTouchedAt: '2026-05-10T10:00:00Z', lastAction: 'read' },
+            ],
+        });
+        expect(ctx).toEqual({
+            alias: 'S4H',
+            system: {
+                sid: null,
+                release: 'S/4HANA 2023',
+                abapVersion: '7.58',
+                platform: 'on-premise',
+                host: null,
+            },
+            currentTransport: 'S4HK900123',
+            activeScope: {
+                package: 'ZFI_PAYMENTS',
+                object: { name: 'ZCL_PAY', type: 'CLAS' },
+            },
+            recentObjects: [
+                { name: 'ZCL_PAY', type: 'CLAS', lastTouchedAt: '2026-05-10T10:00:00Z', lastAction: 'read' },
+            ],
+        });
+    });
+});

package/dist/agent/__tests__/skill-checkpoint.test.js

@@ -0,0 +1,154 @@
+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 { applyToolResultCheckpoint, registerCheckpointHandler, checkpointsRoot, _resetHandlersForTesting, } from '../skill-checkpoint.js';
+const ORIGINAL_HOME = os.homedir();
+describe('applyToolResultCheckpoint (Layer 2)', () => {
+    let tempHome;
+    beforeEach(async () => {
+        tempHome = await fs.mkdtemp(path.join(os.tmpdir(), 'skill-checkpoint-'));
+        process.env.HOME = tempHome;
+        process.env.USERPROFILE = tempHome;
+        _resetHandlersForTesting();
+    });
+    afterEach(async () => {
+        process.env.HOME = ORIGINAL_HOME;
+        process.env.USERPROFILE = ORIGINAL_HOME;
+        await fs.rm(tempHome, { recursive: true, force: true });
+        _resetHandlersForTesting();
+    });
+    function makeInput(overrides = {}) {
+        return {
+            sessionId: 'test-sess',
+            skill: 'abap-cca',
+            toolName: 'sap_sql_query',
+            args: { query: 'SELECT * FROM TADIR WHERE DEVCLASS = ?' },
+            result: '[{"OBJ_NAME":"ZFOO","OBJECT":"PROG"}]',
+            isError: false,
+            durationMs: 382,
+            completedAt: '2026-05-09T20:09:56.746Z',
+            ...overrides,
+        };
+    }
+    it('appends a JSONL row to ~/.cspeach/checkpoints/<sessionId>/tool-calls.jsonl', async () => {
+        await applyToolResultCheckpoint(makeInput());
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const content = await fs.readFile(filePath, 'utf-8');
+        expect(content.trim().split('\n')).toHaveLength(1);
+        const row = JSON.parse(content.trim());
+        expect(row.tool).toBe('sap_sql_query');
+        expect(row.ok).toBe(true);
+        expect(row.duration_ms).toBe(382);
+        expect(row.at).toBe('2026-05-09T20:09:56.746Z');
+    });
+    it('appends multiple rows in order without overwriting', async () => {
+        await applyToolResultCheckpoint(makeInput({ toolName: 'sap_sql_query' }));
+        await applyToolResultCheckpoint(makeInput({ toolName: 'sap_search_object' }));
+        await applyToolResultCheckpoint(makeInput({ toolName: 'sap_atc_run' }));
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const lines = (await fs.readFile(filePath, 'utf-8')).trim().split('\n');
+        expect(lines).toHaveLength(3);
+        expect(JSON.parse(lines[0]).tool).toBe('sap_sql_query');
+        expect(JSON.parse(lines[1]).tool).toBe('sap_search_object');
+        expect(JSON.parse(lines[2]).tool).toBe('sap_atc_run');
+    });
+    it('captures errored tool calls with ok=false', async () => {
+        await applyToolResultCheckpoint(makeInput({
+            isError: true,
+            result: 'SAP HTTP 400: sqlQuery',
+        }));
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const row = JSON.parse((await fs.readFile(filePath, 'utf-8')).trim());
+        expect(row.ok).toBe(false);
+    });
+    it('truncates oversized result payloads to ~4 KB', async () => {
+        const huge = 'x'.repeat(10_000);
+        await applyToolResultCheckpoint(makeInput({ result: huge }));
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const row = JSON.parse((await fs.readFile(filePath, 'utf-8')).trim());
+        expect(row.result.length).toBeLessThanOrEqual(4100);
+        expect(row.result).toMatch(/\.\.\.$/);
+    });
+    it('separates sessions into different directories', async () => {
+        await applyToolResultCheckpoint(makeInput({ sessionId: 'sess-a' }));
+        await applyToolResultCheckpoint(makeInput({ sessionId: 'sess-b' }));
+        const a = await fs.readFile(path.join(checkpointsRoot(), 'sess-a', 'tool-calls.jsonl'), 'utf-8');
+        const b = await fs.readFile(path.join(checkpointsRoot(), 'sess-b', 'tool-calls.jsonl'), 'utf-8');
+        expect(a.trim().split('\n')).toHaveLength(1);
+        expect(b.trim().split('\n')).toHaveLength(1);
+    });
+    it('runs even when no skill handler is registered (default JSONL is unconditional)', async () => {
+        await applyToolResultCheckpoint(makeInput({ skill: 'unknown-skill' }));
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const stat = await fs.stat(filePath);
+        expect(stat.size).toBeGreaterThan(0);
+    });
+    it('dispatches to a registered skill-specific handler', async () => {
+        const calls = [];
+        const handler = {
+            skill: 'abap-cca',
+            apply: async (input) => { calls.push(input); },
+        };
+        registerCheckpointHandler(handler);
+        await applyToolResultCheckpoint(makeInput({ skill: 'abap-cca' }));
+        expect(calls).toHaveLength(1);
+        expect(calls[0]?.toolName).toBe('sap_sql_query');
+    });
+    it('does NOT dispatch to handlers for other skills', async () => {
+        const calls = [];
+        registerCheckpointHandler({
+            skill: 'abap-cca',
+            apply: async (input) => { calls.push(input); },
+        });
+        await applyToolResultCheckpoint(makeInput({ skill: 'abap-other' }));
+        expect(calls).toHaveLength(0);
+    });
+    it('swallows handler errors so a checkpoint failure never breaks a turn', async () => {
+        registerCheckpointHandler({
+            skill: 'abap-cca',
+            apply: async () => { throw new Error('handler exploded'); },
+        });
+        // Should not throw out — best-effort contract.
+        await expect(applyToolResultCheckpoint(makeInput())).resolves.toBeUndefined();
+        // Default JSONL still landed.
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const stat = await fs.stat(filePath);
+        expect(stat.size).toBeGreaterThan(0);
+    });
+    it('handles unstringifiable args without crashing', async () => {
+        const cyclic = {};
+        cyclic.self = cyclic;
+        await applyToolResultCheckpoint(makeInput({ args: cyclic }));
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const row = JSON.parse((await fs.readFile(filePath, 'utf-8')).trim());
+        expect(row.args).toBe('<unstringifiable>');
+    });
+    it('REGRESSION: a 30-tool-call turn produces a recoverable JSONL log', async () => {
+        // Mirror the /abap-cca DISCOVER+INVENTORY+ANALYZE pattern — many SQL
+        // probes followed by a few ATC + source-read calls. JSONL must contain
+        // every call with ordering preserved.
+        const calls = [
+            ...Array.from({ length: 25 }, (_, i) => ({
+                toolName: 'sap_sql_query',
+                args: { query: `SELECT * FROM TADIR WHERE DEVCLASS = 'ZPKG${i}'` },
+            })),
+            { toolName: 'sap_atc_run', args: { name: 'ZPAYMENTS', type: 'PROG' } },
+            { toolName: 'sap_get_source', args: { name: 'ZPAYMENTS', type: 'PROG' } },
+            { toolName: 'sap_get_source', args: { name: 'ZPAYMENTS_OLD', type: 'PROG' } },
+            { toolName: 'sap_usage_references', args: { name: 'ZPAYMENTS', type: 'PROG' } },
+            { toolName: 'sap_api_state', args: { objects: 'TABL:BSIK' } },
+        ];
+        for (const c of calls) {
+            await applyToolResultCheckpoint(makeInput(c));
+        }
+        const filePath = path.join(checkpointsRoot(), 'test-sess', 'tool-calls.jsonl');
+        const lines = (await fs.readFile(filePath, 'utf-8')).trim().split('\n');
+        expect(lines).toHaveLength(30);
+        // Verify ordering preserved.
+        expect(JSON.parse(lines[0]).tool).toBe('sap_sql_query');
+        expect(JSON.parse(lines[24]).tool).toBe('sap_sql_query');
+        expect(JSON.parse(lines[25]).tool).toBe('sap_atc_run');
+        expect(JSON.parse(lines[29]).tool).toBe('sap_api_state');
+    });
+});

package/dist/agent/__tests__/turn-assistant-text.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { collectTurnAssistantText } from '../turn-assistant-text.js';
+describe('collectTurnAssistantText', () => {
+    it('returns the FULL turn-worth of assistant text when manifest lives in a non-final message', () => {
+        // The bug this fixes: /abap-cca emits the manifest in an earlier
+        // assistant message, then calls ask_question, then emits a wrap-up
+        // message. The pre-fix call site read only the final message and
+        // missed the manifest entirely. This test pins the regression.
+        const messages = [
+            { role: 'user', content: 'go' },
+            // First assistant message: contains the manifest
+            {
+                role: 'assistant',
+                content: [
+                    { type: 'text', text: 'Long report ...\n<!-- csforge:cca-manifest\nartefact: cca-assessment\n-->' },
+                    { type: 'tool_use', name: 'ask_question', input: {} },
+                ],
+            },
+            // tool_result lands as a user message
+            { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'x', content: 'done' }] },
+            // Second assistant message: closing prose, NO manifest
+            {
+                role: 'assistant',
+                content: [{ type: 'text', text: 'Done. Closing out.' }],
+            },
+        ];
+        const out = collectTurnAssistantText(messages, 1);
+        expect(out).toContain('csforge:cca-manifest');
+        expect(out).toContain('Done. Closing out.');
+    });
+    it('joins multiple assistant messages with \\n\\n separators', () => {
+        const messages = [
+            { role: 'user', content: 'go' },
+            { role: 'assistant', content: [{ type: 'text', text: 'first' }] },
+            { role: 'user', content: [{ type: 'tool_result', tool_use_id: 't', content: 'x' }] },
+            { role: 'assistant', content: [{ type: 'text', text: 'second' }] },
+        ];
+        expect(collectTurnAssistantText(messages, 1)).toBe('first\n\nsecond');
+    });
+    it('skips non-text content blocks (tool_use, tool_result wrapped, etc.)', () => {
+        const messages = [
+            {
+                role: 'assistant',
+                content: [
+                    { type: 'tool_use', name: 'sap_sql_query', input: { sql: 'SELECT' } },
+                    { type: 'text', text: 'visible' },
+                ],
+            },
+        ];
+        expect(collectTurnAssistantText(messages, 0)).toBe('visible');
+    });
+    it('skips user / system / tool messages entirely', () => {
+        const messages = [
+            { role: 'user', content: 'should not appear' },
+            { role: 'assistant', content: [{ type: 'text', text: 'asst-text' }] },
+            { role: 'user', content: [{ type: 'tool_result', tool_use_id: 't', content: 'result' }] },
+        ];
+        expect(collectTurnAssistantText(messages, 0)).toBe('asst-text');
+    });
+    it('returns empty string when no messages exist past turnStartCount', () => {
+        expect(collectTurnAssistantText([], 0)).toBe('');
+        expect(collectTurnAssistantText([{ role: 'user', content: 'x' }], 5)).toBe('');
+        expect(collectTurnAssistantText([{ role: 'user', content: 'x' }], 1)).toBe('');
+    });
+    it('treats non-string content arrays gracefully (string content, malformed blocks)', () => {
+        const messages = [
+            { role: 'assistant', content: 'this is a string, not an array' },
+            { role: 'assistant', content: [{ type: 'text', text: null }] },
+            { role: 'assistant', content: [{ type: 'text', text: 'valid' }] },
+        ];
+        expect(collectTurnAssistantText(messages, 0)).toBe('valid');
+    });
+});

package/dist/agent/__tests__/turn-error-ux.test.js

@@ -0,0 +1,145 @@
+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 { describeError, renderTurnError, logsRoot } from '../turn-error-ux.js';
+const ORIGINAL_HOME = os.homedir();
+describe('describeError', () => {
+    it('translates "terminated" to a human phrase', () => {
+        expect(describeError(new Error('terminated'))).toBe('provider stream closed mid-response');
+    });
+    it('translates ECONNRESET', () => {
+        expect(describeError(new Error('ECONNRESET'))).toBe('network connection reset');
+    });
+    it('translates ETIMEDOUT', () => {
+        expect(describeError(new Error('ETIMEDOUT'))).toBe('network timeout');
+    });
+    it('passes through unknown messages truncated to 200 chars', () => {
+        const long = 'x'.repeat(500);
+        expect(describeError(new Error(long))).toBe('x'.repeat(200));
+    });
+    it('handles non-Error throws (string, number)', () => {
+        expect(describeError('plain string')).toBe('plain string');
+        expect(describeError(42)).toBe('42');
+    });
+    it('handles null and undefined', () => {
+        expect(describeError(null)).toBe('unknown error');
+        expect(describeError(undefined)).toBe('unknown error');
+    });
+});
+describe('renderTurnError', () => {
+    let tempHome;
+    beforeEach(async () => {
+        tempHome = await fs.mkdtemp(path.join(os.tmpdir(), 'turn-error-ux-'));
+        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 });
+    });
+    it('prints a clean 4-6 line block with session id and resume hint', async () => {
+        const lines = [];
+        await renderTurnError({
+            err: new Error('terminated'),
+            session: { id: '17c04ce8' },
+            print: (l) => lines.push(l),
+        });
+        const text = lines.join('\n');
+        // Strip ANSI for content checks (chalk colours).
+        // eslint-disable-next-line no-control-regex
+        const plain = text.replace(/\x1b\[[0-9;]*m/g, '');
+        expect(plain).toContain('Turn interrupted: provider stream closed mid-response');
+        expect(plain).toContain('Session: 17c04ce8');
+        expect(plain).toContain('Resume:  cspeach --resume 17c04ce8');
+        // 6 content lines + 2 blank → 8 total.
+        expect(lines.length).toBeGreaterThanOrEqual(5);
+        expect(lines.length).toBeLessThanOrEqual(8);
+    });
+    it('writes a diagnostic log file under ~/.cspeach/logs/', async () => {
+        const err = new Error('terminated');
+        await renderTurnError({
+            err,
+            session: { id: 'abc12345' },
+            print: () => { },
+        });
+        const dir = logsRoot();
+        const files = await fs.readdir(dir);
+        const match = files.find((f) => f.startsWith('abc12345-') && f.endsWith('.log'));
+        expect(match).toBeDefined();
+        const content = await fs.readFile(path.join(dir, match), 'utf-8');
+        expect(content).toContain('# CSPeach turn error log');
+        expect(content).toContain('session: abc12345');
+        expect(content).toContain('Error: terminated');
+        expect(content).toContain('## stack');
+    });
+    it('includes the stream path when provided', async () => {
+        const lines = [];
+        await renderTurnError({
+            err: new Error('terminated'),
+            session: { id: 'abc' },
+            streamFilePath: '/path/to/stream.md',
+            print: (l) => lines.push(l),
+        });
+        // eslint-disable-next-line no-control-regex
+        const plain = lines.join('\n').replace(/\x1b\[[0-9;]*m/g, '');
+        expect(plain).toContain('Stream:  /path/to/stream.md');
+    });
+    it('handles non-Error throws gracefully', async () => {
+        const lines = [];
+        await renderTurnError({
+            err: 'something exploded',
+            session: { id: 'abc' },
+            print: (l) => lines.push(l),
+        });
+        // eslint-disable-next-line no-control-regex
+        const plain = lines.join('\n').replace(/\x1b\[[0-9;]*m/g, '');
+        expect(plain).toContain('Turn interrupted: something exploded');
+    });
+    it('REGRESSION: replaces the bare [error] terminated UX with actionable info', async () => {
+        // The original v0.5 UX was a single line: "[error] terminated".
+        // After fix, the user sees: cause, session id, log path, resume hint.
+        const lines = [];
+        await renderTurnError({
+            err: new Error('terminated'),
+            session: { id: '17c04ce8' },
+            print: (l) => lines.push(l),
+        });
+        // eslint-disable-next-line no-control-regex
+        const plain = lines.join('\n').replace(/\x1b\[[0-9;]*m/g, '');
+        expect(plain).not.toBe('[error] terminated');
+        expect(plain).toContain('Resume:');
+        expect(plain).toContain('Log:');
+        expect(plain).toContain('17c04ce8');
+    });
+    it('userInterrupted=true frames as cancellation, not crash', async () => {
+        const lines = [];
+        await renderTurnError({
+            err: new Error('aborted'),
+            session: { id: 'abc' },
+            userInterrupted: true,
+            print: (l) => lines.push(l),
+        });
+        // eslint-disable-next-line no-control-regex
+        const plain = lines.join('\n').replace(/\x1b\[[0-9;]*m/g, '');
+        expect(plain).toContain('Turn cancelled.');
+        expect(plain).not.toContain('Turn interrupted');
+        expect(plain).toContain('Resume:');
+        // No log file written for user cancellations — they're not bugs.
+        expect(plain).not.toContain('Log:');
+    });
+    it('userInterrupted=true skips writing a diagnostic log file', async () => {
+        const before = await fs.readdir(logsRoot()).catch(() => []);
+        await renderTurnError({
+            err: new Error('aborted'),
+            session: { id: 'cancel-test' },
+            userInterrupted: true,
+            print: () => { },
+        });
+        const after = await fs.readdir(logsRoot()).catch(() => []);
+        // No new log files were created.
+        const newFiles = after.filter((f) => !before.includes(f) && f.startsWith('cancel-test-'));
+        expect(newFiles).toHaveLength(0);
+    });
+});

package/dist/agent/__tests__/turn-stream.test.js

@@ -0,0 +1,100 @@
+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 { TurnStreamWriter } from '../turn-stream.js';
+// Redirect HOME so streamsRoot() lands inside a temp dir for the test run.
+// Restored in afterEach.
+const ORIGINAL_HOME = os.homedir();
+describe('TurnStreamWriter', () => {
+    let tempHome;
+    beforeEach(async () => {
+        tempHome = await fs.mkdtemp(path.join(os.tmpdir(), 'turn-stream-'));
+        process.env.HOME = tempHome;
+        process.env.USERPROFILE = tempHome;
+    });
+    afterEach(async () => {
+        process.env.HOME = ORIGINAL_HOME;
+        process.env.USERPROFILE = ORIGINAL_HOME;
+        // maxRetries handles Windows fs.rm ENOTEMPTY when a transient handle
+        // is still held on freshly-written stream files under parallel-suite load.
+        await fs.rm(tempHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    });
+    it('writes nothing when never appended (no empty file pollution)', async () => {
+        const w = new TurnStreamWriter('test-session-1');
+        await w.close();
+        await expect(fs.access(w.path())).rejects.toThrow();
+    });
+    it('appends text and creates the file lazily', async () => {
+        const w = new TurnStreamWriter('test-session-2');
+        await w.append('Hello, ');
+        await w.append('world.');
+        const content = await fs.readFile(w.path(), 'utf-8');
+        expect(content).toContain('# CSPeach turn stream');
+        expect(content).toContain('Hello, world.');
+    });
+    it('writes the file under ~/.cspeach/streams/<sessionId>/<ts>.md', async () => {
+        const startedAt = new Date('2026-05-09T20:09:56.746Z');
+        const w = new TurnStreamWriter('17c04ce8', startedAt);
+        await w.append('any text');
+        const expectedPrefix = path.join(tempHome, '.cspeach', 'streams', '17c04ce8');
+        expect(w.path().startsWith(expectedPrefix)).toBe(true);
+        expect(w.path()).toContain('2026-05-09T20-09-56-746Z');
+    });
+    it('close adds a default footer', async () => {
+        const w = new TurnStreamWriter('test-session-3');
+        await w.append('body content');
+        await w.close();
+        const content = await fs.readFile(w.path(), 'utf-8');
+        expect(content).toContain('body content');
+        expect(content).toContain('---');
+        expect(content).toContain('_closed ');
+    });
+    it('close with interrupted footer marks the failure reason', async () => {
+        const w = new TurnStreamWriter('test-session-4');
+        await w.append('partial output before crash');
+        await w.close('_interrupted: terminated_');
+        const content = await fs.readFile(w.path(), 'utf-8');
+        expect(content).toContain('partial output before crash');
+        expect(content).toContain('_interrupted: terminated_');
+    });
+    it('skips empty appends', async () => {
+        const w = new TurnStreamWriter('test-session-5');
+        await w.append('');
+        await w.append(undefined);
+        await w.close();
+        // Nothing was ever written → file does not exist.
+        await expect(fs.access(w.path())).rejects.toThrow();
+    });
+    it('close is idempotent for unused writers', async () => {
+        const w = new TurnStreamWriter('test-session-6');
+        await w.close();
+        await w.close();
+        await expect(fs.access(w.path())).rejects.toThrow();
+    });
+    it('REGRESSION: simulates a 200KB-ish report stream — content survives intact', async () => {
+        // Real-world worst case: model emits a large consulting report and the
+        // stream cuts mid-flight. Even at 200KB the writer must produce a complete
+        // file with all the streamed text.
+        // Bumped timeout: on Windows under parallel-test-file load, 1000
+        // sequential appends + tempdir cleanup can exceed the default 5s.
+        // Same Phase-1.5 pattern as index-files truncate test — large-N
+        // filesystem tests on Windows are timeout-sensitive under load.
+        const w = new TurnStreamWriter('test-session-7');
+        // Emit 1000 chunks of ~200 bytes each = ~200 KB
+        for (let i = 0; i < 1000; i++) {
+            await w.append(`chunk ${i.toString().padStart(4, '0')}: ${'lorem ipsum '.repeat(15)}\n`);
+        }
+        await w.close('_interrupted: terminated_');
+        const content = await fs.readFile(w.path(), 'utf-8');
+        // Spot-check that all chunks landed and the file ends with the
+        // interruption footer.
+        expect(content).toContain('chunk 0000:');
+        expect(content).toContain('chunk 0500:');
+        expect(content).toContain('chunk 0999:');
+        expect(content).toContain('_interrupted: terminated_');
+        // Sanity on size — should be in the right ballpark.
+        const stats = await fs.stat(w.path());
+        expect(stats.size).toBeGreaterThan(150_000);
+    }, 60_000);
+});