newmark-agent 0.5.14 → 0.6.0

package/dist/core/subagentCommunication.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubagentCommunicationSelectionError = void 0;
+exports.selectSubagentCommunication = selectSubagentCommunication;
+class SubagentCommunicationSelectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SubagentCommunicationSelectionError';
+    }
+}
+exports.SubagentCommunicationSelectionError = SubagentCommunicationSelectionError;
+const MAX_BODY_CHARS = 30000;
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function fail(code, message) { throw new SubagentCommunicationSelectionError(code, message); }
+function messageText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return '';
+    return value.filter(part => record(part) && ['text', 'input_text', 'output_text'].includes(String(part.type)))
+        .map(part => typeof part.text === 'string' ? part.text : '').join('\n');
+}
+function toolPayload(value) {
+    // Only the selected message.content / function.arguments enter this path.
+    // Business fields and code snippets inside a tool payload are evidence, not
+    // message-level private metadata, and must never be rewritten or filtered.
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined)
+        return '';
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return fail('invalid_content', 'Selected tool payload is not serializable; provide an explicit summary instead.');
+    }
+}
+function units(history) {
+    const texts = [], tools = [];
+    const pending = new Map();
+    const ambiguous = new Set();
+    history.forEach((message, sourceIndex) => {
+        if (!message || message.hidden_user_input === true)
+            return;
+        if (message.role === 'user' || message.role === 'assistant') {
+            const text = messageText(message.content);
+            if (text.trim())
+                texts.push({ role: message.role, text, sourceIndex });
+        }
+        if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
+            for (const [callIndex, call] of message.tool_calls.entries()) {
+                if (!record(call) || !record(call.function))
+                    continue;
+                const id = typeof call.id === 'string' ? call.id : '';
+                const name = typeof call.function.name === 'string' ? call.function.name : '';
+                if (!id.trim() || !name.trim())
+                    continue;
+                if (pending.has(id) || ambiguous.has(id)) {
+                    pending.delete(id);
+                    ambiguous.add(id);
+                    continue;
+                }
+                pending.set(id, { id, name, arguments: call.function.arguments, sourceIndex, callIndex });
+            }
+        }
+        else if (message.role === 'tool' && typeof message.tool_call_id === 'string') {
+            const call = pending.get(message.tool_call_id);
+            if (!call || (typeof message.name === 'string' && message.name.trim() && message.name !== call.name))
+                return;
+            tools.push({ ...call, result: message.content });
+            pending.delete(message.tool_call_id);
+        }
+    });
+    tools.sort((a, b) => a.sourceIndex - b.sourceIndex || a.callIndex - b.callIndex);
+    const timeline = [...texts, ...tools];
+    timeline.sort((a, b) => a.sourceIndex - b.sourceIndex || ('text' in a ? -1 : 'text' in b ? 1 : a.callIndex - b.callIndex));
+    return { texts, tools, timeline };
+}
+function resolveRange(value, total, kind) {
+    if (!record(value))
+        return fail('invalid_range', `${kind} requires range: {last:N} or {start:N,end:N}.`);
+    const hasLast = own(value, 'last'), hasStart = own(value, 'start'), hasEnd = own(value, 'end');
+    if (Object.keys(value).some(key => !['last', 'start', 'end'].includes(key)) || (hasLast && (hasStart || hasEnd)) || (!hasLast && (!hasStart || !hasEnd))) {
+        return fail('invalid_range', `${kind} range must use last alone or both start/end; ranges are 1-based and inclusive.`);
+    }
+    const integer = (n) => typeof n === 'number' && Number.isSafeInteger(n) && n >= 1;
+    if (hasLast) {
+        if (!integer(value.last) || value.last > total)
+            return fail('invalid_range', `${kind} range.last must be between 1 and ${total}; no selected units are silently omitted.`);
+        return { start: total - value.last + 1, end: total, total };
+    }
+    if (!integer(value.start) || !integer(value.end) || value.start > value.end || value.end > total) {
+        return fail('invalid_range', `${kind} range must satisfy 1 <= start <= end <= ${total}.`);
+    }
+    return { start: value.start, end: value.end, total };
+}
+function rangeLabel(range) { return `${range.start}-${range.end} of ${range.total}`; }
+function textSection(selected, range) {
+    return `[Selected text history: ${rangeLabel(range)}]\n${selected.map((unit, index) => `${range.start + index}. ${unit.role}:\n${unit.text}`).join('\n\n')}`;
+}
+function toolSection(selected, range) {
+    return `[Selected tool history: ${rangeLabel(range)}; complete call/result pairs]\n${selected.map((unit, index) => `${range.start + index}. ${JSON.stringify(unit.name)} call_id=${JSON.stringify(unit.id)}\nCall arguments:\n${toolPayload(unit.arguments) || '(empty)'}\nTool result:\n${toolPayload(unit.result) || '(empty public result)'}`).join('\n\n')}`;
+}
+function selectSubagentCommunication(history, params, options = {}) {
+    const limit = options.maxBodyChars ?? MAX_BODY_CHARS;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_BODY_CHARS)
+        return fail('invalid_content', 'maxBodyChars must be an integer between 1 and 30000.');
+    if (!record(params))
+        return fail('invalid_content', 'Communication parameters must be an object.');
+    const hasMessage = own(params, 'message'), hasPrompt = own(params, 'prompt'), hasContent = own(params, 'content');
+    if ((hasMessage || hasPrompt) && hasContent)
+        return fail('ambiguous_content', 'Use explicit message/prompt or content selections, not both.');
+    if (hasMessage && hasPrompt && params.message !== params.prompt)
+        return fail('ambiguous_content', 'message and prompt contain conflicting explicit text.');
+    const segments = [];
+    let body = '';
+    const append = (section) => {
+        const next = body ? `${body}\n\n${section}` : section;
+        if (next.length > limit)
+            fail('budget_exceeded', `Selected communication exceeds the ${limit}-character budget. Select a smaller range or provide a shorter summary; no selected text or tool pair was truncated.`);
+        body = next;
+    };
+    if (hasMessage || hasPrompt) {
+        const explicit = hasMessage ? params.message : params.prompt;
+        if (typeof explicit !== 'string' || !explicit.trim())
+            return fail('invalid_content', 'Explicit message/prompt must be non-empty text.');
+        append(explicit);
+        segments.push({ kind: 'message', units: 1 });
+        return { body, selection: { source: 'explicit', segments, bodyChars: body.length } };
+    }
+    const available = units(history);
+    if (!hasContent) {
+        if (!available.texts.length)
+            return fail('empty_history', 'No visible text history is available. Supply an explicit message or a scoped content selection.');
+        const range = resolveRange({ last: 1 }, available.texts.length, 'text_history');
+        append(textSection(available.texts.slice(-1), range));
+        segments.push({ kind: 'text_history', range, units: 1 });
+        return { body, selection: { source: 'default_history', segments, bodyChars: body.length } };
+    }
+    if (!Array.isArray(params.content) || !params.content.length)
+        return fail('invalid_content', 'content must contain at least one scoped selection.');
+    for (const part of params.content) {
+        if (!record(part) || !['summary', 'text_history', 'tool_history'].includes(String(part.kind)))
+            return fail('invalid_content', 'content kind must be summary, text_history, or tool_history.');
+        const kind = part.kind;
+        const total = kind === 'text_history' ? available.texts.length : kind === 'tool_history' ? available.tools.length : available.timeline.length;
+        const range = resolveRange(part.range, total, kind);
+        if (kind === 'summary') {
+            if (typeof part.text !== 'string' || !part.text.trim())
+                return fail('invalid_content', 'summary requires non-empty sender-provided text; the tool does not generate a summary.');
+            append(`[Sender-provided summary; visible history units ${rangeLabel(range)}]\n${part.text}`);
+        }
+        else {
+            if (own(part, 'text'))
+                return fail('invalid_content', `${kind} selects source history; use summary for sender-provided text.`);
+            append(kind === 'text_history'
+                ? textSection(available.texts.slice(range.start - 1, range.end), range)
+                : toolSection(available.tools.slice(range.start - 1, range.end), range));
+        }
+        segments.push({ kind, range, units: range.end - range.start + 1 });
+    }
+    return { body, selection: { source: 'content', segments, bodyChars: body.length } };
+}
+//# sourceMappingURL=subagentCommunication.js.map

