@methodts/runtime 0.1.0

package/dist/sessions/spawn-queue.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * SpawnQueue — enforces a minimum gap between PTY session spawns.
+ *
+ * Problem: concurrent spawns cause API rate-limit contention and resource
+ * spikes (PRD 012 observation). The bridge HTTP handler already staggers
+ * batch spawns with setTimeout, but individual bridge_spawn calls from
+ * different orchestrators can still fire simultaneously.
+ *
+ * Solution: all spawn requests pass through SpawnQueue.enqueue(), which
+ * ensures at least MIN_SPAWN_GAP_MS between actual PTY process launches.
+ * The queue is FIFO and serializes execution.
+ */
+const DEFAULT_MIN_SPAWN_GAP_MS = 2000;
+export class SpawnQueue {
+    minGapMs;
+    lastSpawnAt = 0;
+    queue = [];
+    processing = false;
+    constructor(options) {
+        this.minGapMs = options?.minGapMs ?? DEFAULT_MIN_SPAWN_GAP_MS;
+    }
+    enqueue(execute) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                execute: execute,
+                resolve: resolve,
+                reject,
+            });
+            this.drain();
+        });
+    }
+    get pending() {
+        return this.queue.length;
+    }
+    get lastSpawnTime() {
+        return this.lastSpawnAt;
+    }
+    async drain() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        while (this.queue.length > 0) {
+            const item = this.queue.shift();
+            const elapsed = Date.now() - this.lastSpawnAt;
+            if (elapsed < this.minGapMs && this.lastSpawnAt > 0) {
+                const waitMs = this.minGapMs - elapsed;
+                await new Promise(r => setTimeout(r, waitMs));
+            }
+            try {
+                const result = await item.execute();
+                this.lastSpawnAt = Date.now();
+                item.resolve(result);
+            }
+            catch (err) {
+                this.lastSpawnAt = Date.now();
+                item.reject(err);
+            }
+        }
+        this.processing = false;
+    }
+}
+//# sourceMappingURL=spawn-queue.js.map

package/dist/sessions/spawn-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-queue.js","sourceRoot":"","sources":["../../src/sessions/spawn-queue.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;;;;;GAWG;AAOH,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAEtC,MAAM,OAAO,UAAU;IACJ,QAAQ,CAAS;IAC1B,WAAW,GAAG,CAAC,CAAC;IAChB,KAAK,GAIR,EAAE,CAAC;IACA,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAY,OAA2B;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,wBAAwB,CAAC;IAChE,CAAC;IAED,OAAO,CAAI,OAAyB;QAClC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;gBACd,OAAO,EAAE,OAAiC;gBAC1C,OAAO,EAAE,OAAmC;gBAC5C,MAAM;aACP,CAAC,CAAC;YACH,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QAEvB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;YAEjC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;YAC9C,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;gBACpD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;gBACvC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;YAChD,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;gBACpC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC9B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;CACF"}

package/dist/sessions/spawn-queue.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spawn-queue.test.d.ts.map

package/dist/sessions/spawn-queue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-queue.test.d.ts","sourceRoot":"","sources":["../../src/sessions/spawn-queue.test.ts"],"names":[],"mappings":""}

