@pellux/goodvibes-sdk 0.38.0 → 1.1.0

package/dist/platform/companion/companion-chat-manager.js

@@ -19,12 +19,16 @@
  *   for that specific session — never the global TUI event feed.
  * - A GC sweep closes sessions that have been idle beyond the TTL.
  */
-import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
+import { SDKErrorCodes } from '@pellux/goodvibes-errors';
 import { ConversationManager } from '../core/conversation.js';
 import { CompanionChatPersistence, defaultSessionsDir, } from './companion-chat-persistence.js';
+import { buildProviderUserContent, buildReplayUserContent, resolveAttachments, } from './companion-chat-attachments.js';
+import { activeMessages, applyEditBranch, planRegenerate, } from './companion-chat-branching.js';
+import { executeCompanionToolCalls, runToolExhaustionFinalizer, } from './companion-chat-turn-execution.js';
+import { planCompanionSweep } from './companion-chat-gc.js';
+import { CompanionBrokerSync } from './companion-chat-broker-sync.js';
 import { CompanionChatRateLimiter } from './companion-chat-rate-limiter.js';
-import { executeToolCalls as executeOrchestratorToolCalls } from '../core/orchestrator-tool-runtime.js';
 import { appendGoodVibesRuntimeAwarenessPrompt } from '../tools/goodvibes-runtime/index.js';
 import { summarizeError } from '../utils/error-display.js';
 import { logger } from '../utils/logger.js';
@@ -33,6 +37,7 @@ import { logger } from '../utils/logger.js';
 // ---------------------------------------------------------------------------
 const DEFAULT_IDLE_ACTIVE_MS = 30 * 60 * 1_000; // 30 minutes with messages
 const DEFAULT_IDLE_EMPTY_MS = 5 * 60 * 1_000; // 5 minutes empty session