package/dist/core/types.d.ts

@@ -38,7 +38,16 @@ export interface GuideReceipt {
     /** Durable user-authored media referenced while the Guide is pending. */
     attachments?: ConversationImageAttachment[];
 }
+/** Presence is separate from value: a reported zero is not missing usage. */
+export interface ProviderUsageReported {
+    input: boolean;
+    output: boolean;
+    cacheRead: boolean;
+    cacheWrite: boolean;
+}
 export interface StreamToken {
+    /** Transport-originated failure, distinct from model-generated prose. */
+    providerError?: boolean;
     type: 'text' | 'tool_call' | 'status' | 'usage';
     text: string;
     toolCall?: {
@@ -52,6 +61,7 @@ export interface StreamToken {
         output: number;
         cacheRead: number;
         cacheWrite: number;
+        reported?: ProviderUsageReported;
     };
 }
 export interface ConversationImageAttachment {
@@ -100,7 +110,7 @@ export interface ChatMessage {
 export interface AgentWorkEvent {
     id: string;
     conversationId: string;
-    type: 'start' | 'text' | 'response' | 'final_response' | 'tool_call' | 'tool_result' | 'thought' | 'thought_delta' | 'thought_result' | 'status' | 'done' | 'error' | 'queue_update' | 'guide' | 'conversation_title';
+    type: 'start' | 'text' | 'response' | 'final_response' | 'tool_call' | 'tool_result' | 'thought' | 'thought_delta' | 'thought_result' | 'status' | 'done' | 'error' | 'queue_update' | 'guide' | 'conversation_title' | 'conversation_list';
     content: string;
     mode: string;
     model: string;
@@ -121,8 +131,24 @@ export interface AgentWorkEvent {
         goalObjective?: string;
         runId?: string;
         createdAt: string;
+        images?: Array<{
+            dataUrl: string;
+            name?: string;
+            type?: string;
+        }>;
     }>;
     queuePaused?: boolean;
+    /** Authoritative metadata events bypass turn identity without changing selection. */
+    stateScope?: 'conversation' | 'workspace';
+    conversations?: Array<{
+        id: string;
+        title: string;
+        messageCount: number;
+        historyCount: number;
+        updatedAt: string;
+        pinned?: boolean;
+        order?: number;
+    }>;
     workspaceId?: string;
     workspaceKey?: string;
     runtimeKey?: string;
@@ -132,6 +158,13 @@ export interface AgentWorkEvent {
     actorId?: string;
     generation?: number;
     sequence?: number;
+    /** Original delta identities retained across IPC batching for snapshot reconciliation. */
+    coalescedDeltas?: Array<{
+        id: string;
+        sequence?: number;
+        content: string;
+        timestamp: string;
+    }>;
     status?: GuideReceiptStatus | ConversationWorkRunStatus | 'stopping' | 'force_restarting';
     guide?: GuideReceipt;
     displayImage?: DisplayImageAttachment;

package/dist/core/utilityAgentProtocol.d.ts

@@ -78,6 +78,10 @@ export type UtilityAgentRequest = {
     method: 'snapshot';
     params: {
         target: ConversationRuntimeTarget;
+        options?: {
+            window?: number;
+            before?: number;
+        };
     };
 } | {
     id: string;

package/dist/core/workEventCoalescer.js

@@ -21,14 +21,17 @@ class WorkEventCoalescer {
         }
         const key = `${event.type}::${event.workspaceId || ''}::${event.conversationId}::${event.runtimeKey || ''}::${event.runId || ''}`;
         const current = this.pending.get(key);
+        const deltas = event.coalescedDeltas?.length ? event.coalescedDeltas : [{ id: event.id, sequence: event.sequence, content: event.content, timestamp: event.timestamp }];
         if (current) {
             current.content += event.content;
+            current.deltas.push(...deltas);
             current.event = event;
             return;
         }
         const entry = {
             event,
             content: event.content,
+            deltas: deltas.slice(),
             timer: setTimeout(() => this.flush(key), this.windowMs),
         };
         this.pending.set(key, entry);
@@ -40,7 +43,7 @@ class WorkEventCoalescer {
         this.pending.delete(key);
         clearTimeout(entry.timer);
         if (entry.content)
-            this.emit({ ...entry.event, content: entry.content });
+            this.emit({ ...entry.event, content: entry.content, coalescedDeltas: entry.deltas });
     }
     flushAll() {
         for (const key of [...this.pending.keys()])

package/dist/core/wslAgentClient.d.ts

@@ -19,12 +19,13 @@ export interface WslRuntimeIdentity {
     pid: number;
     pgid: number;
     sessionId: number;
+    startTimeTicks: string;
+    bootId: string;
 }
 /**
- * Kills one previously verified WSL session/process group and proves that the
- * group no longer exists before its caller may launch a replacement. The bash
- * helper has its own bounded poll loop; the Windows child runner adds a second
- * timeout/cancellation boundary so Electron's event loop is never blocked.
+ * Terminates the verified runtime and its descendants, including detached
+ * tools, through identity-bound Linux pidfds. The historical export name is
+ * retained for callers; no numeric process-group signal is issued.
  */
 export declare function terminateWslRuntimeProcessGroup(distro: string, identityInput: WslRuntimeIdentity, runner?: WslCommandRunner, signal?: AbortSignal): Promise<void>;
 export declare class WslAgentClient {
@@ -46,6 +47,10 @@ export declare class WslAgentClient {
     private remotePid;
     private remotePgid;
     private remoteSessionId;
+    private remoteStartTimeTicks;
+    private remoteBootId;
+    private restartQuarantined;
+    private unconfirmedExit;
     private startPromise;
     constructor(distro: string, windowsRoot: string, windowsHostScript: string, runtimeTarget?: NormalizedConversationTarget | null, commandRunner?: WslCommandRunner);
     subscribe(listener: WorkListener): () => void;
@@ -58,6 +63,9 @@ export declare class WslAgentClient {
         pid: number;
         pgid: number;
         sessionId: number;
+        startTimeTicks: string;
+        bootId: string;
+        quarantined: boolean;
         error: string;
     };
     start(): Promise<void>;
@@ -69,7 +77,10 @@ export declare class WslAgentClient {
     abort(conversationId: string): Promise<boolean>;
     requestStop(target: ConversationRuntimeTarget, runId?: string): Promise<WslAgentStopResult>;
     snapshot(conversationId: string, workspace: WslAgentWorkspace | null): Promise<Record<string, unknown>>;
-    snapshotTarget(target: ConversationRuntimeTarget): Promise<Record<string, unknown>>;
+    snapshotTarget(target: ConversationRuntimeTarget, options?: {
+        window?: number;
+        before?: number;
+    }): Promise<Record<string, unknown>>;
     rewind(target: ConversationRuntimeTarget, messageIndex: number): Promise<WslConversationRewindResult>;
     enqueueGuide(target: ConversationRuntimeTarget, envelope: ConversationInputEnvelope): Promise<GuideReceipt>;
     queueAction(target: ConversationRuntimeTarget, action: ConversationQueueAction, input?: ConversationQueueActionInput): Promise<Record<string, unknown>>;
@@ -88,6 +99,8 @@ export declare class WslAgentClient {
     updateSetting(section: string, key: string, value: unknown): Promise<void>;
     forceStopRuntimeGroup(signal?: AbortSignal): Promise<'terminated' | 'stale'>;
     forceRestartRuntimeGroup(signal?: AbortSignal): Promise<void>;
+    private throwIfRestartQuarantined;
+    private confirmTerminatedGeneration;
     terminalState(owner: TerminalTakeoverOwnerFilter, persistenceRoot?: string): Promise<TerminalTakeoverState[]>;
     terminalWrite(owner: TerminalTakeoverOwnerFilter, sessionId: string, data: string, persistenceRoot?: string): Promise<{
         ok: boolean;

package/dist/core/wslAgentClient.js

@@ -43,6 +43,7 @@ const asyncProcess_1 = require("./asyncProcess");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const performanceDiagnostics_1 = require("./performanceDiagnostics");
+const wslRuntimeProcessTree_1 = require("./wslRuntimeProcessTree");
 const defaultWslCommandRunner = async (args, options) => await new Promise(resolve => {
     let settled = false;
     const finish = (result) => {
@@ -50,10 +51,9 @@ const defaultWslCommandRunner = async (args, options) => await new Promise(resol
             return;
         settled = true;
         clearTimeout(hardTimeout);
-        options.signal?.removeEventListener('abort', abortListener);
         resolve(result);
     };
-    const abortListener = () => finish({
+    const aborted = () => ({
         status: null,
         stdout: '',
         stderr: '',
@@ -71,41 +71,44 @@ const defaultWslCommandRunner = async (args, options) => await new Promise(resol
         timedOut: true,
         overflowed: false,
     }), options.timeoutMs + 200);
-    options.signal?.addEventListener('abort', abortListener, { once: true });
+    if (options.signal?.aborted) {
+        finish(aborted());
+        return;
+    }
+    // Once a Linux pidfd transaction may have paused its owned processes, external
+    // cancellation must wait for its bounded cleanup. Killing the Windows pipe
+    // mid-transaction could strand a held process. The helper has its own alarm
+    // and TERM/HUP/INT cleanup, and the outer timeout is the final failure bound.
     void (0, asyncProcess_1.runAsyncProcess)('wsl.exe', args, {
         timeoutMs: options.timeoutMs,
-        signal: options.signal,
         maxBuffer: 64 * 1024,
         windowsHide: true,
     }).then(finish);
 });
 /**
- * Kills one previously verified WSL session/process group and proves that the
- * group no longer exists before its caller may launch a replacement. The bash
- * helper has its own bounded poll loop; the Windows child runner adds a second
- * timeout/cancellation boundary so Electron's event loop is never blocked.
+ * Terminates the verified runtime and its descendants, including detached
+ * tools, through identity-bound Linux pidfds. The historical export name is
+ * retained for callers; no numeric process-group signal is issued.
  */
 async function terminateWslRuntimeProcessGroup(distro, identityInput, runner = defaultWslCommandRunner, signal) {
     const identity = normalizeRuntimeIdentity(identityInput);
     if (!identity || identity.pid !== identity.pgid || identity.pgid !== identity.sessionId) {
-        throw new Error(`WSL runtime process group termination refused: unverified pid/pgid/session identity`);
+        throw new Error(`WSL runtime process group termination refused: unverified pid/pgid/session/birth identity`);
     }
     const target = identity.pgid;
-    const command = [
-        `if kill -0 -- "-${target}" 2>/dev/null; then kill -KILL -- "-${target}" 2>/dev/null || { echo 'runtime process group kill failed' >&2; exit 71; }; fi`,
-        `for attempt in {1..24}; do if ! kill -0 -- "-${target}" 2>/dev/null; then printf 'terminated:%s\\n' "${target}"; exit 0; fi; sleep 0.05; done`,
-        `echo 'runtime process group is still alive' >&2`,
-        `exit 72`,
-    ].join('; ');
-    // The Linux poll itself is bounded to about 1.2 s, but starting a second
-    // wsl.exe/bash helper and reaping it can exceed two seconds under Windows
-    // load even while the distribution is already warm. Keep this well below
-    // the 30 s cold-start budget while leaving enough room to verify teardown.
-    const result = await runner(['-d', distro, '--', 'bash', '-lc', command], { timeoutMs: 5_500, signal });
+    const result = await runner(['-d', distro, '--', 'bash', '-lc', (0, wslRuntimeProcessTree_1.wslRuntimeProcessTreeCommand)(identity)], { timeoutMs: 8_000, signal });
     if (result.status !== 0 || result.error || result.timedOut || result.aborted || result.overflowed) {
         const detail = String(result.stderr || result.error || `exit ${String(result.status)}`).trim().slice(-500);
         throw new Error(`WSL runtime process group termination failed for pgid ${target}: ${detail || 'unknown helper failure'}`);
     }
+    let receipt = null;
+    try {
+        receipt = JSON.parse(result.stdout.trim());
+    }
+    catch { }
+    if (receipt?.terminated !== true || receipt.method !== 'pidfd_tree' || receipt.rootPid !== identity.pid) {
+        throw new Error(`WSL runtime process tree termination remains unconfirmed: missing identity-bound completion receipt`);
+    }
 }
 class WslAgentClient {
     distro;
@@ -126,6 +129,10 @@ class WslAgentClient {
     remotePid = 0;
     remotePgid = 0;
     remoteSessionId = 0;
+    remoteStartTimeTicks = '';
+    remoteBootId = '';
+    restartQuarantined = '';
+    unconfirmedExit = null;
     startPromise = null;
     constructor(distro, windowsRoot, windowsHostScript, runtimeTarget = null, commandRunner = defaultWslCommandRunner) {
         this.distro = distro;
@@ -153,10 +160,14 @@ class WslAgentClient {
             pid: this.remotePid,
             pgid: this.remotePgid,
             sessionId: this.remoteSessionId,
+            startTimeTicks: this.remoteStartTimeTicks,
+            bootId: this.remoteBootId,
+            quarantined: !!this.restartQuarantined,
             error: this.lastError,
         };
     }
     async start() {
+        this.throwIfRestartQuarantined();
         if (this.child && !this.child.killed)
             return;
         if (this.startPromise)
@@ -226,6 +237,7 @@ class WslAgentClient {
                 catch { }
                 this.detachChild(child, error);
                 this.lastError = error.message;
+                this.restartQuarantined = this.lastError;
                 throw error;
             }
             if (this.child !== child || this.childGeneration !== generation)
@@ -233,6 +245,8 @@ class WslAgentClient {
             this.remotePid = identity.pid;
             this.remotePgid = identity.pgid;
             this.remoteSessionId = identity.sessionId;
+            this.remoteStartTimeTicks = identity.startTimeTicks;
+            this.remoteBootId = identity.bootId;
             this.lastError = '';
         }
         finally {
@@ -240,20 +254,29 @@ class WslAgentClient {
         }
     }
     async stop() {
+        // Pool disposal must not erase an owner whose descendant cleanup was never
+        // confirmed, including after its launcher exit cleared this.child.
+        this.throwIfRestartQuarantined();
         const child = this.child;
         if (!child)
             return;
         const generation = this.childGeneration;
-        const identity = { pid: this.remotePid, pgid: this.remotePgid, sessionId: this.remoteSessionId };
+        const identity = { pid: this.remotePid, pgid: this.remotePgid, sessionId: this.remoteSessionId, startTimeTicks: this.remoteStartTimeTicks, bootId: this.remoteBootId };
+        // Keep the identity anchor alive until the supervisor has captured all
+        // descendants. A detached tool can outlive a worker that exits first.
         try {
-            await this.request('shutdown', undefined, 250);
+            await this.request('shutdown', { supervisorTerminates: true }, 250);
         }
         catch { }
+        if (this.childGeneration !== generation)
+            return;
         try {
             await terminateWslRuntimeProcessGroup(this.distro, identity, this.commandRunner);
+            this.confirmTerminatedGeneration(generation);
         }
         catch (error) {
             this.lastError = error instanceof Error ? error.message : String(error);
+            this.restartQuarantined = this.lastError;
             throw error;
         }
         if (this.childGeneration !== generation)
@@ -298,9 +321,9 @@ class WslAgentClient {
         const target = await this.mapTarget(this.targetFromLegacy(conversationId, workspace));
         return await this.request('snapshot', { target }, 15000);
     }
-    async snapshotTarget(target) {
+    async snapshotTarget(target, options = {}) {
         await this.start();
-        return await this.request('snapshot', { target: await this.mapTarget(target) }, 15000);
+        return await this.request('snapshot', { target: await this.mapTarget(target), options }, 15000);
     }
     async rewind(target, messageIndex) {
         await this.start();
@@ -363,17 +386,18 @@ class WslAgentClient {
         await this.request('update_setting', { section, key, value }, 5_000);
     }
     async forceStopRuntimeGroup(signal) {
+        this.throwIfRestartQuarantined();
         const child = this.child;
         const generation = this.childGeneration;
         const identity = {
             pid: this.remotePid,
             pgid: this.remotePgid,
             sessionId: this.remoteSessionId,
+            startTimeTicks: this.remoteStartTimeTicks,
+            bootId: this.remoteBootId,
         };
         if (!child || child.killed)
             throw new Error('WSL runtime process group termination failed: runtime launcher is not connected');
-        if (!normalizeRuntimeIdentity(identity))
-            throw new Error('WSL runtime process group termination failed: runtime identity was not recorded');
         for (const [requestId, run] of this.hostToolRuns) {
             if (run.generation !== generation)
                 continue;
@@ -384,9 +408,11 @@ class WslAgentClient {
             this.hostToolHandler?.cancelTarget?.(this.runtimeTarget.runtimeKey);
         try {
             await terminateWslRuntimeProcessGroup(this.distro, identity, this.commandRunner, signal);
+            this.confirmTerminatedGeneration(generation);
         }
         catch (error) {
             this.lastError = error instanceof Error ? error.message : String(error);
+            this.restartQuarantined = this.lastError;
             throw error;
         }
         if (this.childGeneration !== generation)
@@ -402,11 +428,25 @@ class WslAgentClient {
         return 'terminated';
     }
     async forceRestartRuntimeGroup(signal) {
+        this.throwIfRestartQuarantined();
         const outcome = await this.forceStopRuntimeGroup(signal);
         if (outcome === 'stale')
             return;
         await this.start();
     }
+    throwIfRestartQuarantined() {
+        if (this.restartQuarantined)
+            throw new Error(`WSL runtime is quarantined until the app backend is restarted: ${this.restartQuarantined}`);
+    }
+    confirmTerminatedGeneration(generation) {
+        if (this.unconfirmedExit?.generation !== generation)
+            return;
+        if (this.restartQuarantined === this.unconfirmedExit.reason) {
+            this.restartQuarantined = '';
+            this.lastError = '';
+        }
+        this.unconfirmedExit = null;
+    }
     async terminalState(owner, persistenceRoot) {
         await this.start();
         return await this.request('terminal_state', { owner, persistenceRoot: persistenceRoot ? await this.toWslPath(persistenceRoot) : undefined }, 15000);
@@ -573,6 +613,12 @@ class WslAgentClient {
         if (this.child !== exitedChild)
             return;
         this.lastError = this.stderrBuffer || this.lastError;
+        if (this.remoteStartTimeTicks && !this.restartQuarantined) {
+            const reason = 'WSL runtime owner exited before descendant termination was confirmed';
+            this.unconfirmedExit = { generation: this.childGeneration, reason };
+            this.restartQuarantined = reason;
+            this.lastError = reason;
+        }
         const error = new Error(`WSL Agent backend exited (${code ?? 'unknown'}): ${this.lastError || 'no stderr'}`);
         this.detachChild(exitedChild, error);
     }
@@ -583,6 +629,8 @@ class WslAgentClient {
         this.remotePid = 0;
         this.remotePgid = 0;
         this.remoteSessionId = 0;
+        this.remoteStartTimeTicks = '';
+        this.remoteBootId = '';
         const generation = this.childGeneration;
         for (const [requestId, run] of this.hostToolRuns) {
             if (run.generation !== generation)
@@ -623,7 +671,11 @@ function normalizeRuntimeIdentity(input) {
     const sessionId = Number(input?.sessionId || 0);
     if (![pid, pgid, sessionId].every(value => Number.isSafeInteger(value) && value > 1))
         return null;
-    return { pid, pgid, sessionId };
+    const startTimeTicks = String(input?.startTimeTicks || '');
+    const bootId = String(input?.bootId || '').toLowerCase();
+    if (!/^\d+$/.test(startTimeTicks) || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(bootId))
+        return null;
+    return { pid, pgid, sessionId, startTimeTicks, bootId };
 }
 function shellQuote(value) {
     return `'${String(value).replace(/'/g, `'\\''`)}'`;

package/dist/core/wslAgentProtocol.d.ts

@@ -96,6 +96,10 @@ export type WslAgentRequest = {
         conversationId?: string;
         target?: ConversationRuntimeTarget;
         workspace?: WslAgentWorkspace | null;
+        options?: {
+            window?: number;
+            before?: number;
+        };
     };
 } | {
     id: string;
@@ -230,6 +234,9 @@ export type WslAgentRequest = {
 } | {
     id: string;
     method: 'shutdown';
+    params?: {
+        supervisorTerminates?: boolean;
+    };
 };
 export type WslAgentResponse = {
     id: string;

package/dist/core/wslAgentRuntimePool.d.ts

@@ -7,7 +7,10 @@ export interface WslTargetRuntimeClient {
     subscribe(listener: (event: AgentWorkEvent) => void): () => void;
     setHostToolHandler(handler: WslHostToolHandler | null): void;
     prompt(params: WslAgentPromptRequest): Promise<WslAgentPromptResult>;
-    snapshotTarget(target: ConversationRuntimeTarget): Promise<Record<string, unknown>>;
+    snapshotTarget(target: ConversationRuntimeTarget, options?: {
+        window?: number;
+        before?: number;
+    }): Promise<Record<string, unknown>>;
     rewind(target: ConversationRuntimeTarget, messageIndex: number): Promise<WslConversationRewindResult>;
     requestStop(target: ConversationRuntimeTarget, runId?: string): Promise<WslAgentStopResult>;
     enqueueGuide(target: ConversationRuntimeTarget, envelope: ConversationInputEnvelope): Promise<GuideReceipt>;
@@ -71,7 +74,10 @@ export declare class WslAgentRuntimePool {
     setHostToolHandler(handler: WslHostToolHandler | null): void;
     prompt(params: WslAgentPromptRequest): Promise<WslAgentPromptResult>;
     prewarm(target: ConversationRuntimeTarget): Promise<void>;
-    snapshot(target: ConversationRuntimeTarget): Promise<Record<string, unknown>>;
+    snapshot(target: ConversationRuntimeTarget, options?: {
+        window?: number;
+        before?: number;
+    }): Promise<Record<string, unknown>>;
     rewind(target: ConversationRuntimeTarget, messageIndex: number): Promise<WslConversationRewindResult>;
     requestStop(target: ConversationRuntimeTarget, runId?: string): Promise<WslPoolStopResult>;
     enqueueGuide(envelope: ConversationInputEnvelope): Promise<GuideReceipt>;