specrails-desktop 2.29.0 → 2.29.2

package/server/dist/agent-refine-manager.js

@@ -44,6 +44,9 @@ class AgentRefineManager {
     _cancelledIds = new Set();
     /** Pending SIGKILL escalation timers, keyed by refine id (BUG-LONGTAIL-02). */
     _killTimers = new Map();
+    /** Provider evidence retained outside the awaiting stack so shutdown can
+     *  account it while the project DB is still open. */
+    _liveAccounting = new Map();
     constructor(broadcast, db, projectPath, projectId, provider) {
         this._broadcast = broadcast;
         this._db = db;
@@ -93,7 +96,13 @@ class AgentRefineManager {
      * orphaned refine child. Idempotent.
      */
     shutdown() {
+        if (this._disposed)
+            return;
         this._disposed = true;
+        for (const [refineId, live] of this._liveAccounting) {
+            this._recordRefineInvocation(refineId, live.events, live.model, 'aborted', live.startedAt);
+        }
+        this._liveAccounting.clear();
         for (const [refineId, child] of this._activeProcesses) {
             if (child.pid)
                 this._killWithEscalation(refineId, child.pid);
@@ -103,6 +112,7 @@ class AgentRefineManager {
     }
     /** Start a new refine session for the given custom agent. */
     async startRefine(opts) {
+        this._assertActive();
         if (!CUSTOM_PREFIX.test(opts.agentId)) {
             throw new Error('not_a_custom_agent');
         }
@@ -128,6 +138,7 @@ class AgentRefineManager {
     }
     /** Send a follow-up instruction on an existing session. */
     async sendTurn(opts) {
+        this._assertActive();
         const session = (0, agent_refine_db_1.getRefineSession)(this._db, opts.refineId);
         if (!session)
             throw new Error('session_not_found');
@@ -140,6 +151,7 @@ class AgentRefineManager {
     }
     /** Cancel an in-flight session. Idempotent. */
     cancel(refineId) {
+        this._assertActive();
         const child = this._activeProcesses.get(refineId);
         if (child?.pid) {
             // Mark intentionally-cancelled BEFORE killing so the spawn's settle path
@@ -161,6 +173,7 @@ class AgentRefineManager {
     }
     /** Toggle auto-test for a session. */
     toggleAutoTest(refineId, enabled) {
+        this._assertActive();
         const session = (0, agent_refine_db_1.getRefineSession)(this._db, refineId);
         if (!session)
             throw new Error('session_not_found');
@@ -168,6 +181,7 @@ class AgentRefineManager {
     }
     /** Apply the current draft_body to disk through the standard write path. */
     apply(opts) {
+        this._assertActive();
         const session = (0, agent_refine_db_1.getRefineSession)(this._db, opts.refineId);
         if (!session)
             return { ok: false, reason: 'session_not_found' };
@@ -206,10 +220,15 @@ class AgentRefineManager {
     }
     /** Hard-delete a session (used by cleanup/admin paths). */
     destroy(refineId) {
+        this._assertActive();
         this.cancel(refineId);
         (0, agent_refine_db_1.deleteRefineSession)(this._db, refineId);
     }
     // ─── Private ──────────────────────────────────────────────────────────────
+    _assertActive() {
+        if (this._disposed)
+            throw new Error('manager_disposed');
+    }
     _agentFile(agentId) {
         // Per-provider on-disk layout:
         //   claude → <root>/.claude/agents/<agentId>.md
@@ -259,15 +278,22 @@ class AgentRefineManager {
             ? 'chat-resume'
             : 'agent-refine';
         const refineModel = this._adapter.defaultModel();
-        const args = this._adapter.buildArgs(action, {
+        const buildOpts = {
             prompt,
             model: refineModel,
             sessionId: session.session_id ?? undefined,
-        });
+            // The model receives the complete current agent body in its prompt and
+            // must only return a replacement body. Repo tools cannot improve this
+            // contract and would turn prompt text into filesystem authority.
+            toolPolicy: 'none',
+        };
+        const args = this._adapter.buildArgs(action, buildOpts);
         let drafted = false;
         this._bodyBuffers.set(refineId, '');
         const turnStartedAt = new Date().toISOString();
         const spawnState = { err: null };
+        const liveAccounting = { events: [], model: refineModel, startedAt: turnStartedAt };
+        this._liveAccounting.set(refineId, liveAccounting);
         // Spawn / stream / settlement is owned by the shared spawn-lifecycle; the
         // refine-specific draft buffering, accounting, validation and history all
         // stay here unchanged.
@@ -277,13 +303,17 @@ class AgentRefineManager {
         const refineEnv = refineExec.relocated ? { ...process.env, ...refineExec.env } : undefined;
         const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
             adapter: this._adapter,
-            action,
-            buildOpts: { prompt, model: refineModel, sessionId: session.session_id ?? undefined },
+            // Pass the already-policy-bound argv so first turns and native resumes
+            // cannot diverge if the lifecycle rebuilds options later.
+            argv: args,
             cwd: refineExec.cwd,
             env: refineEnv,
             onSpawn: (child) => this._activeProcesses.set(refineId, child),
             onSpawnError: (err) => { spawnState.err = err; },
             onEvent: (ev) => {
+                if (this._disposed)
+                    return;
+                liveAccounting.events.push(ev);
                 switch (ev.kind) {
                     case 'text-delta': {
                         if (!drafted) {
@@ -320,6 +350,7 @@ class AgentRefineManager {
         });
         this._clearKillTimer(refineId);
         this._activeProcesses.delete(refineId);
+        this._liveAccounting.delete(refineId);
         const fullDraft = this._bodyBuffers.get(refineId) ?? '';
         this._bodyBuffers.delete(refineId);
         // A cancel() killed this child intentionally; its non-zero exit must NOT
@@ -329,9 +360,13 @@ class AgentRefineManager {
         // adapter events) BEFORE short-circuiting — otherwise the cancel path loses
         // 100% of its spend (MED-12). No status overwrite, no failure emit.
         const wasCancelled = this._cancelledIds.delete(refineId);
-        if (wasCancelled || this._disposed) {
+        // shutdown() already flushed this live run synchronously while the DB was
+        // open. A cancel racing with project removal must not insert it twice.
+        if (this._disposed)
+            return;
+        if (wasCancelled) {
             this._recordRefineInvocation(refineId, run.events, refineModel, 'aborted', turnStartedAt);
-            return; // cancel (BUG-LONGTAIL-01) / M12 dispose: project removed mid-flight
+            return; // cancel (BUG-LONGTAIL-01)
         }
         if (run.spawnFailed) {
             this._emitError(refineId, `Failed to launch claude: ${spawnState.err?.message ?? 'spawn error'}`);
@@ -427,6 +462,8 @@ class AgentRefineManager {
         }
     }
     async _runAutoTest(refineId, agentId, draftBody, draftHash) {
+        if (this._disposed)
+            return;
         (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { phase: 'testing' });
         this._emitPhase(refineId, 'testing');
         const sampleTask = pickSampleTask(this._db, agentId);
@@ -440,6 +477,8 @@ class AgentRefineManager {
                     ? { db: this._db, projectId: this._projectId, surfaceRefId: refineId, broadcast: this._broadcast }
                     : undefined,
             });
+            if (this._disposed)
+                return;
             this._db.prepare(`INSERT INTO agent_tests (agent_name, draft_hash, sample_task_id, tokens, duration_ms, output, created_at)
          VALUES (?, ?, ?, ?, ?, ?, ?)`).run(agentId, result.draftHash, null, result.tokens, result.durationMs, result.output, Date.now());
             (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, {
@@ -462,6 +501,8 @@ class AgentRefineManager {
             });
         }
         catch (err) {
+            if (this._disposed)
+                return;
             this._emitError(refineId, `Auto-test failed: ${err.message}`);
             (0, agent_refine_db_1.updateRefineSession)(this._db, refineId, { phase: 'done' });
         }

package/server/dist/agent-tier.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_CONVERSATION_ENV = exports.AGENT_CONVERSATION_HEADER = exports.AGENT_PROJECT_ENV = exports.AGENT_PROJECT_HEADER = exports.AGENT_TIER_ENV = exports.AGENT_TIER_HEADER = exports.AGENT_TIER_NAMES = void 0;
+exports.AGENT_CAPABILITY_FILE_ENV = exports.AGENT_CAPABILITY_HEADER = exports.AGENT_CONVERSATION_ENV = exports.AGENT_CONVERSATION_HEADER = exports.AGENT_PROJECT_ENV = exports.AGENT_PROJECT_HEADER = exports.AGENT_TIER_ENV = exports.AGENT_TIER_HEADER = exports.AGENT_TIER_NAMES = void 0;
 exports.tierNameForLevel = tierNameForLevel;
 exports.levelForTierName = levelForTierName;
 exports.normalizeLevel = normalizeLevel;
@@ -14,19 +14,22 @@ exports.AGENT_TIER_NAMES = [
     'operate',
     'autonomous',
 ];
-/** The HTTP header the agent's MCP bridge sets so the tool guard can read the level. */
+/** @deprecated Untrusted legacy header retained for compatibility/negative tests. */
 exports.AGENT_TIER_HEADER = 'x-specrails-agent-tier';
-/** Env var the AgentChatManager sets on the bridge spawn; the bridge forwards it as the header. */
+/** @deprecated Untrusted legacy env var; the bridge deliberately ignores it. */
 exports.AGENT_TIER_ENV = 'SPECRAILS_AGENT_TIER';
-/** Header carrying the pinned project id so tools resolve it per-request. */
+/** @deprecated Untrusted legacy header retained for compatibility/negative tests. */
 exports.AGENT_PROJECT_HEADER = 'x-specrails-active-project';
-/** Env var the manager sets on the bridge spawn; the bridge forwards it as the project header. */
+/** @deprecated Untrusted legacy env var; the bridge deliberately ignores it. */
 exports.AGENT_PROJECT_ENV = 'SPECRAILS_ACTIVE_PROJECT';
-/** Header carrying the launching agent-chat conversation id (safe-pr-review-flow
- *  origin link) so an MCP-launched rail can be tagged with its origin. */
+/** @deprecated Untrusted legacy header retained for compatibility/negative tests. */
 exports.AGENT_CONVERSATION_HEADER = 'x-specrails-agent-conversation';
-/** Env var set on the bridge spawn; the bridge forwards it as the conversation header. */
+/** @deprecated Untrusted legacy env var; the bridge deliberately ignores it. */
 exports.AGENT_CONVERSATION_ENV = 'SPECRAILS_AGENT_CONVERSATION';
+/** Bearer-like proof that an MCP request belongs to a live in-app agent turn. */
+exports.AGENT_CAPABILITY_HEADER = 'x-specrails-agent-capability';
+/** 0600 file path read by the bridge; the secret itself never appears in argv. */
+exports.AGENT_CAPABILITY_FILE_ENV = 'SPECRAILS_AGENT_CAPABILITY_FILE';
 /** Which MCP tiers a given ladder level unlocks (cumulative). */
 const TIERS_BY_LEVEL = {
     0: new Set(['read']),
@@ -64,9 +67,8 @@ function levelAllowsTier(level, tier) {
     return TIERS_BY_LEVEL[level].has(tier);
 }
 /**
- * Parse the agent-tier header value into a level, or null when absent/invalid.
- * The header carries the tier NAME (observe/edit/operate/autonomous) or the
- * numeric level; anything else yields null (→ fall back to Settings tiers).
+ * Parse a legacy tier value. Retained for UI/storage compatibility only: MCP
+ * request authorization MUST use a verified server-minted capability instead.
  */
 function levelFromHeader(headerValue) {
     if (headerValue == null)

package/server/dist/artifact-registry.js

@@ -38,13 +38,16 @@ exports.readRegistryOrEmpty = readRegistryOrEmpty;
 exports.atomicWrite = atomicWrite;
 exports.refreshLockHeartbeat = refreshLockHeartbeat;
 exports.withFileLock = withFileLock;
+exports.mirrorProjectEntryWithPrevious = mirrorProjectEntryWithPrevious;
 exports.mirrorProjectEntry = mirrorProjectEntry;
 exports.resolveArtifacts = resolveArtifacts;
 exports.removeRegistryEntry = removeRegistryEntry;
+exports.restoreRegistryEntry = restoreRegistryEntry;
 exports.reconcileFromProjects = reconcileFromProjects;
 const fs_1 = require("fs");
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const util_1 = require("util");
 /** Registry schema version. A reader that sees a higher value MUST treat all
  *  entries as absent (legacy fallback), never mis-parse. */
 exports.REGISTRY_SCHEMA_VERSION = 1;
@@ -458,7 +461,7 @@ function buildMirroredEntry(existing, canon, desiredSlug, input, now, touchInsta
  *
  * Runs under the file lock with a re-read so concurrent writers serialise.
  */
-function mirrorProjectEntry(input, home) {
+function mirrorProjectEntryWithPrevious(input, home) {
     const canon = canonicalizeRepoPath(input.repoPath);
     const key = normalizeKey(canon);
     const { providers, primaryProvider } = normalizeProviders(input.providers, input.primaryProvider);
@@ -480,9 +483,12 @@ function mirrorProjectEntry(input, home) {
         reg.generator = 'specrails-desktop';
         reg.updatedAt = now;
         atomicWrite(registryPath(home), JSON.stringify(reg, null, 2) + '\n');
-        return entry;
+        return { entry, previousEntry: existing };
     });
 }
+function mirrorProjectEntry(input, home) {
+    return mirrorProjectEntryWithPrevious(input, home).entry;
+}
 /**
  * Resolve a repo's artifact locations from the registry (read-only). Returns a
  * legacy (repo-relative) resolution when no entry exists, so callers can treat
@@ -541,6 +547,31 @@ function removeRegistryEntry(repoPath, home) {
         atomicWrite(registryPath(home), JSON.stringify(reg, null, 2) + '\n');
     });
 }
+/** Restore a repo's exact pre-mirror entry, or remove the newly-created entry
+ * when no entry existed before the mirror. Used only to roll back a failed
+ * higher-level project registration after the mirror itself succeeded. */
+function restoreRegistryEntry(repoPath, previousEntry, expectedCurrentEntry, home) {
+    const canon = canonicalizeRepoPath(repoPath);
+    const key = normalizeKey(canon);
+    return withFileLock(home, () => {
+        const reg = readRegistryOrEmpty(home);
+        // Hydration happens after the mirror lock is released. If core or another
+        // desktop process updated this repo meanwhile, that newer entry is no
+        // longer our mutation to undo. Leave it intact instead of restoring stale
+        // state over a lock-respecting concurrent writer.
+        if (!(0, util_1.isDeepStrictEqual)(reg.projects[key], expectedCurrentEntry))
+            return false;
+        if (previousEntry)
+            reg.projects[key] = previousEntry;
+        else
+            delete reg.projects[key];
+        reg.schemaVersion = exports.REGISTRY_SCHEMA_VERSION;
+        reg.generator = 'specrails-desktop';
+        reg.updatedAt = new Date().toISOString();
+        atomicWrite(registryPath(home), JSON.stringify(reg, null, 2) + '\n');
+        return true;
+    });
+}
 /**
  * MERGE-upsert one entry per desktop project, leaving entries NOT owned by
  * desktop (`source:'core-standalone'` for repos desktop doesn't track)

package/server/dist/auth.js

@@ -18,6 +18,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const crypto_1 = require("crypto");
+const secure_token_file_1 = require("./util/secure-token-file");
 const TOKEN_DIR = path_1.default.join(os_1.default.homedir(), '.specrails');
 const TOKEN_PATH = path_1.default.join(TOKEN_DIR, 'desktop.token');
 // Legacy (pre-rebrand) token filename — referenced by the one-time migration
@@ -58,8 +59,9 @@ function loadOrGenerateToken() {
         return _token;
     migrateLegacyTokenFile();
     try {
-        if (fs_1.default.existsSync(TOKEN_PATH)) {
-            const t = fs_1.default.readFileSync(TOKEN_PATH, 'utf-8').trim();
+        const stored = (0, secure_token_file_1.readPrivateTextFile)(TOKEN_PATH);
+        if (stored !== null) {
+            const t = stored.trim();
             if (t && t.length >= 32) {
                 _token = t;
                 return _token;
@@ -71,8 +73,7 @@ function loadOrGenerateToken() {
     }
     _token = (0, crypto_1.randomUUID)().replace(/-/g, '') + (0, crypto_1.randomUUID)().replace(/-/g, '');
     try {
-        fs_1.default.mkdirSync(TOKEN_DIR, { recursive: true });
-        fs_1.default.writeFileSync(TOKEN_PATH, _token, { encoding: 'utf-8', mode: 0o600 });
+        (0, secure_token_file_1.writePrivateTextFile)(TOKEN_PATH, _token);
     }
     catch (err) {
         console.warn('[auth] could not persist token to disk:', err);

package/server/dist/browser-capture-manager.js

@@ -19,6 +19,8 @@ function isTargetClosedError(err) {
     return /target page, context or browser has been closed|target closed|has been closed/i.test(msg);
 }
 const MAX_SESSIONS_PER_PROJECT = 4;
+const DEFAULT_SESSION_IDLE_TTL_MS = 10 * 60_000;
+const DEFAULT_SESSION_SWEEP_INTERVAL_MS = 60_000;
 const DOM_HTML_BYTE_CAP = 100_000;
 const LAST_URL_KEY = 'config.browser_last_url';
 /** Conflation threshold for the screencast fan-out: skip sending a frame to a
@@ -52,6 +54,9 @@ class BrowserCaptureManager {
     /** When set, pages are opened in this app-wide shared context (global cookies)
      *  and this manager never owns/closes the context — only its own pages. */
     contextPool;
+    now;
+    sessionIdleTtlMs;
+    idleSweepTimer = null;
     context = null;
     contextPromise = null;
     sessions = new Map();
@@ -67,9 +72,20 @@ class BrowserCaptureManager {
         this.launcher = opts.launcher ?? (0, browser_playwright_1.createPlaywrightLauncher)();
         this.attachments = opts.attachments ?? attachment_manager_1.attachmentManager;
         this.contextPool = opts.contextPool ?? null;
+        this.now = opts.now ?? Date.now;
+        const requestedIdleTtlMs = opts.sessionIdleTtlMs;
+        this.sessionIdleTtlMs = typeof requestedIdleTtlMs === 'number' && Number.isFinite(requestedIdleTtlMs) && requestedIdleTtlMs > 0
+            ? requestedIdleTtlMs
+            : DEFAULT_SESSION_IDLE_TTL_MS;
         this.profileDir =
             opts.profileDir ??
                 path_1.default.join(opts.homeDir ?? os_1.default.homedir(), '.specrails', 'projects', opts.projectSlug, 'browser-profile');
+        const requestedSweepIntervalMs = opts.sessionSweepIntervalMs;
+        const sweepIntervalMs = typeof requestedSweepIntervalMs === 'number' && Number.isFinite(requestedSweepIntervalMs) && requestedSweepIntervalMs > 0
+            ? requestedSweepIntervalMs
+            : Math.min(DEFAULT_SESSION_SWEEP_INTERVAL_MS, this.sessionIdleTtlMs);
+        this.idleSweepTimer = setInterval(() => { void this.sweepIdleSessions(); }, sweepIntervalMs);
+        this.idleSweepTimer.unref?.();
     }
     // ─── Last-URL persistence (reuses the queue_state key/value table) ───────────
     getLastUrl() {
@@ -138,6 +154,20 @@ class BrowserCaptureManager {
         const s = this.sessions.get(sessionId);
         return s && !s.closed ? s : undefined;
     }
+    getSessionForActivity(sessionId) {
+        const s = this.getSession(sessionId);
+        if (s)
+            s.lastActivityAt = this.now();
+        return s;
+    }
+    beginOperation(s) {
+        s.lastActivityAt = this.now();
+        s.activeOperations += 1;
+    }
+    endOperation(s) {
+        s.activeOperations = Math.max(0, s.activeOperations - 1);
+        s.lastActivityAt = this.now();
+    }
     async create(opts) {
         // Reserve the slot SYNCHRONOUSLY before any await so N concurrent creates can't
         // all observe `< MAX` and race past the cap (BUG-BROWSER-02). `_reserved`
@@ -170,6 +200,7 @@ class BrowserCaptureManager {
             throw new browser_capture_types_1.BrowserLimitExceededError(MAX_SESSIONS_PER_PROJECT);
         }
         const id = (0, ids_1.newId)();
+        const activityAt = this.now();
         const session = {
             id,
             projectId: this.projectId,
@@ -181,7 +212,9 @@ class BrowserCaptureManager {
             url: null,
             title: null,
             viewport: { ...DEFAULT_VIEWPORT },
-            createdAt: opts?.createdAtMs ?? this.now(),
+            createdAt: opts?.createdAtMs ?? activityAt,
+            lastActivityAt: activityAt,
+            activeOperations: 0,
             screencastPage: null,
             screencastDesired: false,
             screencastOp: null,
@@ -302,7 +335,7 @@ class BrowserCaptureManager {
     /** Switch the viewed page between the root page and the top popup ("back to
      *  page" / "show login window"). Returns false for an unknown session. */
     setPopupView(sessionId, target) {
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return false;
         s.popupView = target === 'popup' && s.popups.length > 0;
@@ -314,7 +347,7 @@ class BrowserCaptureManager {
     async attach(sessionId, ws) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
         s.clients.add(ws);
@@ -336,6 +369,7 @@ class BrowserCaptureManager {
         if (!s)
             return;
         s.clients.delete(ws);
+        s.lastActivityAt = this.now();
         if (s.clients.size === 0 && !s.closed) {
             s.screencastDesired = false;
             void this.applyScreencast(s);
@@ -406,7 +440,7 @@ class BrowserCaptureManager {
     async probeElement(sessionId, point) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
         return s.page.probeElementAt(point);
@@ -415,7 +449,7 @@ class BrowserCaptureManager {
     async navigateElement(sessionId, selector, direction) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
         return (await s.page.navigateElement?.(selector, direction)) ?? null;
@@ -423,7 +457,7 @@ class BrowserCaptureManager {
     async handleInput(sessionId, event) {
         if (this.disposed)
             return;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return;
         if (event.type === 'resize') {
@@ -449,30 +483,36 @@ class BrowserCaptureManager {
     async navigate(sessionId, action, url) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
-        let result;
-        if (action === 'goto')
-            result = await s.page.goto(url ?? 'about:blank');
-        else if (action === 'back')
-            result = await s.page.goBack();
-        else if (action === 'forward')
-            result = await s.page.goForward();
-        else
-            result = await s.page.reload();
-        s.url = result.url;
-        s.title = result.title;
-        if (result.url && result.url !== 'about:blank')
-            this.setLastUrl(result.url);
-        this.broadcastControl(s, { type: 'nav', url: result.url, title: result.title });
-        return result;
+        this.beginOperation(s);
+        try {
+            let result;
+            if (action === 'goto')
+                result = await s.page.goto(url ?? 'about:blank');
+            else if (action === 'back')
+                result = await s.page.goBack();
+            else if (action === 'forward')
+                result = await s.page.goForward();
+            else
+                result = await s.page.reload();
+            s.url = result.url;
+            s.title = result.title;
+            if (result.url && result.url !== 'about:blank')
+                this.setLastUrl(result.url);
+            this.broadcastControl(s, { type: 'nav', url: result.url, title: result.title });
+            return result;
+        }
+        finally {
+            this.endOperation(s);
+        }
     }
     // ─── Capture: screenshot + rich DOM → attachments ───────────────────────────
     async capture(sessionId, rect, pendingSpecId, opts) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
         const safeRect = {
@@ -483,6 +523,7 @@ class BrowserCaptureManager {
         };
         let png;
         let dom;
+        this.beginOperation(s);
         try {
             ;
             [png, dom] = await Promise.all([
@@ -500,6 +541,9 @@ class BrowserCaptureManager {
             }
             throw err;
         }
+        finally {
+            this.endOperation(s);
+        }
         // Snapshot the recent network requests into the DOM payload (rides the same
         // JSON attachment → spec prompt). ON unless the spec explicitly disabled it.
         if (opts?.captureNetwork !== false) {
@@ -546,7 +590,7 @@ class BrowserCaptureManager {
     async clipboard(sessionId, action, text) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
         // Clipboard follows the viewed page: pasting credentials into an OAuth
@@ -575,12 +619,13 @@ class BrowserCaptureManager {
     async captureBreakpoints(sessionId, rect, anchorPoint, pendingSpecId, dims) {
         if (this.disposed)
             return null;
-        const s = this.getSession(sessionId);
+        const s = this.getSessionForActivity(sessionId);
         if (!s)
             return null;
         const order = Object.keys(dims);
         if (order.length === 0)
             return null;
+        this.beginOperation(s);
         const stashed = { ...s.viewport };
         let selector = null;
         try {
@@ -640,6 +685,7 @@ class BrowserCaptureManager {
             }
             catch { /* ignore */ }
             s.viewport = stashed;
+            this.endOperation(s);
         }
         const stamp = this.now();
         const breakpoints = {};
@@ -673,6 +719,23 @@ class BrowserCaptureManager {
         };
     }
     // ─── Teardown ───────────────────────────────────────────────────────────────
+    /** Reap sessions abandoned by clients. A connected socket or page-dependent
+     *  operation is authoritative activity and prevents expiry. `kill()` removes
+     *  the map entry synchronously, so an attach cannot race between the final
+     *  eligibility check and teardown on this event loop. */
+    async sweepIdleSessions() {
+        if (this.disposed)
+            return 0;
+        const expiresBefore = this.now() - this.sessionIdleTtlMs;
+        let reaped = 0;
+        for (const [id, s] of this.sessions) {
+            if (s.closed || s.clients.size > 0 || s.activeOperations > 0 || s.lastActivityAt > expiresBefore)
+                continue;
+            if (await this.kill(id))
+                reaped += 1;
+        }
+        return reaped;
+    }
     async kill(sessionId) {
         const s = this.sessions.get(sessionId);
         if (!s)
@@ -709,6 +772,10 @@ class BrowserCaptureManager {
         return true;
     }
     async shutdown() {
+        if (this.idleSweepTimer) {
+            clearInterval(this.idleSweepTimer);
+            this.idleSweepTimer = null;
+        }
         if (this.disposed)
             return;
         this.disposed = true;
@@ -757,9 +824,5 @@ class BrowserCaptureManager {
     sessionCount() {
         return [...this.sessions.values()].filter((s) => !s.closed).length;
     }
-    // Wall-clock indirection so tests can stay deterministic if needed.
-    now() {
-        return Date.now();
-    }
 }
 exports.BrowserCaptureManager = BrowserCaptureManager;