+const DEFAULT_CLOSED_MEMORY_GRACE_MS = 5 * 60 * 1_000; // evict closed bodies from RAM after 5 min
 const GC_INTERVAL_MS = 60 * 1_000; // sweep every minute
 const MAX_TOOL_ROUNDS_PER_TURN = 8;
 const TOOL_EXHAUSTION_FINALIZER_PROMPT = [
@@ -42,16 +47,6 @@ const TOOL_EXHAUSTION_FINALIZER_PROMPT = [
     'If the available tool results are insufficient, say what is missing and ask one short follow-up '
         + 'question.',
 ].join(' ');
-const MAX_ATTACHMENTS_PER_MESSAGE = 8;
-const MAX_INLINE_IMAGE_ATTACHMENT_BYTES = 20 * 1024 * 1024;
-const MAX_INLINE_TEXT_ATTACHMENT_BYTES = 200 * 1024;
-function toNodeBuffer(buffer) {
-    if (Buffer.isBuffer(buffer))
-        return buffer;
-    if (buffer instanceof ArrayBuffer)
-        return Buffer.from(new Uint8Array(buffer));
-    return Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-}
 function assertCompleteProviderModelRoute(input) {
     if ((input.model !== undefined) === (input.provider !== undefined))
         return;
@@ -73,6 +68,10 @@ export class CompanionChatManager {
     rateLimiter;
     idleActiveMs;
     idleEmptyMs;
+    closedMemoryGraceMs;
+    closedRetentionMs;
+    /** Live mirror of sessions into the shared broker store (S1 item D). */
+    _brokerSync;
     gcTimer = null;
     /** Tracks whether the async init() has completed. */
     initCompleted = false;
@@ -93,13 +92,17 @@ export class CompanionChatManager {
         this.artifactStore = config.artifactStore ?? null;
         this.idleActiveMs = config.idleActiveMs ?? DEFAULT_IDLE_ACTIVE_MS;
         this.idleEmptyMs = config.idleEmptyMs ?? DEFAULT_IDLE_EMPTY_MS;
+        this.closedMemoryGraceMs = config.closedSessionMemoryGraceMs ?? DEFAULT_CLOSED_MEMORY_GRACE_MS;
+        this.closedRetentionMs = config.closedSessionRetentionMs;
+        this._brokerSync = new CompanionBrokerSync(config.sessionBroker ?? null);
         // Persistence
         // Default is false — most callers (tests, downstream consumers) get the
         // safe no-write default. The daemon opts into persistence explicitly via
-        // persist: true in facade-composition.
+        // persist: true in facade-composition. When sessionsDir is omitted, derive
+        // the root from the INJECTED home so an isolated-home daemon stays inside it.
         const persist = config.persist === true;
         this.persistence = persist
-            ? new CompanionChatPersistence(config.sessionsDir ?? defaultSessionsDir())
+            ? new CompanionChatPersistence(config.sessionsDir ?? defaultSessionsDir(config.homeDirectory))
             : null;
         // Rate limiter
         this.rateLimiter =
@@ -130,18 +133,18 @@ export class CompanionChatManager {
         const stored = await this.persistence.loadAll();
         for (const { meta, messages } of stored) {
             const normalizedMessages = messages.map((message) => this.normalizeMessage(message));
-            // Skip sessions that were already closed before the restart — they are
-            // in a terminal state and don't need to be in memory.
-            if (meta.status === 'closed')
-                continue;
             const conversation = new ConversationManager();
-            // Replay messages into the conversation to restore LLM context
-            for (const msg of normalizedMessages) {
-                if (msg.role === 'user') {
-                    conversation.addUserMessage(this.buildReplayUserContent(msg));
-                }
-                else {
-                    conversation.addAssistantMessage(msg.content);
+            // Closed-skip fix: closed sessions load in a lightweight terminal state
+            // (meta + messages retained, listable/importable; no history replay). GC
+            // (_gcSweep) remains the sole deletion authority.
+            if (meta.status !== 'closed') {
+                for (const msg of normalizedMessages) {
+                    if (msg.role === 'user') {
+                        conversation.addUserMessage(buildReplayUserContent(msg));
+                    }
+                    else {
+                        conversation.addAssistantMessage(msg.content);
+                    }
                 }
             }
             this.sessions.set(meta.id, {
@@ -185,6 +188,9 @@ export class CompanionChatManager {
             subscriberClientId: null,
         });
         this._persist(id);
+        // Live spine: mirror the new session into the shared broker at write time so
+        // /api/sessions reflects it same-process (no restart). Best-effort.
+        this._brokerSync.track(meta.id, () => this._brokerSync.registerSession(meta));
         return meta;
     }
     getSession(sessionId) {
@@ -226,7 +232,7 @@ export class CompanionChatManager {
             throw Object.assign(new Error(`Session not found: ${sessionId}`), { code: 'SESSION_NOT_FOUND', status: 404 });
         }
         if (session.meta.status === 'closed') {
-            throw Object.assign(new Error(`Session is closed: ${sessionId}`), { code: 'SESSION_CLOSED', status: 409 });
+            throw Object.assign(new Error('Session is closed'), { code: SDKErrorCodes.SESSION_CLOSED, status: 409 });
         }
         const patch = { updatedAt: Date.now() };
         if (input.title !== undefined)
@@ -239,6 +245,9 @@ export class CompanionChatManager {
             patch.systemPrompt = input.systemPrompt;
         const updated = this._updateMeta(session, patch);
         this._persist(sessionId);
+        // Heartbeat the broker record (advances participant.lastSeenAt). Title is
+        // never overwritten by this path (broker treats register as a heartbeat).
+        this._brokerSync.track(updated.id, () => this._brokerSync.registerSession(updated));
         return updated;
     }
     /**
@@ -267,8 +276,37 @@ export class CompanionChatManager {
         const now = Date.now();
         const updated = this._updateMeta(session, { status: 'closed', closedAt: now, updatedAt: now });
         this._persist(sessionId);
+        // Live spine: flip the shared broker record to closed at write time.
+        this._brokerSync.track(sessionId, () => this._brokerSync.closeSession(sessionId));
         return updated;
     }
+    /**
+     * Permanently delete a session (see CHANGELOG 1.0.0: `delete` is now a genuine removal,
+     * distinct from `closeSession` above). Aborts any in-flight turn, removes
+     * the on-disk record file, and drops the in-memory entry — reusing
+     * {@link _hardRemove}, the SAME primitive the GC 'delete-persistent' sweep
+     * action uses, so there is exactly one removal code path.
+     *
+     * Requires the session to already be closed: deleting a still-active
+     * session throws `{ code: 'SESSION_ACTIVE', status: 409 }` (the caller must
+     * close it first, mirroring the SESSION_CLOSED-throw convention elsewhere
+     * in this file). An unknown OR already-deleted id throws
+     * `{ code: 'SESSION_NOT_FOUND', status: 404 }` — delete is not a 200-noop.
+     */
+    async deleteSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw Object.assign(new Error(`Session not found: ${sessionId}`), { code: 'SESSION_NOT_FOUND', status: 404 });
+        }
+        if (session.meta.status !== 'closed') {
+            throw Object.assign(new Error('Session is active — close it, then delete.'), { code: 'SESSION_ACTIVE', status: 409 });
+        }
+        session.abortController.abort();
+        await this._hardRemove(sessionId);
+        // Live spine: drop the mirrored shared broker record entirely (not just closed).
+        this._brokerSync.track(sessionId, () => this._brokerSync.deleteSession(sessionId));
+        return { sessionId, deleted: true };
+    }
     /**
      * Post a user message and start an async LLM turn. Returns the messageId.
      *
@@ -318,11 +356,11 @@ export class CompanionChatManager {
             throw Object.assign(new Error(`Session not found: ${sessionId}`), { code: 'SESSION_NOT_FOUND', status: 404 });
         }
         if (session.meta.status === 'closed') {
-            throw Object.assign(new Error(`Session is closed: ${sessionId}`), { code: 'SESSION_CLOSED', status: 409 });
+            throw Object.assign(new Error('Session is closed'), { code: SDKErrorCodes.SESSION_CLOSED, status: 409 });
         }
         // Rate-limit check (throws GoodVibesSdkError on violation)
         this.rateLimiter?.check(sessionId, clientId);
-        const attachments = this.resolveAttachments(options.attachments ?? []);
+        const attachments = resolveAttachments(options.attachments ?? [], this.artifactStore);
         if (!content.trim() && attachments.length === 0) {
             throw Object.assign(new Error('content or attachments are required'), { code: 'INVALID_INPUT', status: 400 });
         }
@@ -338,7 +376,7 @@ export class CompanionChatManager {
             createdAt: now,
         };
         session.messages.push(userMsg);
-        session.conversation.addUserMessage(await this.buildProviderUserContent(content, attachments));
+        session.conversation.addUserMessage(await buildProviderUserContent(content, attachments, this.artifactStore));
         session.lastActivityAt = now;
         this._updateMeta(session, {
             messageCount: session.messages.length,
@@ -357,106 +395,6 @@ export class CompanionChatManager {
         });
         return messageId;
     }
-    resolveAttachments(inputs) {
-        if (inputs.length === 0)
-            return [];
-        if (inputs.length > MAX_ATTACHMENTS_PER_MESSAGE) {
-            throw Object.assign(new Error(`A companion chat message can include at most ${MAX_ATTACHMENTS_PER_MESSAGE} attachments.`), { code: 'TOO_MANY_ATTACHMENTS', status: 400 });
-        }
-        if (!this.artifactStore) {
-            throw Object.assign(new Error('Companion chat attachments require an artifact store.'), { code: 'ATTACHMENTS_UNAVAILABLE', status: 501 });
-        }
-        return inputs.map((input) => {
-            const artifactId = input.artifactId.trim();
-            if (!artifactId) {
-                throw Object.assign(new Error('Attachment artifactId is required.'), {
-                    code: 'INVALID_ATTACHMENT',
-                    status: 400,
-                });
-            }
-            const artifact = this.artifactStore.get(artifactId);
-            if (!artifact) {
-                throw Object.assign(new Error(`Unknown attachment artifact: ${artifactId}`), {
-                    code: 'UNKNOWN_ARTIFACT',
-                    status: 404,
-                });
-            }
-            return {
-                ...artifact,
-                artifactId: artifact.id,
-                ...(input.label?.trim() ? { label: input.label.trim() } : {}),
-                metadata: {
-                    ...artifact.metadata,
-                    ...(input.metadata ?? {}),
-                },
-            };
-        });
-    }
-    formatAttachmentSummary(attachments) {
-        if (attachments.length === 0)
-            return '';
-        const lines = attachments.map((attachment, index) => {
-            const name = attachment.label ?? attachment.filename ?? attachment.artifactId;
-            return `${index + 1}. ${name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes, artifact ${attachment.artifactId})`;
-        });
-        return `\n\nAttached file${attachments.length === 1 ? '' : 's'}:\n${lines.join('\n')}`;
-    }
-    buildReplayUserContent(message) {
-        return `${message.content}${this.formatAttachmentSummary(message.attachments ?? [])}`;
-    }
-    isInlineTextAttachment(attachment) {
-        const lower = attachment.mimeType.toLowerCase();
-        return attachment.sizeBytes <= MAX_INLINE_TEXT_ATTACHMENT_BYTES
-            && (lower.startsWith('text/')
-                || lower === 'application/json'
-                || lower === 'application/xml'
-                || lower === 'application/yaml'
-                || lower === 'text/csv');
-    }
-    isInlineImageAttachment(attachment) {
-        const lower = attachment.mimeType.toLowerCase();
-        return attachment.sizeBytes <= MAX_INLINE_IMAGE_ATTACHMENT_BYTES
-            && (lower === 'image/png'
-                || lower === 'image/jpeg'
-                || lower === 'image/gif'
-                || lower === 'image/webp');
-    }
-    async buildProviderUserContent(content, attachments) {
-        if (attachments.length === 0)
-            return content;
-        const textSections = [content.trim() ? content : 'Please review the attached file(s).'];
-        const imageParts = [];
-        for (const attachment of attachments) {
-            if (!this.artifactStore)
-                continue;
-            try {
-                if (this.isInlineTextAttachment(attachment)) {
-                    const { buffer } = await this.artifactStore.readContent(attachment.artifactId);
-                    const text = toNodeBuffer(buffer).toString('utf-8');
-                    textSections.push(`\n\n--- Attachment: ${attachment.label ?? attachment.filename ?? attachment.artifactId} ---\n${text}`);
-                    continue;
-                }
-                if (this.isInlineImageAttachment(attachment)) {
-                    const { buffer } = await this.artifactStore.readContent(attachment.artifactId);
-                    imageParts.push({
-                        type: 'image',
-                        mediaType: attachment.mimeType,
-                        data: toNodeBuffer(buffer).toString('base64'),
-                    });
-                }
-            }
-            catch (error) {
-                logger.warn('[companion-chat] failed to inline attachment for provider prompt', {
-                    artifactId: attachment.artifactId,
-                    error: summarizeError(error),
-                });
-            }
-        }
-        textSections.push(this.formatAttachmentSummary(attachments));
-        if (imageParts.length === 0)
-            return textSections.join('');
-        return [{ type: 'text', text: textSections.join('') }, ...imageParts];
-    }
     dispose() {
         if (this.gcTimer) {
             clearInterval(this.gcTimer);
@@ -563,11 +501,11 @@ export class CompanionChatManager {
                     completed = true;
                     break;
                 }
-                const toolResults = await this._executeToolCalls(toolCalls, publish, sessionId, turnId);
+                const toolResults = await executeCompanionToolCalls({ toolRegistry: this.toolRegistry, permissionManager: this.permissionManager, hookDispatcher: this.hookDispatcher, runtimeBus: this.runtimeBus }, toolCalls, publish, sessionId, turnId);
                 session.conversation.addToolResults(toolResults);
             }
             if (!completed && !abortSignal.aborted) {
-                const finalResponse = await this._finalizeAfterToolExhaustion(session, abortSignal, turnId, publish);
+                const finalResponse = await runToolExhaustionFinalizer({ provider: this.provider, finalizerPrompt: TOOL_EXHAUSTION_FINALIZER_PROMPT }, session, abortSignal, turnId, publish);
                 if (finalResponse.trim()) {
                     assistantContent += finalResponse;
                     session.conversation.addAssistantMessage(finalResponse);
@@ -623,113 +561,120 @@ export class CompanionChatManager {
             }
         }
     }
-    async _finalizeAfterToolExhaustion(session, abortSignal, turnId, publish) {
-        const sessionId = session.meta.id;
-        let finalContent = '';
-        const stream = this.provider.chatStream([...session.conversation.getMessagesForLLM()], {
-            systemPrompt: appendGoodVibesRuntimeAwarenessPrompt([session.meta.systemPrompt, TOOL_EXHAUSTION_FINALIZER_PROMPT].filter(Boolean).join('\n\n')),
-            model: session.meta.model,
-            provider: session.meta.provider,
-            abortSignal,
-        });
-        for await (const chunk of stream) {
-            if (abortSignal.aborted)
-                break;
-            switch (chunk.type) {
-                case 'text_delta': {
-                    const delta = chunk.delta ?? '';
-                    finalContent += delta;
-                    publish({ type: 'turn.delta', sessionId, turnId, delta });
-                    break;
-                }
-                case 'error':
-                    throw new Error(chunk.error ?? 'Provider streaming error');
-                case 'tool_call':
-                case 'tool_result':
-                case 'done':
-                    break;
-            }
-        }
-        return finalContent;
+    // ---------------------------------------------------------------------------
+    // Regenerate + edit-and-branch (honest lineage — see companion-chat-branching.ts)
+    // ---------------------------------------------------------------------------
+    /**
+     * Regenerate an assistant response: supersede the target assistant message (an
+     * explicit id, or the latest response) and everything after it — retained as
+     * history, never deleted — then re-run a fresh turn from the preceding user
+     * message. Refuses a closed (409 SESSION_CLOSED) or unknown (404
+     * SESSION_NOT_FOUND) session; honest code when there is nothing to regenerate.
+     */
+    regenerateMessage(sessionId, input = {}) {
+        const session = this._requireOpenSession(sessionId);
+        this.rateLimiter?.check(sessionId, '');
+        const now = Date.now();
+        const plan = planRegenerate(session, input.messageId, now);
+        this._commitBranchAndRun(session, sessionId, plan.anchorUserMessageId, now);
+        const { regeneratedFrom, supersededMessageIds } = plan;
+        return { sessionId, regeneratedFrom, supersededMessageIds, turnStarted: true };
     }
-    async _executeToolCalls(toolCalls, publish, sessionId, turnId) {
-        const toolRegistry = this.toolRegistry;
-        if (!toolRegistry)
-            return [];
-        if (!this.permissionManager) {
-            return toolCalls.map((call) => {
-                const toolResult = {
-                    callId: call.id,
-                    success: false,
-                    error: 'Tool execution denied: permission manager unavailable for companion chat',
-                };
-                publish({
-                    type: 'turn.tool_result',
-                    sessionId,
-                    turnId,
-                    toolCallId: call.id,
-                    toolName: call.name,
-                    result: toolResult.error,
-                    isError: true,
-                });
-                return toolResult;
-            });
+    /**
+     * Edit a user message and branch from it: supersede the target user message and
+     * everything after it (retained history), append a new user message carrying
+     * `revisionOf` back to the original, and run a fresh turn. Same closed/unknown
+     * refusals as {@link regenerateMessage}.
+     */
+    editMessage(sessionId, input) {
+        const session = this._requireOpenSession(sessionId);
+        this.rateLimiter?.check(sessionId, '');
+        const now = Date.now();
+        const plan = applyEditBranch(session, sessionId, input, this.artifactStore, now);
+        this._commitBranchAndRun(session, sessionId, plan.newMessageId, now);
+        const { editedFrom, newMessageId, supersededMessageIds } = plan;
+        return { sessionId, editedFrom, messageId: newMessageId, supersededMessageIds, turnStarted: true };
+    }
+    /** Look up an active (open) session or throw the closed/not-found machine codes. */
+    _requireOpenSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw Object.assign(new Error(`Session not found: ${sessionId}`), { code: 'SESSION_NOT_FOUND', status: 404 });
         }
-        const results = await executeOrchestratorToolCalls({
-            toolRegistry,
-            permissionManager: this.permissionManager,
-            hookDispatcher: this.hookDispatcher,
-            runtimeBus: this.runtimeBus,
-            sessionId,
-            emitterContext: (id) => ({
-                sessionId,
-                traceId: `${sessionId}:${id}`,
-                source: 'companion-chat',
-            }),
-        }, turnId, toolCalls);
-        for (const [index, toolResult] of results.entries()) {
-            const call = toolCalls[index];
-            if (!call)
-                continue;
-            publish({
-                type: 'turn.tool_result',
-                sessionId,
-                turnId,
-                toolCallId: call.id,
-                toolName: call.name,
-                result: toolResult.output ?? toolResult.error ?? null,
-                isError: !toolResult.success,
-            });
+        if (session.meta.status === 'closed') {
+            throw Object.assign(new Error('Session is closed'), { code: SDKErrorCodes.SESSION_CLOSED, status: 409 });
         }
-        return results;
+        return session;
+    }
+    /**
+     * Shared tail of regenerate/edit: rebuild the LLM-facing conversation from the
+     * ACTIVE (non-superseded) chain (mirroring init()'s replay so the next turn
+     * sees only the live branch), persist, and fire the new turn.
+     */
+    _commitBranchAndRun(session, sessionId, anchorUserMessageId, now) {
+        const conversation = new ConversationManager();
+        for (const msg of activeMessages(session.messages)) {
+            if (msg.role === 'user')
+                conversation.addUserMessage(buildReplayUserContent(msg));
+            else
+                conversation.addAssistantMessage(msg.content);
+        }
+        session.conversation = conversation;
+        this._updateMeta(session, { messageCount: session.messages.length, updatedAt: now });
+        this._persist(sessionId);
+        void this._runTurn(session, anchorUserMessageId).catch((error) => {
+            logger.warn('[companion-chat] branch turn execution failed', { sessionId, error: summarizeError(error) });
+        });
     }
     // ---------------------------------------------------------------------------
     // GC sweep
     // ---------------------------------------------------------------------------
+    /**
+     * Periodic GC sweep. Deletion authority is SPLIT (charter: closed sessions are
+     * HISTORY): close-idle closes an idle active session; evict-memory drops a
+     * long-closed session's in-memory handles (meta + on-disk copy kept);
+     * delete-persistent removes the file ONLY under an explicit finite retention
+     * window (default retains indefinitely — see {@link planCompanionSweep}).
+     */
     _gcSweep() {
         const now = Date.now();
         for (const [id, session] of this.sessions) {
-            if (session.meta.status === 'closed') {
-                // Remove already-closed sessions after a short grace period (5 min)
-                if (now - (session.meta.closedAt ?? now) > 5 * 60_000) {
-                    void this.persistence?.delete(id).catch((error) => {
+            const action = planCompanionSweep({
+                status: session.meta.status,
+                closedAt: session.meta.closedAt,
+                lastActivityAt: session.lastActivityAt,
+                hasMessagesInMemory: !session.messagesEvicted && session.messages.length > 0,
+                isEmpty: session.messages.length === 0,
+            }, {
+                now,
+                idleActiveMs: this.idleActiveMs,
+                idleEmptyMs: this.idleEmptyMs,
+                closedMemoryGraceMs: this.closedMemoryGraceMs,
+                closedRetentionMs: this.closedRetentionMs,
+            });
+            switch (action.kind) {
+                case 'close-idle':
+                    session.abortController.abort();
+                    this._updateMeta(session, { status: 'closed', closedAt: now, updatedAt: now });
+                    this._persist(id);
+                    this._brokerSync.track(id, () => this._brokerSync.closeSession(id));
+                    break;
+                case 'evict-memory':
+                    // Free heavy handles; keep meta (listable) and the persisted file.
+                    session.messages = [];
+                    session.conversation = new ConversationManager();
+                    session.messagesEvicted = true;
+                    break;
+                case 'delete-persistent':
+                    void this._hardRemove(id).catch((error) => {
                         logger.warn('[companion-chat] session delete failed', {
                             sessionId: id,
                             error: summarizeError(error),
                         });
                     });
-                    this.sessions.delete(id);
-                }
-                continue;
-            }
-            const idleMs = now - session.lastActivityAt;
-            const isEmpty = session.messages.length === 0;
-            const ttl = isEmpty ? this.idleEmptyMs : this.idleActiveMs;
-            if (idleMs >= ttl) {
-                // Close via GC
-                session.abortController.abort();
-                this._updateMeta(session, { status: 'closed', closedAt: now, updatedAt: now });
-                this._persist(id);
+                    break;
+                case 'retain':
+                    break;
             }
         }
     }
@@ -738,6 +683,33 @@ export class CompanionChatManager {
         session.meta = updated;
         return updated;
     }
+    // ---------------------------------------------------------------------------
+    // Live shared-broker registration (S1 item D) — see companion-chat-broker-sync.ts
+    // ---------------------------------------------------------------------------
+    /**
+     * Await all in-flight best-effort broker-sync operations. The daemon's
+     * companion HTTP routes call this before responding so `/api/sessions`
+     * reflects the change synchronously; tests use it to make the mirror
+     * deterministic. A no-op when no broker bridge is configured.
+     */
+    async flushBrokerSync() {
+        await this._brokerSync.flush();
+    }
+    /**
+     * Hard-remove a session's persisted file and in-memory record. The ONE
+     * removal code path — shared by {@link deleteSession} and the GC
+     * 'delete-persistent' action. Never fork this. Order matters:
+     * drop the map entry, drain any in-flight {@link _persist} save for this
+     * id, THEN unlink — else a save mid-write from {@link closeSession} can
+     * resurrect the file post-unlink.
+     */
+    async _hardRemove(sessionId) {
+        this.sessions.delete(sessionId);
+        const pendingSave = this._pendingSaves.get(sessionId);
+        if (pendingSave)
+            await pendingSave.catch(() => { });
+        await this.persistence?.delete(sessionId);
+    }
     /**
      * Schedule a persistence save for the given session.
      * Saves are serialized per-session: each new save waits for the prior one to

package/dist/platform/companion/companion-chat-persistence.d.ts

@@ -16,7 +16,15 @@ export interface PersistedChatSession {
     readonly meta: CompanionChatSession;
     readonly messages: CompanionChatMessage[];
 }
-export declare function defaultSessionsDir(): string;
+/**
+ * Resolve the companion-chat sessions directory.
+ *
+ * Pass the runtime's INJECTED home directory so an isolated-home daemon never
+ * reads or writes the real `~/.goodvibes/companion-chat` — the rest of the
+ * runtime resolves paths from the injected home, and this must agree. The
+ * OS `homedir()` is used only as a last resort when nothing is injected.
+ */
+export declare function defaultSessionsDir(homeDirectory?: string): string;
 export declare class CompanionChatPersistence {
     private readonly sessionsDir;
     constructor(sessionsDir?: string);

package/dist/platform/companion/companion-chat-persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"companion-chat-persistence.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAQ5F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAC3C;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAMD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,WAAW,CAAC,EAAE,MAAM;IAIhC,4CAA4C;IAC5C,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAIhB,0FAA0F;IACpF,OAAO,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAoChD,iFAAiF;IAC3E,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BxD,yGAAyG;IACnG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAU/C"}
+{"version":3,"file":"companion-chat-persistence.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAQ5F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAC3C;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAMD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,WAAW,CAAC,EAAE,MAAM;IAIhC,4CAA4C;IAC5C,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAIhB,0FAA0F;IACpF,OAAO,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAoChD,iFAAiF;IAC3E,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BxD,yGAAyG;IACnG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAU/C"}

package/dist/platform/companion/companion-chat-persistence.js

@@ -20,8 +20,16 @@ import { summarizeError } from '../utils/error-display.js';
 // ---------------------------------------------------------------------------
 // Default path
 // ---------------------------------------------------------------------------
-export function defaultSessionsDir() {
-    return join(homedir(), '.goodvibes', 'companion-chat', 'sessions');
+/**
+ * Resolve the companion-chat sessions directory.
+ *
+ * Pass the runtime's INJECTED home directory so an isolated-home daemon never
+ * reads or writes the real `~/.goodvibes/companion-chat` — the rest of the
+ * runtime resolves paths from the injected home, and this must agree. The
+ * OS `homedir()` is used only as a last resort when nothing is injected.
+ */
+export function defaultSessionsDir(homeDirectory) {
+    return join(homeDirectory ?? homedir(), '.goodvibes', 'companion-chat', 'sessions');
 }
 // ---------------------------------------------------------------------------
 // CompanionChatPersistence

package/dist/platform/companion/companion-chat-routes.d.ts

@@ -7,7 +7,8 @@
  *   POST   /api/companion/chat/sessions
  *   GET    /api/companion/chat/sessions/:sessionId
  *   PATCH  /api/companion/chat/sessions/:sessionId
- *   DELETE /api/companion/chat/sessions/:sessionId
+ *   POST   /api/companion/chat/sessions/:sessionId/close   (soft close — history preserved)
+ *   DELETE /api/companion/chat/sessions/:sessionId         (hard delete — record permanently removed)
  *   POST   /api/companion/chat/sessions/:sessionId/messages
  *   GET    /api/companion/chat/sessions/:sessionId/messages
  *   GET    /api/companion/chat/sessions/:sessionId/events  (SSE)

package/dist/platform/companion/companion-chat-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"companion-chat-routes.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAMjF;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAoD1B;AA8MD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAMlF"}
+{"version":3,"file":"companion-chat-routes.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAMjF;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAmE1B;AAgPD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAMlF"}