package/dist/sessions/spawn-queue.test.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { SpawnQueue } from './spawn-queue.js';
+describe('SpawnQueue', () => {
+    it('executes a single enqueued operation', async () => {
+        const queue = new SpawnQueue({ minGapMs: 0 });
+        const result = await queue.enqueue(() => Promise.resolve('hello'));
+        assert.equal(result, 'hello');
+    });
+    it('enforces minimum gap between consecutive spawns', async () => {
+        const gapMs = 100;
+        const queue = new SpawnQueue({ minGapMs: gapMs });
+        const timestamps = [];
+        await queue.enqueue(async () => { timestamps.push(Date.now()); });
+        await queue.enqueue(async () => { timestamps.push(Date.now()); });
+        assert.equal(timestamps.length, 2);
+        const elapsed = timestamps[1] - timestamps[0];
+        assert.ok(elapsed >= gapMs - 20, `Expected >= ${gapMs - 20}ms gap, got ${elapsed}ms`);
+    });
+    it('does not delay the first spawn', async () => {
+        const queue = new SpawnQueue({ minGapMs: 5000 });
+        const before = Date.now();
+        await queue.enqueue(async () => 'fast');
+        const elapsed = Date.now() - before;
+        assert.ok(elapsed < 100, `First spawn should be immediate, took ${elapsed}ms`);
+    });
+    it('serializes concurrent enqueue calls', async () => {
+        const gapMs = 50;
+        const queue = new SpawnQueue({ minGapMs: gapMs });
+        const order = [];
+        const p1 = queue.enqueue(async () => { order.push(1); return 1; });
+        const p2 = queue.enqueue(async () => { order.push(2); return 2; });
+        const p3 = queue.enqueue(async () => { order.push(3); return 3; });
+        const results = await Promise.all([p1, p2, p3]);
+        assert.deepEqual(order, [1, 2, 3]);
+        assert.deepEqual(results, [1, 2, 3]);
+    });
+    it('propagates errors without blocking the queue', async () => {
+        const queue = new SpawnQueue({ minGapMs: 0 });
+        await assert.rejects(() => queue.enqueue(async () => { throw new Error('boom'); }), /boom/);
+        const result = await queue.enqueue(async () => 'recovered');
+        assert.equal(result, 'recovered');
+    });
+    it('reports pending count', async () => {
+        const queue = new SpawnQueue({ minGapMs: 100 });
+        assert.equal(queue.pending, 0);
+        let pendingDuringSecond = -1;
+        const p1 = queue.enqueue(async () => 'a');
+        const p2 = queue.enqueue(async () => {
+            pendingDuringSecond = queue.pending;
+            return 'b';
+        });
+        const p3 = queue.enqueue(async () => 'c');
+        await Promise.all([p1, p2, p3]);
+        assert.equal(pendingDuringSecond, 1);
+        assert.equal(queue.pending, 0);
+    });
+    it('uses default minGapMs when no options provided', async () => {
+        const queue = new SpawnQueue();
+        const result = await queue.enqueue(async () => 42);
+        assert.equal(result, 42);
+    });
+});
+//# sourceMappingURL=spawn-queue.test.js.map

package/dist/sessions/spawn-queue.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-queue.test.js","sourceRoot":"","sources":["../../src/sessions/spawn-queue.test.ts"],"names":[],"mappings":"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"}

package/dist/sessions/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sessions domain — collected type re-exports (PRD-057 / S2 §3.3 / C5).
+ *
+ * Transcript reader, routes, and `SessionsConfig` types live in
+ * `@methodts/bridge` — this barrel now re-exports only the types that
+ * belong to the runtime subpath. Bridge-internal code that needs the
+ * full historical bundle should import the specific modules directly.
+ */
+export type { SessionPool, SessionBudget, SessionChainInfo, SessionMode, IsolationMode, WorktreeAction, WorktreeInfo, StaleConfig, SessionStatusInfo, PoolStats, PoolOptions, StreamEvent, } from './pool.js';
+export type { PtySession, SessionStatus, AdaptiveSettleDelay } from './print-session.js';
+export type { ActivityObservation } from './auto-retro.js';
+export type { ChannelMessage, Channel, SessionChannels } from './channels.js';
+export type { SessionDiagnostics } from './diagnostics.js';
+export type { CognitiveSessionConfig, CognitiveSessionOptions, } from './cognitive-provider.js';
+export type { CognitiveEventContext } from './cognitive-sink.js';
+//# sourceMappingURL=types.d.ts.map

package/dist/sessions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sessions/types.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAGH,YAAY,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzF,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAG9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,YAAY,EACV,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/sessions/types.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Sessions domain — collected type re-exports (PRD-057 / S2 §3.3 / C5).
+ *
+ * Transcript reader, routes, and `SessionsConfig` types live in
+ * `@methodts/bridge` — this barrel now re-exports only the types that
+ * belong to the runtime subpath. Bridge-internal code that needs the
+ * full historical bundle should import the specific modules directly.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sessions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sessions/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;;GAOG"}

