termdock 1.4.324 → 1.4.325

package/dist/server/routes/terminal.js

@@ -52,6 +52,8 @@ import { AgentResumeHistoryStore } from '../agent/resumeHistory.js';
 import { completedExecution, ExecutionArchiveStore } from '../agent/executionArchives.js';
 import { archiveTaskWorkspace, restoreTaskWorkspace, snapshotTaskWorkspace } from '../agent/collaborationTaskWorkspace.js';
 import { isTmuxRecoveryCandidate } from '../utils/tmuxRecoveryCandidate.js';
+import { configuredTmuxRecoveryConcurrency, TmuxRecoveryOperationStore } from '../utils/tmuxRecoveryOperations.js';
+import { assessAgentResourceBudget, collectHostResourceSnapshot, configuredAgentResourceBudget } from '../utils/hostResources.js';
 import { AutomationStore, normalizeAutomationSchedule } from '../agent/automationStore.js';
 import { writeBracketedPrompt, canDeliverPromptToAgent } from '../agent/promptDelivery.js';
 import { captureTerminalInputGuard, captureRuntimeInputGuard, waitAndWriteTerminalInput } from '../agent/terminalInput.js';
@@ -204,7 +206,11 @@ const agentResumeHistory = new AgentResumeHistoryStore(`${TERMDOCK_DIR}/agent-re
 const executionArchives = new ExecutionArchiveStore(`${TERMDOCK_DIR}/execution-archives.json`);
 let executionArchiveMutation = Promise.resolve();
 const TMUX_RECOVERY_STATE_FILE = `${TERMDOCK_DIR}/tmux-recovery-state.json`;
+const TMUX_RECOVERY_OPERATIONS_FILE = `${TERMDOCK_DIR}/tmux-recovery-operations.json`;
 const tmuxLifecycle = new TmuxLifecycleCoordinator();
+const tmuxRecoveryConcurrencyLimit = configuredTmuxRecoveryConcurrency();
+const tmuxRecoveryOperations = new TmuxRecoveryOperationStore(TMUX_RECOVERY_OPERATIONS_FILE, tmuxRecoveryConcurrencyLimit, (error) => console.error('[tmux-recovery] operation worker error:', getErrorMessage(error)));
+let tmuxRecoveryHealthTimer = null;
 const intentionallyDeletingTmuxSessions = new Set();
 let tmuxRecoveryState = { lastServerPid: null, incident: null, dismissedSessionIds: [] };
 let persistGlobalStateTimer = null;
@@ -215,6 +221,10 @@ let globalSessionStateReloadTimer = null;
 // receives deltas on every mutation (PUT/DELETE client-state, dead-session
 // reconciliation, etc.). Replaces the 5-second poll on the front-end. ──
 const controlClients = new Map();
+tmuxRecoveryOperations.subscribe(() => {
+    latestSessionInventoryAt = 0;
+    broadcastClientState();
+});
 let latestSessionInventory = null;
 // Only authoritative observations may remove persisted tmux sessions.
 const inventoryTmuxLiveness = new WeakMap();
@@ -543,8 +553,10 @@ async function loadGlobalSessionStateFromDisk() {
 async function loadTmuxRecoveryStateFromDisk() {
     try {
         const data = await readJsonFileIfExists(TMUX_RECOVERY_STATE_FILE);
-        if (!data)
+        if (!data) {
+            await tmuxRecoveryOperations.load();
             return;
+        }
         tmuxRecoveryState = {
             lastServerPid: typeof data.lastServerPid === 'number' && Number.isInteger(data.lastServerPid)
                 ? data.lastServerPid
@@ -554,6 +566,7 @@ async function loadTmuxRecoveryStateFromDisk() {
                 ? data.dismissedSessionIds.filter((id) => typeof id === 'string')
                 : [],
         };
+        await tmuxRecoveryOperations.load();
     }
     catch (error) {
         console.warn('[tmux-recovery] Failed to load recovery state:', getErrorMessage(error));
@@ -666,6 +679,8 @@ const shutdownWithRecordings = async () => {
     if (shuttingDown)
         return;
     shuttingDown = true;
+    if (tmuxRecoveryHealthTimer)
+        clearInterval(tmuxRecoveryHealthTimer);
     flushPersistAndExit();
     void persistToolbarPresetsNow();
     caffeinateManager.shutdown();
@@ -682,6 +697,9 @@ process.on('SIGINT', () => { void shutdownWithRecordings(); });
 // 服务启动时从磁盘加载（带去重，防止历史累积的重复条目复活）
 void (async () => {
     await Promise.all([loadGlobalSessionStateFromDisk(), loadTmuxRecoveryStateFromDisk()]);
+    await sampleTmuxRecoveryHealth();
+    tmuxRecoveryHealthTimer = setInterval(() => void sampleTmuxRecoveryHealth(), 15_000);
+    tmuxRecoveryHealthTimer.unref?.();
     // Delivery needs the loaded inventory, not optional PTY adoption/metadata backfill.
     // Those steps must not leave durable messages without a background scheduler.
     collaborationDeliveryWorker.start();
@@ -694,6 +712,7 @@ void (async () => {
     });
     pruneOrphanSessions();
     await backfillPersistedTmuxMetadata();
+    await tmuxRecoveryOperations.resumePending();
 })();
 caffeinateManager.startNetworkMonitor();
 // 清理磁盘恢复后后端已不存在的 session 引用。
@@ -3009,8 +3028,21 @@ async function getTmuxServerPid() {
 }
 function getTmuxRecoveryView() {
     const incident = tmuxRecoveryState.incident;
-    if (!incident)
-        return null;
+    const latestOperation = tmuxRecoveryOperations.latest();
+    if (!incident) {
+        if (!latestOperation || ['succeeded', 'partial_failure'].includes(latestOperation.state))
+            return null;
+        const sessions = latestOperation.items.flatMap(item => {
+            const record = globalSessionState.sessions.find(candidate => candidate.sessionId === item.sessionId);
+            const agent = record?.agentResume ? agentBySlug(record.agentResume.slug) : null;
+            if (!record?.tmuxSessionName || !record.cwd || !agent || !record.agentResume?.sessionId)
+                return [];
+            return [{ sessionId: record.sessionId, name: record.name, tmuxSessionName: record.tmuxSessionName,
+                    cwd: record.cwd, agentSlug: agent.slug, agentDisplayName: agent.displayName }];
+        });
+        return { id: latestOperation.incidentId, detectedAt: latestOperation.createdAt, operation: latestOperation, sessions };
+    }
+    const operation = latestOperation?.incidentId === incident.id ? latestOperation : null;
     const affected = new Set(incident.affectedSessionIds);
     const sessions = globalSessionState.sessions.flatMap((record) => {
         if (!affected.has(record.sessionId) || record.mode !== 'tmux' || !record.tmuxSessionName
@@ -3029,7 +3061,7 @@ function getTmuxRecoveryView() {
             }];
     });
     return sessions.length > 0
-        ? { id: incident.id, detectedAt: incident.detectedAt, sessions }
+        ? { id: incident.id, detectedAt: incident.detectedAt, operation, sessions }
         : null;
 }
 async function observeTmuxServerGeneration(liveTmuxSessions) {
@@ -5938,7 +5970,7 @@ async function resolveShellIntegrationDir() {
 /**
  * Inject termdock shell integration via environment variables.
  *
- * This replaces the old injectShellTitleHooks with a full Ghostty-style
+ * This replaces the old injectShellTitleHooks with full shell
  * integration that emits OSC 133 (prompt marks), OSC 2 (title), and OSC 7 (cwd).
  *
  * Works for both shell mode (env passed to PTY spawn) and tmux mode
@@ -5958,7 +5990,7 @@ async function injectShellIntegration(shellPath, baseEnv) {
     }
     if (shellType === 'zsh') {
         // Create a temporary ZDOTDIR that sources user's zshenv/zshrc then
-        // sources our integration script. Same approach as Ghostty.
+        // sources our integration script. This preserves the user shell configuration.
         const zdotdir = '/tmp/termdock-zsh-' + String(process.pid);
         try {
             await fs.promises.mkdir(zdotdir, { recursive: true });
@@ -6122,74 +6154,202 @@ router.get('/tmux/status', async (_req, res) => {
     const status = await getTmuxStatus();
     res.json(status);
 });
-router.post('/tmux/recovery/restore-all', async (_req, res) => {
-    const incident = tmuxRecoveryState.incident;
-    if (!incident)
-        return res.status(404).json({ error: 'no tmux recovery is pending' });
-    const outcomes = [];
-    for (const frontendSessionId of incident.affectedSessionIds) {
-        const record = globalSessionState.sessions.find((session) => session.sessionId === frontendSessionId);
-        if (!record || record.mode !== 'tmux' || !record.tmuxSessionName || !record.cwd
-            || !record.agentResume?.sessionId) {
-            outcomes.push({ sessionId: frontendSessionId, restored: false, error: 'recovery metadata is incomplete' });
-            continue;
-        }
-        const agent = agentBySlug(record.agentResume.slug);
-        const command = agent
-            ? buildResumeCommand(agent, record.agentResume.sessionId, record.agentResume.launchArgv)
-            : null;
-        if (!agent || !command) {
-            outcomes.push({ sessionId: frontendSessionId, restored: false, error: 'Agent does not support resume' });
-            continue;
-        }
-        const target = {
-            slug: agent.slug,
-            nativeSessionId: record.agentResume.sessionId,
-            command,
-        };
-        const activeBackend = findActiveAgentResumeOwner('', target);
-        const activeWriterPid = activeBackend ? null : await findExternalCodexWriter(target);
-        if (activeBackend || activeWriterPid) {
-            outcomes.push({ sessionId: frontendSessionId, restored: true });
-            continue;
+async function restoreTmuxRecoverySession(operationId, frontendSessionId, reportPhase) {
+    const record = globalSessionState.sessions.find((session) => session.sessionId === frontendSessionId);
+    if (!record || record.mode !== 'tmux' || !record.tmuxSessionName || !record.cwd || !record.agentResume?.sessionId) {
+        throw Object.assign(new Error('Recovery metadata is incomplete'), { code: 'RECOVERY_METADATA_INCOMPLETE' });
+    }
+    const agent = agentBySlug(record.agentResume.slug);
+    const command = agent ? buildResumeCommand(agent, record.agentResume.sessionId, record.agentResume.launchArgv) : null;
+    if (!agent || !command)
+        throw Object.assign(new Error('Agent does not support exact resume'), { code: 'EXACT_RESUME_UNSUPPORTED' });
+    const target = { slug: agent.slug, nativeSessionId: record.agentResume.sessionId, command };
+    const activeBackend = findActiveAgentResumeOwner('', target);
+    const activeWriterPid = activeBackend ? null : await findExternalCodexWriter(target);
+    if (activeBackend || activeWriterPid)
+        return {};
+    await collaborationDeliveryWorker.reconfigure(frontendSessionId, () => tmuxLifecycle.run(`restore:${record.tmuxSessionName}`, async () => {
+        // Reconcile ownership again inside the per-terminal serialization fence.
+        if (findActiveAgentResumeOwner('', target) || await findExternalCodexWriter(target))
+            return;
+        reportPhase('runtime_resolving');
+        await prepareManagedTmuxSessionUnlocked(record.tmuxSessionName, record.cwd);
+        const metadata = await resolveLiveTmuxMetadata(record.tmuxSessionName);
+        const foreground = metadata?.program?.toLowerCase() ?? null;
+        if (foreground && !shellNamesBackend.has(foreground)) {
+            throw Object.assign(new Error(`pane is busy with ${foreground}`), { code: 'RECOVERY_TARGET_BUSY' });
         }
+        const previous = collaborationRouting.get(frontendSessionId);
+        if (previous)
+            collaborationRouting.bind({ ...previous, pane: null });
+        reportPhase('guard_captured');
+        const launchGuard = await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
         try {
-            await collaborationDeliveryWorker.reconfigure(frontendSessionId, () => tmuxLifecycle.run(`restore:${record.tmuxSessionName}`, async () => {
-                await prepareManagedTmuxSessionUnlocked(record.tmuxSessionName, record.cwd);
-                const metadata = await resolveLiveTmuxMetadata(record.tmuxSessionName);
-                const foreground = metadata?.program?.toLowerCase() ?? null;
-                if (foreground && !shellNamesBackend.has(foreground)) {
-                    throw new Error(`pane is busy with ${foreground}`);
-                }
-                // Explicit recovery may replace the vanished tmux pane. A pending
-                // message alone must never replace that binding.
-                const previous = collaborationRouting.get(frontendSessionId);
-                if (previous)
-                    collaborationRouting.bind({ ...previous, pane: null });
-                const launchGuard = await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
-                await writeAutomaticTerminalPrompt(frontendSessionId, command, undefined, launchGuard);
-            }));
-            outcomes.push({ sessionId: frontendSessionId, restored: true });
+            reportPhase('paste_submit');
+            await writeAutomaticTerminalPrompt(frontendSessionId, command, stage => reportPhase(stage), launchGuard);
         }
         catch (error) {
-            outcomes.push({ sessionId: frontendSessionId, restored: false, error: getErrorMessage(error) });
+            const message = getErrorMessage(error);
+            const reportedCode = error?.code;
+            const code = reportedCode === 'TERMINAL_INPUT_TARGET_CHANGED' || message.includes('TERMINAL_INPUT_TARGET_CHANGED')
+                ? 'TERMINAL_INPUT_TARGET_CHANGED' : 'RECOVERY_LAUNCH_FAILED';
+            throw Object.assign(new Error(message), { code, operationId, sessionId: frontendSessionId });
         }
+    }));
+    const incident = tmuxRecoveryState.incident;
+    if (incident?.affectedSessionIds.includes(frontendSessionId)) {
+        const remaining = incident.affectedSessionIds.filter(id => id !== frontendSessionId);
+        tmuxRecoveryState.incident = remaining.length ? { ...incident, affectedSessionIds: remaining } : null;
+        await persistTmuxRecoveryState();
     }
-    const restoredIds = new Set(outcomes.filter((outcome) => outcome.restored).map((outcome) => outcome.sessionId));
-    const remaining = incident.affectedSessionIds.filter((sessionId) => !restoredIds.has(sessionId));
-    tmuxRecoveryState.incident = remaining.length > 0
-        ? { ...incident, affectedSessionIds: remaining }
-        : null;
-    await persistTmuxRecoveryState();
-    latestSessionInventoryAt = 0;
-    broadcastClientState();
-    res.status(remaining.length > 0 ? 207 : 200).json({
-        restored: restoredIds.size,
-        failed: remaining.length,
-        outcomes,
+    const paneTty = await runTmux(['display-message', '-p', '-t', record.tmuxSessionName, '#{pane_tty}']).catch(() => '');
+    const normalizedTty = paneTty.trim().replace(/^\/dev\//, '');
+    if (normalizedTty) {
+        const resources = await collectHostResourceSnapshot();
+        const rows = resources.processRows.filter(row => row.tty === normalizedTty);
+        if (rows.some(row => row.agent))
+            return { actualRssBytes: rows.reduce((sum, row) => sum + row.rssBytes, 0) };
+    }
+    return {};
+}
+async function resolveTmuxRecoveryScope(scope, incident) {
+    const candidates = incident.affectedSessionIds;
+    if (scope.kind === 'incident')
+        return candidates;
+    if (scope.kind === 'sessions') {
+        if (!Array.isArray(scope.sessionIds) || scope.sessionIds.length === 0)
+            throw Object.assign(new Error('sessionIds must be a non-empty array'), { code: 'INVALID_RECOVERY_SCOPE' });
+        if (scope.sessionIds.some(id => !candidates.includes(id)))
+            throw Object.assign(new Error('Explicit scope may only include sessions in the current recovery incident'), { code: 'RECOVERY_SCOPE_OUTSIDE_INCIDENT' });
+        return [...new Set(scope.sessionIds)];
+    }
+    if (!scope.id)
+        throw Object.assign(new Error('scope id is required'), { code: 'INVALID_RECOVERY_SCOPE' });
+    if (scope.kind === 'group') {
+        const group = collaborationStore.getGroup(scope.id);
+        if (!group || group.deleted)
+            throw Object.assign(new Error('Collaboration group was not found'), { code: 'RECOVERY_GROUP_NOT_FOUND' });
+        return candidates.filter(id => group.sessionIds.includes(id));
+    }
+    const integrationRoot = `${TERMDOCK_DIR}/integration-state`;
+    const portDirectories = await fs.promises.readdir(integrationRoot, { withFileTypes: true }).catch(() => []);
+    const memberIds = new Set();
+    for (const directory of portDirectories.filter(item => item.isDirectory())) {
+        const state = await readJsonFileIfExists(path.join(integrationRoot, directory.name, 'integration-sessions.json'));
+        for (const item of state?.sessions ?? [])
+            if (item.principal_id === scope.id && typeof item.session_id === 'string')
+                memberIds.add(item.session_id);
+    }
+    return candidates.filter(id => memberIds.has(id));
+}
+tmuxRecoveryOperations.setRunner(restoreTmuxRecoverySession);
+const tmuxAgentResourceBudget = configuredAgentResourceBudget();
+tmuxRecoveryOperations.setAdmission(async (_operationId, sessionId) => {
+    try {
+        const snapshot = await collectHostResourceSnapshot();
+        const group = collaborationStore.list().find(item => item.sessionIds.includes(sessionId));
+        let residentAgentsInGroup = 0;
+        if (group) {
+            const rows = globalSessionState.sessions.filter(item => group.sessionIds.includes(item.sessionId) && item.agentResume && item.tmuxSessionName);
+            const liveSessions = await listLiveTmuxInventorySessions();
+            const liveAgents = new Set(liveSessions.filter(item => item.program && agentBySlug(item.program) !== null).map(item => item.name));
+            residentAgentsInGroup = rows.filter(item => liveAgents.has(item.tmuxSessionName)).length;
+            const memberIds = new Set(group.sessionIds);
+            residentAgentsInGroup += tmuxRecoveryOperations.all().flatMap(operation => operation.items)
+                .filter(item => item.state === 'running' && memberIds.has(item.sessionId)).length;
+        }
+        const result = assessAgentResourceBudget({ snapshot: { ...snapshot, residentAgentCount: snapshot.residentAgentCount + tmuxRecoveryOperations.stats().activeLaunches }, budget: tmuxAgentResourceBudget, residentAgentsInGroup });
+        return { ...result, memAvailableBytes: snapshot.memoryAvailableBytes, estimatedRssBytes: tmuxAgentResourceBudget.estimatedRssBytes };
+    }
+    catch {
+        return { admitted: false, reason: 'RESOURCE_SNAPSHOT_UNAVAILABLE', estimatedRssBytes: tmuxAgentResourceBudget.estimatedRssBytes };
+    }
+});
+const TMUX_RECOVERY_HEALTH_FILE = `${TERMDOCK_DIR}/tmux-recovery-health.json`;
+let latestTmuxRecoveryHealth = null;
+let tmuxRecoveryHealthSampling = false;
+async function sampleTmuxRecoveryHealth() {
+    if (tmuxRecoveryHealthSampling)
+        return;
+    tmuxRecoveryHealthSampling = true;
+    try {
+        const snapshot = await collectHostResourceSnapshot();
+        const diagnostics = {
+            sampledAt: snapshot.sampledAt,
+            platform: snapshot.platform,
+            memoryAvailableBytes: snapshot.memoryAvailableBytes,
+            memoryTotalBytes: snapshot.memoryTotalBytes,
+            memorySnapshotAvailable: snapshot.memorySnapshotAvailable,
+            processSnapshotAvailable: snapshot.processSnapshotAvailable,
+            memoryPressure: snapshot.memoryPressure,
+            kswapd: snapshot.kswapd,
+            dStateProcessCount: snapshot.dStateProcessCount,
+            residentAgentCount: snapshot.residentAgentCount,
+            residentAgentRssBytes: snapshot.residentAgentRssBytes,
+            browserProcessCount: snapshot.browserProcessCount,
+            recovery: tmuxRecoveryOperations.stats(),
+            resourceBudget: tmuxAgentResourceBudget,
+        };
+        latestTmuxRecoveryHealth = diagnostics;
+        const temporaryPath = `${TMUX_RECOVERY_HEALTH_FILE}.${process.pid}.tmp`;
+        await fs.promises.writeFile(temporaryPath, JSON.stringify(diagnostics, null, 2), { mode: 0o600 });
+        await fs.promises.rename(temporaryPath, TMUX_RECOVERY_HEALTH_FILE);
+    }
+    catch (error) {
+        console.warn('[tmux-recovery] resource health sample failed:', getErrorMessage(error));
+    }
+    finally {
+        tmuxRecoveryHealthSampling = false;
+    }
+}
+router.get('/tmux/recovery/diagnostics', async (_req, res) => {
+    await sampleTmuxRecoveryHealth();
+    return res.json({ health: latestTmuxRecoveryHealth, operation: tmuxRecoveryOperations.latest(), concurrencyLimit: tmuxRecoveryConcurrencyLimit });
+});
+router.post('/tmux/recovery/restore-all', async (req, res) => {
+    const incident = tmuxRecoveryState.incident;
+    if (!incident)
+        return res.status(404).json({ error: 'no tmux recovery is pending' });
+    const rawScope = req.body?.scope;
+    let scope = { kind: 'incident' };
+    if (rawScope !== undefined) {
+        if (!rawScope || !['incident', 'group', 'principal', 'sessions'].includes(rawScope.kind))
+            return res.status(400).json({ error: 'invalid recovery scope' });
+        scope = rawScope;
+    }
+    const sessionIds = await resolveTmuxRecoveryScope(scope, incident).catch(error => {
+        res.status(400).json({ error: getErrorMessage(error), code: error.code ?? 'INVALID_RECOVERY_SCOPE' });
+        return null;
     });
+    if (!sessionIds)
+        return;
+    try {
+        const operation = await tmuxRecoveryOperations.create({ incidentId: incident.id, sessionIds, scope,
+            idempotencyKey: String(req.body?.idempotencyKey ?? req.headers['idempotency-key'] ?? ''),
+            ...(req.body?.concurrency !== undefined ? { concurrency: Number(req.body.concurrency) } : {}) });
+        res.status(202).json({ accepted: true, operation_id: operation.id, operation: tmuxRecoveryOperations.get(operation.id) });
+    }
+    catch (error) {
+        res.status(409).json({ error: getErrorMessage(error), code: error.code ?? 'RECOVERY_OPERATION_FAILED', operation_id: error.operationId });
+    }
+});
+router.get('/tmux/recovery/operations', (_req, res) => res.json({ operations: tmuxRecoveryOperations.all().slice(-50) }));
+router.get('/tmux/recovery/operations/:id', (req, res) => {
+    const operation = tmuxRecoveryOperations.get(req.params.id);
+    return operation ? res.json({ operation }) : res.status(404).json({ error: 'recovery operation not found' });
+});
+router.post('/tmux/recovery/operations/:id/pause', async (req, res) => {
+    const operation = await tmuxRecoveryOperations.pause(req.params.id);
+    return operation ? res.json({ operation }) : res.status(404).json({ error: 'recovery operation not found' });
+});
+router.post('/tmux/recovery/operations/:id/resume', async (req, res) => {
+    const operation = await tmuxRecoveryOperations.resume(req.params.id);
+    return operation ? res.json({ operation }) : res.status(404).json({ error: 'recovery operation not found' });
 });
 router.delete('/tmux/recovery', async (_req, res) => {
+    if (tmuxRecoveryOperations.all().some(operation => !['succeeded', 'partial_failure'].includes(operation.state))) {
+        return res.status(409).json({ error: 'a recovery operation is active; pause or finish it before dismissing the incident', code: 'RECOVERY_OPERATION_ACTIVE' });
+    }
     tmuxRecoveryState.dismissedSessionIds = Array.from(new Set([
         ...tmuxRecoveryState.dismissedSessionIds,
         ...(tmuxRecoveryState.incident?.affectedSessionIds ?? []),

package/dist/server/utils/hostResources.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { detectAgentFromCommand } from '../agent/registry.js';
+const execFileAsync = promisify(execFile);
+function parseMemAvailable(contents) {
+    const match = contents.match(/^MemAvailable:\s+(\d+)\s+kB$/m);
+    return match ? Number(match[1]) * 1024 : null;
+}
+function parsePressure(contents) {
+    const parse = (kind) => {
+        const line = contents.split('\n').find(item => item.startsWith(`${kind} `));
+        const value = line?.match(/\bavg10=([\d.]+)/)?.[1];
+        return value === undefined ? null : Number(value);
+    };
+    const someAvg10 = parse('some');
+    const fullAvg10 = parse('full');
+    return someAvg10 === null && fullAvg10 === null ? null : { someAvg10, fullAvg10 };
+}
+function parseProcesses(contents, customCommands = {}) {
+    return contents.split('\n').flatMap(line => {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\d+)\s+(.*)$/);
+        if (!match)
+            return [];
+        const [, pidRaw, pgidRaw, state, ttyRaw, rssRaw, commandRaw] = match;
+        const pid = Number(pidRaw), processGroupId = Number(pgidRaw), rssKb = Number(rssRaw);
+        if (!Number.isSafeInteger(pid) || pid <= 0 || !Number.isSafeInteger(processGroupId) || processGroupId <= 0 || !Number.isFinite(rssKb))
+            return [];
+        const command = commandRaw ?? '';
+        const comm = (command.split(/\s+/, 1)[0] ?? '').toLowerCase().split('/').at(-1) ?? '';
+        return [{
+                pid, processGroupId, state: state ?? '?', tty: ttyRaw === '?' ? '' : ttyRaw, command,
+                rssBytes: Math.max(0, rssKb) * 1024,
+                agent: Boolean(detectAgentFromCommand(command, customCommands)),
+                browser: /^(chrome|chromium|firefox|webkit|agent-browser)(-|$)/.test(comm),
+                kswapd: /^\[?kswapd\d*\]?$/.test(comm),
+            }];
+    });
+}
+export async function collectHostResourceSnapshot(customCommands = {}) {
+    let memoryAvailableBytes = os.freemem();
+    let memorySnapshotAvailable = false;
+    let memoryPressure = null;
+    if (process.platform === 'linux') {
+        const [meminfo, pressure] = await Promise.all([
+            fs.readFile('/proc/meminfo', 'utf8').catch(() => ''),
+            fs.readFile('/proc/pressure/memory', 'utf8').catch(() => ''),
+        ]);
+        const parsedAvailable = parseMemAvailable(meminfo);
+        if (parsedAvailable !== null) {
+            memoryAvailableBytes = parsedAvailable;
+            memorySnapshotAvailable = true;
+        }
+        memoryPressure = parsePressure(pressure);
+    }
+    else {
+        memorySnapshotAvailable = Number.isFinite(memoryAvailableBytes);
+    }
+    let processRows = [];
+    let processSnapshotAvailable = false;
+    try {
+        const { stdout } = await execFileAsync('ps', ['-e', '-o', 'pid=,pgid=,stat=,tty=,rss=,args='], { timeout: 5000, maxBuffer: 8 * 1024 * 1024 });
+        processRows = parseProcesses(stdout, customCommands);
+        processSnapshotAvailable = processRows.length > 0;
+    }
+    catch { /* process metrics are diagnostic; memory admission remains fail-closed below */ }
+    const groupRss = new Map();
+    const agentGroupIds = new Set();
+    for (const row of processRows) {
+        groupRss.set(row.processGroupId, (groupRss.get(row.processGroupId) ?? 0) + row.rssBytes);
+        if (row.agent)
+            agentGroupIds.add(row.processGroupId);
+    }
+    const agentRss = [...agentGroupIds].reduce((sum, id) => sum + (groupRss.get(id) ?? 0), 0);
+    return {
+        sampledAt: Date.now(), platform: process.platform, memoryAvailableBytes, memoryTotalBytes: os.totalmem(), memoryPressure,
+        dStateProcessCount: processRows.filter(row => row.state.includes('D')).length,
+        kswapd: processRows.filter(row => row.kswapd).map(({ pid, state }) => ({ pid, state })),
+        residentAgentCount: agentGroupIds.size,
+        residentAgentRssBytes: agentRss,
+        browserProcessCount: processRows.filter(row => row.browser).length,
+        memorySnapshotAvailable,
+        processSnapshotAvailable,
+        processRows,
+    };
+}
+export function configuredAgentResourceBudget(env = process.env) {
+    const readMb = (key, fallback, min, max) => {
+        const raw = env[key];
+        if (raw === undefined || raw.trim() === '')
+            return fallback * 1024 ** 2;
+        const value = Number(raw);
+        if (!Number.isInteger(value) || value < min || value > max)
+            throw new Error(`${key} must be an integer from ${min} to ${max} MiB`);
+        return value * 1024 ** 2;
+    };
+    const readCount = (key, fallback, max) => {
+        const raw = env[key];
+        if (raw === undefined || raw.trim() === '')
+            return fallback;
+        const value = Number(raw);
+        if (!Number.isInteger(value) || value < 1 || value > max)
+            throw new Error(`${key} must be an integer from 1 to ${max}`);
+        return value;
+    };
+    return {
+        minAvailableBytes: readMb('TD_AGENT_MIN_AVAILABLE_MB', 2048, 256, 131072),
+        estimatedRssBytes: readMb('TD_AGENT_ESTIMATED_RSS_MB', 512, 64, 32768),
+        maxResidentAgents: readCount('TD_MAX_RESIDENT_AGENTS', 48, 10000),
+        maxAgentsPerGroup: readCount('TD_MAX_AGENTS_PER_GROUP', 32, 1000),
+    };
+}
+export function assessAgentResourceBudget(input) {
+    if (input.snapshot.memorySnapshotAvailable === false || input.snapshot.processSnapshotAvailable === false)
+        return { admitted: false, reason: 'RESOURCE_SNAPSHOT_UNAVAILABLE' };
+    const required = input.budget.minAvailableBytes + input.budget.estimatedRssBytes;
+    if (input.snapshot.memoryAvailableBytes < required)
+        return { admitted: false, reason: 'MEMORY_BUDGET_LOW' };
+    if (input.snapshot.residentAgentCount >= input.budget.maxResidentAgents)
+        return { admitted: false, reason: 'MAX_RESIDENT_AGENTS' };
+    if (input.residentAgentsInGroup >= input.budget.maxAgentsPerGroup)
+        return { admitted: false, reason: 'MAX_GROUP_AGENTS' };
+    return { admitted: true };
+}
+export function parseHostResourcesForTest(contents) {
+    return { memAvailableBytes: parseMemAvailable(contents.meminfo), pressure: parsePressure(contents.pressure), processes: parseProcesses(contents.ps) };
+}