package/dist/sessions/worktree-stale.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worktree-stale.test.d.ts.map

package/dist/sessions/worktree-stale.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-stale.test.d.ts","sourceRoot":"","sources":["../../src/sessions/worktree-stale.test.ts"],"names":[],"mappings":""}

package/dist/sessions/worktree-stale.test.js

@@ -0,0 +1,468 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createSessionChannels, appendMessage, readMessages, } from './channels.js';
+/**
+ * Create a fake PtySession for testing without spawning a real PTY process.
+ * Supports controllable lastActivityAt for stale detection tests.
+ */
+function fakePtySession(id, initialStatus = 'ready') {
+    let status = initialStatus;
+    let promptCount = 0;
+    let lastActivityAt = new Date();
+    return {
+        id,
+        get status() { return status; },
+        set status(s) { status = s; },
+        queueDepth: 0,
+        get promptCount() { return promptCount; },
+        set promptCount(n) { promptCount = n; },
+        get lastActivityAt() { return lastActivityAt; },
+        set lastActivityAt(d) { lastActivityAt = d; },
+        get transcript() { return ''; },
+        onOutput(_cb) { return () => { }; },
+        onExit(_cb) { },
+        async sendPrompt(_prompt, _timeoutMs, _settleDelayMs) {
+            promptCount++;
+            lastActivityAt = new Date();
+            return { output: 'mock response', timedOut: false };
+        },
+        resize() { },
+        kill() {
+            status = 'dead';
+        },
+        interrupt() { return false; },
+        adaptiveSettle: null,
+        pid: null,
+    };
+}
+const DEFAULT_CHAIN = {
+    parent_session_id: null,
+    depth: 0,
+    children: [],
+    budget: { max_depth: 3, max_agents: 10, agents_spawned: 0 },
+};
+const DEFAULT_WORKTREE = {
+    isolation: 'shared',
+    worktree_path: null,
+    worktree_branch: null,
+    metals_available: true,
+};
+/**
+ * Test pool with stale detection support.
+ * Sessions can have their lastActivityAt manipulated for stale tests.
+ */
+function createStaleTestPool(maxSessions = 5) {
+    const sessions = new Map();
+    const sessionMetadata = new Map();
+    const sessionWorkdirs = new Map();
+    const sessionChains = new Map();
+    const sessionChannelsMap = new Map();
+    const sessionStaleConfigs = new Map();
+    const sessionStaleFlags = new Map();
+    let totalSpawned = 0;
+    const startedAt = new Date();
+    let nextId = 0;
+    // Expose internals for test manipulation
+    const _internals = { sessions, sessionStaleConfigs, sessionStaleFlags, sessionChannelsMap };
+    const pool = {
+        _internals,
+        async create({ workdir, initialPrompt: _initialPrompt, spawnArgs: _spawnArgs, metadata, parentSessionId, depth, budget, isolation: _isolation, timeout_ms }) {
+            const activeSessions = [...sessions.values()].filter((s) => s.status !== 'dead').length;
+            if (activeSessions >= maxSessions) {
+                throw new Error(`Session pool full — maximum ${maxSessions} active sessions`);
+            }
+            const effectiveDepth = depth ?? 0;
+            const effectiveBudget = {
+                max_depth: budget?.max_depth ?? 3,
+                max_agents: budget?.max_agents ?? 10,
+                agents_spawned: budget?.agents_spawned ?? 0,
+            };
+            if (parentSessionId) {
+                const parentChain = sessionChains.get(parentSessionId);
+                if (parentChain) {
+                    if (effectiveDepth >= parentChain.budget.max_depth) {
+                        throw new Error(JSON.stringify({ error: 'DEPTH_EXCEEDED' }));
+                    }
+                    if (parentChain.budget.agents_spawned >= parentChain.budget.max_agents) {
+                        throw new Error(JSON.stringify({ error: 'BUDGET_EXHAUSTED' }));
+                    }
+                    parentChain.budget.agents_spawned++;
+                    effectiveBudget.max_depth = parentChain.budget.max_depth;
+                    effectiveBudget.max_agents = parentChain.budget.max_agents;
+                    effectiveBudget.agents_spawned = parentChain.budget.agents_spawned;
+                }
+            }
+            const sessionId = `test-session-${nextId++}`;
+            const session = fakePtySession(sessionId);
+            sessions.set(sessionId, session);
+            sessionWorkdirs.set(sessionId, workdir);
+            if (metadata)
+                sessionMetadata.set(sessionId, metadata);
+            const chainInfo = {
+                parent_session_id: parentSessionId ?? null,
+                depth: effectiveDepth,
+                children: [],
+                budget: effectiveBudget,
+            };
+            sessionChains.set(sessionId, chainInfo);
+            const channels = createSessionChannels();
+            sessionChannelsMap.set(sessionId, channels);
+            appendMessage(channels.events, 'bridge', 'started', { session_id: sessionId });
+            // Stale config
+            const staleConfig = {
+                stale_timeout_ms: timeout_ms ?? 30 * 60 * 1000,
+                kill_timeout_ms: timeout_ms ? timeout_ms * 2 : 60 * 60 * 1000,
+            };
+            sessionStaleConfigs.set(sessionId, staleConfig);
+            sessionStaleFlags.set(sessionId, false);
+            if (parentSessionId) {
+                const parentChain = sessionChains.get(parentSessionId);
+                if (parentChain)
+                    parentChain.children.push(sessionId);
+            }
+            totalSpawned++;
+            return { sessionId, nickname: `test-${nextId - 1}`, status: session.status, chain: chainInfo, worktree: DEFAULT_WORKTREE, mode: 'print' };
+        },
+        async prompt(sessionId, prompt, timeoutMs, settleDelayMs) {
+            const session = sessions.get(sessionId);
+            if (!session)
+                throw new Error(`Session not found: ${sessionId}`);
+            if (session.status === 'dead')
+                throw new Error(`Session ${sessionId} is dead`);
+            // Reset stale flag on activity
+            sessionStaleFlags.set(sessionId, false);
+            const result = await session.sendPrompt(prompt, timeoutMs, settleDelayMs);
+            return { output: result.output, timedOut: result.timedOut, metadata: null };
+        },
+        async promptStream(sessionId, prompt, onEvent, timeoutMs) {
+            const result = await pool.prompt(sessionId, prompt, timeoutMs);
+            onEvent({ type: 'done', output: result.output, metadata: null, timed_out: result.timedOut });
+        },
+        status(sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session)
+                throw new Error(`Session not found: ${sessionId}`);
+            return {
+                sessionId: session.id,
+                nickname: session.id,
+                purpose: null,
+                status: session.status,
+                queueDepth: session.queueDepth,
+                metadata: sessionMetadata.get(sessionId),
+                promptCount: session.promptCount,
+                lastActivityAt: session.lastActivityAt,
+                workdir: sessionWorkdirs.get(sessionId) ?? '',
+                chain: sessionChains.get(sessionId) ?? DEFAULT_CHAIN,
+                worktree: DEFAULT_WORKTREE,
+                stale: sessionStaleFlags.get(sessionId) ?? false,
+                waiting_for: null,
+                mode: 'print',
+                diagnostics: null,
+            };
+        },
+        kill(sessionId, _worktreeAction) {
+            const session = sessions.get(sessionId);
+            if (!session)
+                throw new Error(`Session not found: ${sessionId}`);
+            session.kill();
+            const channels = sessionChannelsMap.get(sessionId);
+            if (channels) {
+                appendMessage(channels.events, 'bridge', 'killed', { session_id: sessionId });
+            }
+            return { sessionId: session.id, killed: true, worktree_cleaned: false };
+        },
+        list() {
+            return [...sessions.entries()].map(([sessionId, session]) => ({
+                sessionId: session.id,
+                nickname: session.id,
+                purpose: null,
+                status: session.status,
+                queueDepth: session.queueDepth,
+                metadata: sessionMetadata.get(sessionId),
+                promptCount: session.promptCount,
+                lastActivityAt: session.lastActivityAt,
+                workdir: sessionWorkdirs.get(sessionId) ?? '',
+                chain: sessionChains.get(sessionId) ?? DEFAULT_CHAIN,
+                worktree: DEFAULT_WORKTREE,
+                stale: sessionStaleFlags.get(sessionId) ?? false,
+                waiting_for: null,
+                mode: 'print',
+                diagnostics: null,
+            }));
+        },
+        getChannels(sessionId) {
+            const channels = sessionChannelsMap.get(sessionId);
+            if (!channels)
+                throw new Error(`Session not found: ${sessionId}`);
+            return channels;
+        },
+        getSession(sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session)
+                throw new Error(`Session not found: ${sessionId}`);
+            return session;
+        },
+        poolStats() {
+            const allSessions = [...sessions.values()];
+            const active = allSessions.filter((s) => s.status !== 'dead').length;
+            const dead = allSessions.filter((s) => s.status === 'dead').length;
+            return { totalSpawned, startedAt, maxSessions, activeSessions: active, deadSessions: dead };
+        },
+        removeDead(ttlMs) {
+            let removed = 0;
+            for (const [sessionId, session] of sessions.entries()) {
+                if (session.status === 'dead' && Date.now() - session.lastActivityAt.getTime() > ttlMs) {
+                    sessions.delete(sessionId);
+                    sessionMetadata.delete(sessionId);
+                    sessionWorkdirs.delete(sessionId);
+                    sessionChains.delete(sessionId);
+                    sessionChannelsMap.delete(sessionId);
+                    sessionStaleConfigs.delete(sessionId);
+                    sessionStaleFlags.delete(sessionId);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+        /**
+         * Stale detection — mirrors pool.ts checkStale() logic.
+         */
+        checkStale() {
+            const now = Date.now();
+            const staleIds = [];
+            const killedIds = [];
+            for (const [sessionId, session] of sessions.entries()) {
+                if (session.status === 'dead')
+                    continue;
+                const config = sessionStaleConfigs.get(sessionId);
+                if (!config)
+                    continue;
+                const inactiveMs = now - session.lastActivityAt.getTime();
+                const isStale = sessionStaleFlags.get(sessionId) ?? false;
+                if (inactiveMs >= config.kill_timeout_ms) {
+                    session.kill();
+                    const channels = sessionChannelsMap.get(sessionId);
+                    if (channels) {
+                        appendMessage(channels.events, 'bridge', 'stale', {
+                            session_id: sessionId,
+                            inactive_ms: inactiveMs,
+                            action: 'auto_killed',
+                        });
+                    }
+                    killedIds.push(sessionId);
+                    sessionStaleFlags.set(sessionId, true);
+                    continue;
+                }
+                if (inactiveMs >= config.stale_timeout_ms && !isStale) {
+                    sessionStaleFlags.set(sessionId, true);
+                    const channels = sessionChannelsMap.get(sessionId);
+                    if (channels) {
+                        appendMessage(channels.events, 'bridge', 'stale', {
+                            session_id: sessionId,
+                            inactive_ms: inactiveMs,
+                            action: 'marked_stale',
+                        });
+                    }
+                    staleIds.push(sessionId);
+                }
+            }
+            return { stale: staleIds, killed: killedIds };
+        },
+        childPids() {
+            return [];
+        },
+        setObservationHook() {
+            // no-op in test pool
+        },
+        restoreSession() {
+            // no-op in test pool
+        },
+        cleanupStaleCognitiveSessions() {
+            return { killed: [] };
+        },
+    };
+    return pool;
+}
+// ── Worktree Isolation Tests (PRD 006 Component 2) ───────────
+describe('Worktree Isolation (PRD 006 Component 2)', () => {
+    describe('WorktreeInfo defaults', () => {
+        it('shared session has metals_available: true and no worktree path', async () => {
+            const pool = createStaleTestPool();
+            const result = await pool.create({ workdir: '/tmp/test' });
+            assert.equal(result.worktree.isolation, 'shared');
+            assert.equal(result.worktree.worktree_path, null);
+            assert.equal(result.worktree.worktree_branch, null);
+            assert.equal(result.worktree.metals_available, true);
+        });
+        it('status includes worktree info', async () => {
+            const pool = createStaleTestPool();
+            const result = await pool.create({ workdir: '/tmp/test' });
+            const status = pool.status(result.sessionId);
+            assert.equal(status.worktree.isolation, 'shared');
+            assert.equal(status.worktree.metals_available, true);
+        });
+        it('list includes worktree info for all sessions', async () => {
+            const pool = createStaleTestPool();
+            await pool.create({ workdir: '/tmp/a' });
+            await pool.create({ workdir: '/tmp/b' });
+            const sessions = pool.list();
+            assert.equal(sessions.length, 2);
+            for (const s of sessions) {
+                assert.equal(s.worktree.isolation, 'shared');
+                assert.equal(s.worktree.metals_available, true);
+            }
+        });
+    });
+    describe('kill with worktree_action', () => {
+        it('kill returns worktree_cleaned: false for shared sessions', async () => {
+            const pool = createStaleTestPool();
+            const result = await pool.create({ workdir: '/tmp/test' });
+            const killResult = pool.kill(result.sessionId, 'discard');
+            assert.equal(killResult.killed, true);
+            assert.equal(killResult.worktree_cleaned, false);
+        });
+        it('kill without worktree_action defaults to keep', async () => {
+            const pool = createStaleTestPool();
+            const result = await pool.create({ workdir: '/tmp/test' });
+            const killResult = pool.kill(result.sessionId);
+            assert.equal(killResult.killed, true);
+            assert.equal(killResult.worktree_cleaned, false);
+        });
+    });
+});
+// ── Stale Detection Tests (PRD 006 Component 4) ─────────────
+describe('Stale Detection (PRD 006 Component 4)', () => {
+    describe('stale flag defaults', () => {
+        it('new session is not stale', async () => {
+            const pool = createStaleTestPool();
+            const result = await pool.create({ workdir: '/tmp/test' });
+            const status = pool.status(result.sessionId);
+            assert.equal(status.stale, false);
+        });
+        it('list includes stale flag', async () => {
+            const pool = createStaleTestPool();
+            await pool.create({ workdir: '/tmp/a' });
+            const sessions = pool.list();
+            assert.equal(sessions[0].stale, false);
+        });
+    });
+    describe('checkStale()', () => {
+        it('returns empty arrays when no sessions are stale', async () => {
+            const pool = createStaleTestPool();
+            await pool.create({ workdir: '/tmp/test' });
+            const result = pool.checkStale();
+            assert.deepEqual(result.stale, []);
+            assert.deepEqual(result.killed, []);
+        });
+        it('marks session stale after stale_timeout_ms', async () => {
+            const pool = createStaleTestPool();
+            // Create with very short timeout for testing
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 50 });
+            // Simulate inactivity by backdating lastActivityAt well beyond the threshold
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 5000); // 5s ago, well past 50ms stale but under 100ms kill
+            // Override stale config to ensure kill timeout is far away
+            pool._internals.sessionStaleConfigs.set(created.sessionId, {
+                stale_timeout_ms: 50,
+                kill_timeout_ms: 999_999,
+            });
+            const result = pool.checkStale();
+            assert.deepEqual(result.stale, [created.sessionId]);
+            assert.deepEqual(result.killed, []);
+            // Status should now show stale
+            const status = pool.status(created.sessionId);
+            assert.equal(status.stale, true);
+        });
+        it('does not mark dead sessions as stale', async () => {
+            const pool = createStaleTestPool();
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 50 });
+            // Kill it first
+            pool.kill(created.sessionId);
+            // Backdate
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 100);
+            const result = pool.checkStale();
+            assert.deepEqual(result.stale, []);
+            assert.deepEqual(result.killed, []);
+        });
+        it('auto-kills session after kill_timeout_ms', async () => {
+            const pool = createStaleTestPool();
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 50 });
+            // kill_timeout_ms = 50 * 2 = 100
+            // Backdate beyond kill timeout
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 150); // 150ms ago, > 100ms kill timeout
+            const result = pool.checkStale();
+            assert.deepEqual(result.stale, []);
+            assert.deepEqual(result.killed, [created.sessionId]);
+            // Session should now be dead
+            assert.equal(session.status, 'dead');
+        });
+        it('emits stale event to channels when marking stale', async () => {
+            const pool = createStaleTestPool();
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 50 });
+            // Backdate
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 75); // Past stale, not past kill
+            pool.checkStale();
+            // Read events channel — should have 'started' + 'stale'
+            const channels = pool.getChannels(created.sessionId);
+            const events = readMessages(channels.events, 0);
+            assert.equal(events.messages.length, 2); // started + stale
+            assert.equal(events.messages[1].type, 'stale');
+            assert.equal(events.messages[1].content.action, 'marked_stale');
+        });
+        it('emits stale event with auto_killed action when killing', async () => {
+            const pool = createStaleTestPool();
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 50 });
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 150); // Past kill timeout
+            pool.checkStale();
+            const channels = pool.getChannels(created.sessionId);
+            const events = readMessages(channels.events, 0);
+            const staleEvent = events.messages.find(m => m.type === 'stale');
+            assert.ok(staleEvent);
+            assert.equal(staleEvent.content.action, 'auto_killed');
+        });
+        it('does not double-mark already stale sessions', async () => {
+            const pool = createStaleTestPool();
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 50 });
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 75); // Past stale, not kill
+            // First check — marks stale
+            const result1 = pool.checkStale();
+            assert.deepEqual(result1.stale, [created.sessionId]);
+            // Second check — already stale, should not re-mark
+            const result2 = pool.checkStale();
+            assert.deepEqual(result2.stale, []);
+        });
+        it('uses custom timeout_ms when provided', async () => {
+            const pool = createStaleTestPool();
+            // 10ms stale timeout, 20ms kill timeout
+            const created = await pool.create({ workdir: '/tmp/test', timeout_ms: 10 });
+            const session = pool._internals.sessions.get(created.sessionId);
+            session.lastActivityAt = new Date(Date.now() - 15); // Past 10ms stale, not 20ms kill
+            const result = pool.checkStale();
+            assert.deepEqual(result.stale, [created.sessionId]);
+            assert.deepEqual(result.killed, []);
+        });
+        it('multiple sessions can be stale independently', async () => {
+            const pool = createStaleTestPool();
+            const s1 = await pool.create({ workdir: '/tmp/a', timeout_ms: 50 });
+            const s2 = await pool.create({ workdir: '/tmp/b', timeout_ms: 50 });
+            const s3 = await pool.create({ workdir: '/tmp/c', timeout_ms: 50 });
+            // Make s1 and s3 stale, leave s2 active
+            pool._internals.sessions.get(s1.sessionId).lastActivityAt = new Date(Date.now() - 75);
+            pool._internals.sessions.get(s3.sessionId).lastActivityAt = new Date(Date.now() - 75);
+            const result = pool.checkStale();
+            assert.equal(result.stale.length, 2);
+            assert.ok(result.stale.includes(s1.sessionId));
+            assert.ok(result.stale.includes(s3.sessionId));
+            assert.deepEqual(result.killed, []);
+            // s2 should not be stale
+            assert.equal(pool.status(s2.sessionId).stale, false);
+        });
+    });
+});
+//# sourceMappingURL=worktree-stale.test.js.map