@xenosystem/agent-interface-host 0.1.3

package/dist/subagents/SubagentRunService.js

@@ -0,0 +1,1183 @@
+import { closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { matchSubagentCapabilities } from './capabilityMatcher.js';
+const ACTIVE_STATUSES = new Set([
+    'queued',
+    'launch-requested',
+    'running',
+    'waiting-for-permission',
+    'waiting-for-user',
+]);
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const MAX_STORED_RUNS = 5000;
+const DEFAULT_LEASE_MS = 120_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_RUN_TIMEOUT_MS = 60 * 60_000;
+const DEFAULT_STALE_HEARTBEAT_MS = 5 * 60_000;
+const VALID_EXPECTED_ARTIFACT_TYPES = new Set(['answer', 'file', 'diff', 'diagnostic', 'report']);
+const LOCAL_CLI_APP_SERVER_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+const LEGAL_STATUS_TRANSITIONS = {
+    queued: new Set(['queued', 'launch-requested', 'running', 'waiting-for-permission', 'waiting-for-user', 'failed', 'cancelled']),
+    'launch-requested': new Set(['queued', 'launch-requested', 'running', 'waiting-for-permission', 'waiting-for-user', 'failed', 'cancelled']),
+    running: new Set(['queued', 'launch-requested', 'running', 'waiting-for-permission', 'waiting-for-user', 'completed', 'failed', 'cancelled']),
+    'waiting-for-permission': new Set(['queued', 'launch-requested', 'waiting-for-permission', 'running', 'waiting-for-user', 'failed', 'cancelled']),
+    'waiting-for-user': new Set(['queued', 'launch-requested', 'waiting-for-user', 'running', 'waiting-for-permission', 'failed', 'cancelled']),
+    completed: new Set(['completed']),
+    failed: new Set(['failed']),
+    cancelled: new Set(['cancelled']),
+};
+function readRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function requiredString(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${label} is required.`);
+    return value.trim();
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function optionalEnvKey(value) {
+    const key = optionalString(value)?.slice(0, 128);
+    if (key && /^(sk|xox[baprs]|gh[pousr])_[A-Za-z0-9_=-]{8,}$/i.test(key))
+        return undefined;
+    return key && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) ? key : undefined;
+}
+function normalizeCliEndpoint(value) {
+    const raw = optionalString(value);
+    if (!raw)
+        return undefined;
+    try {
+        const url = new URL(raw.slice(0, 500));
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        const host = url.hostname.toLowerCase();
+        if (!LOCAL_CLI_APP_SERVER_HOSTS.has(host) && !host.endsWith('.localhost'))
+            return undefined;
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        url.hash = '';
+        return url.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            continue;
+        const trimmed = entry.trim();
+        const key = trimmed.toLowerCase();
+        if (!trimmed || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(trimmed);
+    }
+    return out;
+}
+function normalizeCapabilityMatch(value) {
+    const score = typeof value?.score === 'number' && Number.isFinite(value.score)
+        ? Math.max(0, Math.min(1, value.score))
+        : 0.5;
+    return {
+        score,
+        reasons: normalizeStringArray(value?.reasons),
+        missingCapabilities: normalizeStringArray(value?.missingCapabilities),
+    };
+}
+function normalizeToolPolicy(value) {
+    const permissionMode = value?.permissionMode === 'ask-parent'
+        || value?.permissionMode === 'ask-user'
+        || value?.permissionMode === 'deny'
+        || value?.permissionMode === 'inherit-parent'
+        ? value.permissionMode
+        : 'inherit-parent';
+    return {
+        allowedTools: normalizeStringArray(value?.allowedTools),
+        allowedDirectories: normalizeStringArray(value?.allowedDirectories),
+        allowedApps: normalizeStringArray(value?.allowedApps),
+        permissionMode,
+    };
+}
+function normalizePositiveNumber(value, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    const normalized = Math.floor(value);
+    return normalized > 0 ? Math.min(normalized, max) : undefined;
+}
+function normalizeBudget(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const budget = {
+        maxTokens: normalizePositiveNumber(value.maxTokens, 10_000_000),
+        maxCredits: normalizePositiveNumber(value.maxCredits, 10_000_000),
+        estimatedTokens: normalizePositiveNumber(value.estimatedTokens, 10_000_000),
+        estimatedCredits: normalizePositiveNumber(value.estimatedCredits, 10_000_000),
+        spentTokens: normalizePositiveNumber(value.spentTokens, 10_000_000),
+        spentCredits: normalizePositiveNumber(value.spentCredits, 10_000_000),
+    };
+    return Object.values(budget).some((entry) => entry !== undefined) ? budget : undefined;
+}
+function normalizeExpectedArtifacts(value) {
+    if (!Array.isArray(value))
+        return ['answer'];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            continue;
+        const normalized = entry.trim();
+        if (!VALID_EXPECTED_ARTIFACT_TYPES.has(normalized) || out.includes(normalized))
+            continue;
+        out.push(normalized);
+    }
+    return out.length ? out.slice(0, 20) : ['answer'];
+}
+function normalizeRuntimeSelectionMetadata(value) {
+    const record = readRecord(value);
+    const providerKind = optionalString(record.providerKind);
+    if (providerKind !== 'sdk-native'
+        && providerKind !== 'cli-app-server'
+        && providerKind !== 'cli-remote'
+        && providerKind !== 'acp-provider')
+        return undefined;
+    const providerId = optionalString(record.providerId) || providerKind;
+    const cliEndpoint = providerKind === 'cli-app-server' ? normalizeCliEndpoint(record.cliAppServerEndpoint) : undefined;
+    return {
+        providerKind,
+        providerId,
+        ...(providerKind === 'acp-provider' && optionalString(record.acpAgentConfigId) ? { acpAgentConfigId: optionalString(record.acpAgentConfigId) } : {}),
+        ...(cliEndpoint ? { cliAppServerEndpoint: cliEndpoint } : {}),
+        ...(cliEndpoint && optionalEnvKey(record.cliAppServerTokenEnvKey) ? { cliAppServerTokenEnvKey: optionalEnvKey(record.cliAppServerTokenEnvKey) } : {}),
+        ...(providerKind === 'cli-remote' && optionalString(record.remoteBackendId) ? { remoteBackendId: optionalString(record.remoteBackendId) } : {}),
+    };
+}
+function normalizeDelegationPolicy(value) {
+    const record = readRecord(value);
+    return {
+        maxTokens: normalizePositiveNumber(record.maxTokens, 10_000_000),
+        maxCredits: normalizePositiveNumber(record.maxCredits, 10_000_000),
+        maxRuntimeMs: normalizePositiveNumber(record.maxRuntimeMs, 24 * 60 * 60_000),
+        maxConcurrentChildRuns: normalizePositiveNumber(record.maxConcurrentChildRuns, 20),
+        maxChildDepth: normalizePositiveNumber(record.maxChildDepth, 10),
+        allowFurtherDelegation: record.allowFurtherDelegation === true,
+        cancellationPropagation: record.cancellationPropagation !== false,
+    };
+}
+function normalizeDelegation(value, run, now) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = readRecord(value);
+    const depth = normalizePositiveNumber(record.depth, 10) || 1;
+    return {
+        routerVersion: 1,
+        routedAt: typeof record.routedAt === 'number' && Number.isFinite(record.routedAt) ? record.routedAt : now,
+        parentConversationId: optionalString(record.parentConversationId) || run.parentConversationId,
+        parentRequestId: optionalString(record.parentRequestId) || run.parentRequestId,
+        parentAgentId: optionalString(record.parentAgentId) || run.parentAgentId,
+        targetAgentId: optionalString(record.targetAgentId) || run.childAgentId,
+        workspaceId: optionalString(record.workspaceId) || run.workspaceId,
+        teamId: optionalString(record.teamId) || run.teamId,
+        contextAttachmentIds: normalizeStringArray(record.contextAttachmentIds).slice(0, 100),
+        expectedArtifacts: normalizeExpectedArtifacts(record.expectedArtifacts),
+        targetRuntimeSelection: normalizeRuntimeSelectionMetadata(record.targetRuntimeSelection),
+        policy: normalizeDelegationPolicy(record.policy),
+        depth,
+    };
+}
+function assertBudgetAllowsQueue(budget) {
+    if (!budget)
+        return;
+    if (budget.maxTokens !== undefined && budget.estimatedTokens !== undefined && budget.estimatedTokens > budget.maxTokens) {
+        throw new Error(`Subagent budget denied: estimated ${budget.estimatedTokens} tokens exceeds ${budget.maxTokens} token limit.`);
+    }
+    if (budget.maxCredits !== undefined && budget.estimatedCredits !== undefined && budget.estimatedCredits > budget.maxCredits) {
+        throw new Error(`Subagent budget denied: estimated ${budget.estimatedCredits} credits exceeds ${budget.maxCredits} credit limit.`);
+    }
+}
+function assertCapabilitiesAllowQueue(match, requiredCapabilities) {
+    const missing = new Set(match.missingCapabilities);
+    for (const capability of requiredCapabilities) {
+        if (missing.has(capability)) {
+            throw new Error(`Subagent capability denied: missing required capability "${capability}".`);
+        }
+    }
+    if (match.missingCapabilities.length > 0 && match.score < 0.5) {
+        throw new Error(`Subagent capability denied: missing ${match.missingCapabilities.join(', ')}.`);
+    }
+}
+function normalizePriority(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : 0;
+    return Math.max(-100, Math.min(100, numeric));
+}
+function normalizeMaxConcurrentRuns(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : 1;
+    return Math.max(1, Math.min(20, numeric));
+}
+function nextQueueOrdinal(runs) {
+    return runs.reduce((max, run) => Math.max(max, run.queue?.slotOrdinal || 0), 0) + 1;
+}
+function normalizeQueue(value, run, slotOrdinal) {
+    const slotKey = optionalString(value?.slotKey) || `${run.workspaceId}:${run.teamId}:${run.childAgentId}`;
+    return {
+        queuedAt: run.createdAt,
+        priority: normalizePriority(value?.priority),
+        slotKey,
+        slotOrdinal,
+        maxConcurrentRuns: normalizeMaxConcurrentRuns(value?.maxConcurrentRuns),
+    };
+}
+function normalizeCancellation(request, run, now) {
+    const requestedPropagation = request.propagateToChild !== false;
+    const propagateToChild = requestedPropagation && (!!run.childRequestId || run.status === 'launch-requested' || run.status === 'running');
+    const requestedFrom = request.requestedFrom === 'parent'
+        || request.requestedFrom === 'child'
+        || request.requestedFrom === 'scheduler'
+        || request.requestedFrom === 'user'
+        || request.requestedFrom === 'unknown'
+        ? request.requestedFrom
+        : 'unknown';
+    return {
+        requestedAt: now,
+        requestedBy: optionalString(request.requestedBy),
+        requestedFrom,
+        reason: truncateSummary(request.reason),
+        parentConversationId: run.parentConversationId,
+        parentRequestId: run.parentRequestId,
+        childConversationId: run.childConversationId,
+        childRequestId: run.childRequestId,
+        parentAgentId: run.parentAgentId,
+        childAgentId: run.childAgentId,
+        propagateToChild,
+        propagatedAt: propagateToChild && run.childRequestId ? (request.propagatedAt || now) : undefined,
+        propagationStatus: propagateToChild ? (run.childRequestId ? 'propagated' : 'pending') : 'not-applicable',
+    };
+}
+function normalizeHandoff(value, run, artifact, now) {
+    const record = readRecord(value);
+    const provenance = readRecord(record.provenance);
+    return {
+        subagentRunId: optionalString(record.subagentRunId) || run.id,
+        parentConversationId: optionalString(record.parentConversationId) || run.parentConversationId,
+        childConversationId: optionalString(record.childConversationId) || run.childConversationId,
+        parentAgentId: optionalString(record.parentAgentId) || run.parentAgentId,
+        childAgentId: optionalString(record.childAgentId) || run.childAgentId,
+        parentRequestId: optionalString(record.parentRequestId) || run.parentRequestId,
+        childRequestId: optionalString(record.childRequestId) || run.childRequestId,
+        handedOffAt: typeof record.handedOffAt === 'number' && Number.isFinite(record.handedOffAt) ? record.handedOffAt : now,
+        provenance: {
+            createdByAgentId: optionalString(provenance.createdByAgentId) || run.childAgentId,
+            createdByConversationId: optionalString(provenance.createdByConversationId) || artifact.conversationId || run.childConversationId,
+            createdByRequestId: optionalString(provenance.createdByRequestId) || run.childRequestId,
+            sourcePath: optionalString(provenance.sourcePath) || artifact.path,
+            sourceMessageId: optionalString(provenance.sourceMessageId) || artifact.messageId,
+        },
+    };
+}
+function normalizeRecoveryHistory(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const events = value.flatMap((entry) => {
+        const record = readRecord(entry);
+        const action = record.action === 'requeued' || record.action === 'failed' || record.action === 'cancelled'
+            ? record.action
+            : undefined;
+        const reason = record.reason === 'lease-expired'
+            || record.reason === 'heartbeat-stale'
+            || record.reason === 'timeout'
+            || record.reason === 'manual-cancel'
+            || record.reason === 'scheduler-cancel'
+            ? record.reason
+            : undefined;
+        const at = typeof record.at === 'number' && Number.isFinite(record.at) ? record.at : undefined;
+        if (!action || !reason || at === undefined)
+            return [];
+        return [{
+                at,
+                action,
+                reason,
+                workerId: optionalString(record.workerId),
+                attempt: typeof record.attempt === 'number' && Number.isFinite(record.attempt) ? record.attempt : undefined,
+                detail: optionalString(record.detail),
+            }];
+    });
+    return events.length ? events.slice(-100) : undefined;
+}
+function normalizeRecordMetadata(value) {
+    const record = readRecord(value);
+    return Object.keys(record).length ? record : undefined;
+}
+function normalizeAttemptStatus(value) {
+    if (value === 'launch-requested'
+        || value === 'running'
+        || value === 'completed'
+        || value === 'failed'
+        || value === 'cancelled'
+        || value === 'expired')
+        return value;
+    return undefined;
+}
+function normalizeExecutionAttempts(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const attempts = value.flatMap((entry) => {
+        const record = readRecord(entry);
+        const attempt = typeof record.attempt === 'number' && Number.isFinite(record.attempt)
+            ? Math.max(1, Math.floor(record.attempt))
+            : undefined;
+        const workerId = optionalString(record.workerId);
+        const status = normalizeAttemptStatus(record.status);
+        const launchRequestedAt = typeof record.launchRequestedAt === 'number' && Number.isFinite(record.launchRequestedAt)
+            ? record.launchRequestedAt
+            : undefined;
+        if (!attempt || !workerId || !status || launchRequestedAt === undefined)
+            return [];
+        return [{
+                attempt,
+                workerId,
+                adapterId: optionalString(record.adapterId),
+                adapterVersion: optionalString(record.adapterVersion),
+                adapterCapabilities: normalizeStringArray(record.adapterCapabilities),
+                status,
+                launchRequestedAt,
+                launchRequestExpiresAt: typeof record.launchRequestExpiresAt === 'number' && Number.isFinite(record.launchRequestExpiresAt) ? record.launchRequestExpiresAt : undefined,
+                runningAt: typeof record.runningAt === 'number' && Number.isFinite(record.runningAt) ? record.runningAt : undefined,
+                endedAt: typeof record.endedAt === 'number' && Number.isFinite(record.endedAt) ? record.endedAt : undefined,
+                childRequestId: optionalString(record.childRequestId),
+                error: truncateSummary(optionalString(record.error)),
+                metadata: normalizeRecordMetadata(record.metadata),
+            }];
+    });
+    return attempts.length ? attempts.slice(-100) : undefined;
+}
+function markLatestAttempt(run, status, now, patch = {}) {
+    const attempts = [...(run.executionAttempts || [])];
+    const index = attempts.length - 1;
+    if (index < 0)
+        return run.executionAttempts;
+    const current = attempts[index];
+    attempts[index] = {
+        ...current,
+        ...patch,
+        status,
+        runningAt: status === 'running' ? (current.runningAt || now) : (patch.runningAt ?? current.runningAt),
+        endedAt: status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'expired'
+            ? (current.endedAt || now)
+            : (patch.endedAt ?? current.endedAt),
+    };
+    return attempts.slice(-100);
+}
+function appendRecoveryHistory(run, event) {
+    return [...(run.recoveryHistory || []), event].slice(-100);
+}
+function normalizeArtifact(value, run, now) {
+    const record = readRecord(value);
+    const title = optionalString(record.title);
+    if (!title)
+        return null;
+    const type = record.type === 'file'
+        || record.type === 'diff'
+        || record.type === 'terminal'
+        || record.type === 'browser'
+        || record.type === 'note'
+        || record.type === 'unknown'
+        ? record.type
+        : 'unknown';
+    const artifact = {
+        id: optionalString(record.id) || `artifact-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        type,
+        title,
+        path: optionalString(record.path),
+        conversationId: optionalString(record.conversationId),
+        messageId: optionalString(record.messageId),
+        metadata: readRecord(record.metadata),
+        createdAt: typeof record.createdAt === 'number' && Number.isFinite(record.createdAt) ? record.createdAt : now,
+    };
+    return {
+        ...artifact,
+        handoff: normalizeHandoff(record.handoff, run, artifact, now),
+    };
+}
+function truncateSummary(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > 12000 ? `${trimmed.slice(0, 12000)}\n...[truncated]` : trimmed;
+}
+function clampLeaseMs(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? value : DEFAULT_LEASE_MS;
+    return Math.max(10_000, Math.min(15 * 60_000, Math.floor(numeric)));
+}
+function clampRunTimeoutMs(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? value : DEFAULT_RUN_TIMEOUT_MS;
+    return Math.max(30_000, Math.min(24 * 60 * 60_000, Math.floor(numeric)));
+}
+function clampStaleHeartbeatMs(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? value : DEFAULT_STALE_HEARTBEAT_MS;
+    return Math.max(10_000, Math.min(60 * 60_000, Math.floor(numeric)));
+}
+function activeLeaseExpired(run, now) {
+    return ACTIVE_STATUSES.has(run.status) && typeof run.leaseExpiresAt === 'number' && run.leaseExpiresAt <= now;
+}
+function activeRunTimedOut(run, now, timeoutMs) {
+    return ACTIVE_STATUSES.has(run.status)
+        && run.status !== 'queued'
+        && typeof run.startedAt === 'number'
+        && run.startedAt + timeoutMs <= now;
+}
+function activeHeartbeatStale(run, now, staleHeartbeatMs) {
+    if (!ACTIVE_STATUSES.has(run.status) || run.status !== 'running' || !run.leaseOwner)
+        return false;
+    const heartbeatAt = typeof run.heartbeatAt === 'number' ? run.heartbeatAt : run.startedAt;
+    return typeof heartbeatAt === 'number' && heartbeatAt + staleHeartbeatMs <= now;
+}
+function assertStatusTransition(from, to) {
+    if (LEGAL_STATUS_TRANSITIONS[from]?.has(to))
+        return;
+    throw new Error(`Illegal subagent run status transition: ${from} -> ${to}.`);
+}
+function isSubagentRunStatus(value) {
+    return value === 'queued'
+        || value === 'launch-requested'
+        || value === 'running'
+        || value === 'waiting-for-permission'
+        || value === 'waiting-for-user'
+        || value === 'completed'
+        || value === 'failed'
+        || value === 'cancelled';
+}
+function isPersistedSubagentRun(value) {
+    const run = readRecord(value);
+    return typeof run.id === 'string'
+        && typeof run.parentConversationId === 'string'
+        && typeof run.parentRequestId === 'string'
+        && typeof run.parentAgentId === 'string'
+        && typeof run.childConversationId === 'string'
+        && typeof run.childAgentId === 'string'
+        && typeof run.workspaceId === 'string'
+        && typeof run.teamId === 'string'
+        && typeof run.createdAt === 'number'
+        && typeof run.updatedAt === 'number'
+        && isSubagentRunStatus(run.status)
+        && typeof run.objective === 'string'
+        && Array.isArray(run.artifacts);
+}
+export class SubagentRunService {
+    storePath;
+    /**
+     * ⚠️ The default is the REAL user's home, and a host that runs isolated must not use it.
+     * `readonly` and public so `getSubagentRunService` can refuse a second, conflicting store.
+     */
+    constructor(storePath = join(homedir(), '.xeno', 'subagent-runs.json')) {
+        this.storePath = storePath;
+    }
+    createRun(request) {
+        try {
+            const now = Date.now();
+            const capabilityMatch = normalizeCapabilityMatch(request.capabilityMatch);
+            const requiredCapabilities = normalizeStringArray(request.requiredCapabilities);
+            assertCapabilitiesAllowQueue(capabilityMatch, requiredCapabilities);
+            const budget = normalizeBudget(request.budget);
+            assertBudgetAllowsQueue(budget);
+            const store = this.load();
+            const baseRun = {
+                workspaceId: requiredString(request.workspaceId, 'workspaceId'),
+                teamId: requiredString(request.teamId, 'teamId'),
+                childAgentId: requiredString(request.childAgentId, 'childAgentId'),
+                createdAt: now,
+            };
+            const run = {
+                id: `subrun-${now}-${Math.random().toString(36).slice(2, 9)}`,
+                parentConversationId: requiredString(request.parentConversationId, 'parentConversationId'),
+                parentRequestId: optionalString(request.parentRequestId) || `parent-${now}`,
+                parentAgentId: requiredString(request.parentAgentId, 'parentAgentId'),
+                childConversationId: requiredString(request.childConversationId, 'childConversationId'),
+                childAgentId: baseRun.childAgentId,
+                workspaceId: baseRun.workspaceId,
+                teamId: baseRun.teamId,
+                createdAt: now,
+                updatedAt: now,
+                status: 'queued',
+                objective: requiredString(request.objective, 'objective'),
+                role: optionalString(request.role),
+                // Bounded by the parent before it reaches here. Persisted with the run because the run may
+                // be launched long after the parent turn ended, so re-deriving the bound at launch time
+                // would ask a question whose answer has already gone.
+                workspace: request.workspace ? structuredClone(request.workspace) : undefined,
+                capabilityMatch,
+                toolPolicy: normalizeToolPolicy(request.toolPolicy),
+                parentAgentName: optionalString(request.parentAgentName),
+                childAgentName: optionalString(request.childAgentName),
+                workspaceName: optionalString(request.workspaceName),
+                teamName: optionalString(request.teamName),
+                artifacts: [],
+                ...(budget ? { budget } : {}),
+                queue: normalizeQueue(request.queue, baseRun, nextQueueOrdinal(store.runs)),
+            };
+            const delegation = normalizeDelegation(request.delegation, run, now);
+            if (delegation)
+                run.delegation = delegation;
+            store.runs.unshift(run);
+            store.runs = store.runs.slice(0, MAX_STORED_RUNS);
+            this.save(store);
+            return { success: true, run };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    updateRun(request) {
+        try {
+            const id = requiredString(request.id, 'id');
+            const store = this.load();
+            const index = store.runs.findIndex((run) => run.id === id);
+            if (index < 0)
+                return { success: false, error: 'Subagent run not found.' };
+            const current = store.runs[index];
+            const now = Date.now();
+            const status = request.status || current.status;
+            assertStatusTransition(current.status, status);
+            const workerId = optionalString(request.workerId) || current.leaseOwner || current.launchOwner || 'legacy-renderer';
+            const adapterId = optionalString(request.adapterId) || current.executionAdapterId;
+            const childRequestId = optionalString(request.childRequestId) || current.childRequestId;
+            const artifacts = request.artifacts
+                ? request.artifacts.map((artifact) => normalizeArtifact(artifact, current, now)).filter((artifact) => !!artifact)
+                : current.artifacts;
+            const terminalReason = status === 'completed'
+                ? 'completed'
+                : status === 'cancelled'
+                    ? 'cancelled'
+                    : status === 'failed'
+                        ? (current.terminalReason || 'failed')
+                        : current.terminalReason;
+            const hasAttempts = !!current.executionAttempts?.length;
+            const runningAttempts = status === 'running'
+                ? (hasAttempts
+                    ? markLatestAttempt(current, 'running', request.startedAt || now, { childRequestId, workerId, adapterId })
+                    : [{
+                            attempt: current.attempt || 1,
+                            workerId,
+                            adapterId,
+                            status: 'running',
+                            launchRequestedAt: request.startedAt || now,
+                            runningAt: request.startedAt || now,
+                            childRequestId,
+                            metadata: current.executionMetadata,
+                        }])
+                : current.executionAttempts;
+            const terminalAttempts = TERMINAL_STATUSES.has(status)
+                ? markLatestAttempt({ ...current, executionAttempts: runningAttempts }, status === 'completed' ? 'completed' : status === 'cancelled' ? 'cancelled' : 'failed', request.endedAt || now, { childRequestId, error: truncateSummary(request.error) })
+                : runningAttempts;
+            const updated = {
+                ...current,
+                parentRequestId: optionalString(request.parentRequestId) || current.parentRequestId,
+                childConversationId: optionalString(request.childConversationId) || current.childConversationId,
+                childRequestId,
+                status,
+                startedAt: request.startedAt || current.startedAt || (status === 'running' ? now : undefined),
+                endedAt: request.endedAt || current.endedAt || (TERMINAL_STATUSES.has(status) ? now : undefined),
+                updatedAt: now,
+                summary: truncateSummary(request.summary) ?? current.summary,
+                error: truncateSummary(request.error) ?? current.error,
+                artifacts,
+                tokenUsage: request.tokenUsage || current.tokenUsage,
+                leaseOwner: TERMINAL_STATUSES.has(status) ? undefined : current.leaseOwner,
+                leaseExpiresAt: TERMINAL_STATUSES.has(status) ? undefined : current.leaseExpiresAt,
+                heartbeatAt: TERMINAL_STATUSES.has(status) ? undefined : current.heartbeatAt,
+                launchOwner: TERMINAL_STATUSES.has(status) ? undefined : current.launchOwner,
+                launchRequestExpiresAt: TERMINAL_STATUSES.has(status) ? undefined : current.launchRequestExpiresAt,
+                executionAdapterId: adapterId,
+                executionAttempts: terminalAttempts,
+                attempt: status === 'running' && !current.attempt ? 1 : current.attempt,
+                cancelledAt: status === 'cancelled' ? (current.cancelledAt || now) : current.cancelledAt,
+                terminalReason,
+            };
+            store.runs[index] = updated;
+            this.save(store);
+            return { success: true, run: updated };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    claimNextRun(request) {
+        try {
+            const workerId = requiredString(request.workerId, 'workerId');
+            const now = typeof request.now === 'number' && Number.isFinite(request.now) ? request.now : Date.now();
+            const leaseMs = clampLeaseMs(request.leaseMs);
+            const requestedRunId = optionalString(request.id);
+            const requestedSlotKey = optionalString(request.slotKey);
+            const requestedMaxConcurrentRuns = normalizeMaxConcurrentRuns(request.maxConcurrentRuns);
+            const adapterId = optionalString(request.adapterId) || 'renderer-agent-run';
+            const adapterVersion = optionalString(request.adapterVersion);
+            const adapterCapabilities = normalizeStringArray(request.adapterCapabilities);
+            const executionMetadata = normalizeRecordMetadata(request.executionMetadata);
+            const store = this.load();
+            const orderedCandidates = store.runs
+                .map((run, index) => ({ run, index }))
+                .filter(({ run }) => {
+                if (requestedRunId && run.id !== requestedRunId)
+                    return false;
+                if (request.workspaceId && run.workspaceId !== request.workspaceId)
+                    return false;
+                if (request.teamId && run.teamId !== request.teamId)
+                    return false;
+                if (request.childAgentId && run.childAgentId !== request.childAgentId)
+                    return false;
+                if (requestedSlotKey && (run.queue?.slotKey || `${run.workspaceId}:${run.teamId}:${run.childAgentId}`) !== requestedSlotKey)
+                    return false;
+                if (TERMINAL_STATUSES.has(run.status))
+                    return false;
+                return run.status === 'queued' || activeLeaseExpired(run, now);
+            })
+                .sort((a, b) => {
+                const priorityDelta = (b.run.queue?.priority || 0) - (a.run.queue?.priority || 0);
+                if (priorityDelta !== 0)
+                    return priorityDelta;
+                const ordinalDelta = (a.run.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER) - (b.run.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER);
+                if (ordinalDelta !== 0)
+                    return ordinalDelta;
+                return a.run.createdAt - b.run.createdAt;
+            });
+            const candidateIndex = orderedCandidates
+                .find(({ run }) => {
+                const slotKey = run.queue?.slotKey || `${run.workspaceId}:${run.teamId}:${run.childAgentId}`;
+                const maxConcurrentRuns = run.queue?.maxConcurrentRuns || requestedMaxConcurrentRuns;
+                if (requestedRunId) {
+                    const blocking = store.runs
+                        .filter((queued) => queued.id !== run.id && queued.status === 'queued')
+                        .filter((queued) => (queued.queue?.slotKey || `${queued.workspaceId}:${queued.teamId}:${queued.childAgentId}`) === slotKey)
+                        .sort((a, b) => {
+                        const priorityDelta = (b.queue?.priority || 0) - (a.queue?.priority || 0);
+                        if (priorityDelta !== 0)
+                            return priorityDelta;
+                        const ordinalDelta = (a.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER) - (b.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER);
+                        if (ordinalDelta !== 0)
+                            return ordinalDelta;
+                        return a.createdAt - b.createdAt;
+                    })[0];
+                    if (blocking) {
+                        const priorityDelta = (blocking.queue?.priority || 0) - (run.queue?.priority || 0);
+                        const blockingComesFirst = priorityDelta > 0
+                            || (priorityDelta === 0 && (blocking.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER) < (run.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER))
+                            || (priorityDelta === 0
+                                && (blocking.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER) === (run.queue?.slotOrdinal || Number.MAX_SAFE_INTEGER)
+                                && blocking.createdAt < run.createdAt);
+                        if (blockingComesFirst)
+                            return false;
+                    }
+                }
+                const activeInSlot = store.runs.filter((active) => {
+                    if (active.id === run.id)
+                        return false;
+                    if (active.status !== 'launch-requested' && active.status !== 'running' && active.status !== 'waiting-for-permission' && active.status !== 'waiting-for-user')
+                        return false;
+                    const activeSlotKey = active.queue?.slotKey || `${active.workspaceId}:${active.teamId}:${active.childAgentId}`;
+                    return activeSlotKey === slotKey && !activeLeaseExpired(active, now);
+                }).length;
+                return activeInSlot < maxConcurrentRuns;
+            })?.index;
+            if (candidateIndex === undefined)
+                return { success: true };
+            const current = store.runs[candidateIndex];
+            assertStatusTransition(current.status, 'launch-requested');
+            const expired = activeLeaseExpired(current, now);
+            const nextAttempt = (current.attempt || 0) + 1;
+            const expiredAttempts = expired
+                ? markLatestAttempt(current, 'expired', now, {
+                    error: truncateSummary(`Recovered expired launch lease from ${current.leaseOwner || current.launchOwner || 'unknown worker'}.`),
+                })
+                : current.executionAttempts;
+            const updated = {
+                ...current,
+                status: 'launch-requested',
+                updatedAt: now,
+                leaseOwner: workerId,
+                launchOwner: workerId,
+                launchRequestedAt: now,
+                launchRequestExpiresAt: now + leaseMs,
+                leaseExpiresAt: now + leaseMs,
+                heartbeatAt: now,
+                attempt: nextAttempt,
+                executionAdapterId: adapterId,
+                executionMetadata,
+                executionAttempts: [
+                    ...(expiredAttempts || []),
+                    {
+                        attempt: nextAttempt,
+                        workerId,
+                        adapterId,
+                        adapterVersion,
+                        adapterCapabilities,
+                        status: 'launch-requested',
+                        launchRequestedAt: now,
+                        launchRequestExpiresAt: now + leaseMs,
+                        metadata: executionMetadata,
+                    },
+                ].slice(-100),
+                error: expired
+                    ? truncateSummary(`Recovered expired lease from ${current.leaseOwner || 'unknown worker'}.`)
+                    : current.error,
+            };
+            store.runs[candidateIndex] = updated;
+            this.save(store);
+            return { success: true, run: updated };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    heartbeatRun(request) {
+        try {
+            const id = requiredString(request.id, 'id');
+            const workerId = requiredString(request.workerId, 'workerId');
+            const now = typeof request.now === 'number' && Number.isFinite(request.now) ? request.now : Date.now();
+            const leaseMs = clampLeaseMs(request.leaseMs);
+            const store = this.load();
+            const index = store.runs.findIndex((run) => run.id === id);
+            if (index < 0)
+                return { success: false, error: 'Subagent run not found.' };
+            const current = store.runs[index];
+            if (TERMINAL_STATUSES.has(current.status))
+                return { success: false, error: 'Subagent run is already terminal.' };
+            if (activeLeaseExpired(current, now))
+                return { success: false, error: 'Subagent run lease has expired.' };
+            if (current.leaseOwner && current.leaseOwner !== workerId)
+                return { success: false, error: 'Subagent run is leased by another worker.' };
+            const status = current.status === 'queued' || current.status === 'launch-requested' ? 'running' : current.status;
+            assertStatusTransition(current.status, status);
+            const childRequestId = optionalString(request.childRequestId) || current.childRequestId;
+            const adapterId = optionalString(request.adapterId) || current.executionAdapterId;
+            const executionAttempts = status === 'running'
+                ? markLatestAttempt(current, 'running', now, { workerId, childRequestId, adapterId })
+                : current.executionAttempts;
+            const updated = {
+                ...current,
+                childRequestId,
+                status,
+                startedAt: current.startedAt || now,
+                updatedAt: now,
+                leaseOwner: workerId,
+                leaseExpiresAt: now + leaseMs,
+                heartbeatAt: now,
+                launchOwner: current.launchOwner || workerId,
+                executionAdapterId: adapterId,
+                executionAttempts,
+            };
+            store.runs[index] = updated;
+            this.save(store);
+            return { success: true, run: updated };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    cancelRun(request) {
+        try {
+            const id = requiredString(request.id, 'id');
+            const store = this.load();
+            const index = store.runs.findIndex((run) => run.id === id);
+            if (index < 0)
+                return { success: false, error: 'Subagent run not found.' };
+            const current = store.runs[index];
+            const now = Date.now();
+            const status = TERMINAL_STATUSES.has(current.status) ? current.status : 'cancelled';
+            assertStatusTransition(current.status, status);
+            const executionAttempts = status === 'cancelled' && !TERMINAL_STATUSES.has(current.status)
+                ? markLatestAttempt(current, 'cancelled', now, { error: truncateSummary(request.reason) })
+                : current.executionAttempts;
+            const updated = {
+                ...current,
+                status,
+                endedAt: current.endedAt || now,
+                updatedAt: now,
+                leaseOwner: undefined,
+                leaseExpiresAt: undefined,
+                heartbeatAt: undefined,
+                launchOwner: undefined,
+                launchRequestExpiresAt: undefined,
+                cancellationReason: truncateSummary(request.reason),
+                cancellation: status === 'cancelled' ? normalizeCancellation(request, current, now) : current.cancellation,
+                executionAttempts,
+                cancelledAt: current.cancelledAt || now,
+                terminalReason: status === 'cancelled' ? 'cancelled' : current.terminalReason,
+                recoveryHistory: status === 'cancelled' && !TERMINAL_STATUSES.has(current.status)
+                    ? appendRecoveryHistory(current, {
+                        at: now,
+                        action: 'cancelled',
+                        reason: 'manual-cancel',
+                        workerId: current.leaseOwner,
+                        attempt: current.attempt,
+                        detail: truncateSummary(request.reason),
+                    })
+                    : current.recoveryHistory,
+            };
+            store.runs[index] = updated;
+            this.save(store);
+            return { success: true, run: updated };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    recoverExpiredRuns(request = {}) {
+        try {
+            const now = typeof request.now === 'number' && Number.isFinite(request.now) ? request.now : Date.now();
+            const maxAttempts = Math.max(1, Math.min(20, Math.floor(request.maxAttempts || DEFAULT_MAX_ATTEMPTS)));
+            const runTimeoutMs = clampRunTimeoutMs(request.runTimeoutMs);
+            const staleHeartbeatMs = clampStaleHeartbeatMs(request.staleHeartbeatMs);
+            const store = this.load();
+            let recovered = 0;
+            let failed = 0;
+            let timedOut = 0;
+            let stale = 0;
+            const changed = [];
+            store.runs = store.runs.map((run) => {
+                if (activeRunTimedOut(run, now, runTimeoutMs)) {
+                    assertStatusTransition(run.status, 'failed');
+                    const detail = `Subagent run timed out after ${runTimeoutMs}ms.`;
+                    const updated = {
+                        ...run,
+                        status: 'failed',
+                        updatedAt: now,
+                        endedAt: run.endedAt || now,
+                        leaseOwner: undefined,
+                        leaseExpiresAt: undefined,
+                        heartbeatAt: undefined,
+                        launchOwner: undefined,
+                        launchRequestExpiresAt: undefined,
+                        error: truncateSummary(detail),
+                        timedOutAt: run.timedOutAt || now,
+                        terminalReason: 'timeout',
+                        executionAttempts: markLatestAttempt(run, 'failed', now, { error: detail }),
+                        recoveryHistory: appendRecoveryHistory(run, {
+                            at: now,
+                            action: 'failed',
+                            reason: 'timeout',
+                            workerId: run.leaseOwner,
+                            attempt: run.attempt,
+                            detail,
+                        }),
+                    };
+                    failed += 1;
+                    timedOut += 1;
+                    changed.push(updated);
+                    return updated;
+                }
+                const staleHeartbeat = activeHeartbeatStale(run, now, staleHeartbeatMs);
+                if (!activeLeaseExpired(run, now) && !staleHeartbeat)
+                    return run;
+                const attempts = run.attempt || 0;
+                const terminal = attempts >= maxAttempts;
+                const status = terminal ? 'failed' : 'queued';
+                assertStatusTransition(run.status, status);
+                const reason = staleHeartbeat ? 'heartbeat-stale' : 'lease-expired';
+                const detail = terminal
+                    ? `Subagent ${staleHeartbeat ? 'heartbeat went stale' : 'lease expired'} after ${attempts} attempts.`
+                    : `Recovered ${staleHeartbeat ? 'stale heartbeat' : 'expired lease'} from ${run.leaseOwner || 'unknown worker'}.`;
+                const updated = {
+                    ...run,
+                    status,
+                    updatedAt: now,
+                    endedAt: terminal ? (run.endedAt || now) : undefined,
+                    leaseOwner: undefined,
+                    leaseExpiresAt: undefined,
+                    heartbeatAt: undefined,
+                    launchOwner: undefined,
+                    launchRequestExpiresAt: undefined,
+                    error: truncateSummary(detail),
+                    terminalReason: terminal ? reason : run.terminalReason,
+                    executionAttempts: markLatestAttempt(run, terminal ? 'failed' : 'expired', now, { error: detail }),
+                    recoveryHistory: appendRecoveryHistory(run, {
+                        at: now,
+                        action: terminal ? 'failed' : 'requeued',
+                        reason,
+                        workerId: run.leaseOwner,
+                        attempt: run.attempt,
+                        detail,
+                    }),
+                };
+                if (terminal)
+                    failed += 1;
+                else
+                    recovered += 1;
+                if (staleHeartbeat)
+                    stale += 1;
+                changed.push(updated);
+                return updated;
+            });
+            if (changed.length > 0)
+                this.save(store);
+            return { success: true, recovered, failed, timedOut, stale, runs: changed };
+        }
+        catch (err) {
+            return { success: false, recovered: 0, failed: 0, timedOut: 0, stale: 0, runs: [], error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    getRun(id) {
+        try {
+            const runId = requiredString(id, 'id');
+            const run = this.load().runs.find((item) => item.id === runId);
+            if (!run)
+                return { success: false, error: 'Subagent run not found.' };
+            return { success: true, run };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    listRuns(request = {}) {
+        try {
+            const limit = Math.max(1, Math.min(Number(request.limit) || 100, 1000));
+            let runs = this.load().runs;
+            if (request.parentConversationId)
+                runs = runs.filter((run) => run.parentConversationId === request.parentConversationId);
+            if (request.parentAgentId)
+                runs = runs.filter((run) => run.parentAgentId === request.parentAgentId);
+            if (request.childConversationId)
+                runs = runs.filter((run) => run.childConversationId === request.childConversationId);
+            if (request.childAgentId)
+                runs = runs.filter((run) => run.childAgentId === request.childAgentId);
+            if (request.workspaceId)
+                runs = runs.filter((run) => run.workspaceId === request.workspaceId);
+            if (request.teamId)
+                runs = runs.filter((run) => run.teamId === request.teamId);
+            if (request.status)
+                runs = runs.filter((run) => run.status === request.status);
+            if (request.activeOnly)
+                runs = runs.filter((run) => ACTIVE_STATUSES.has(run.status));
+            return {
+                success: true,
+                runs: runs
+                    .slice()
+                    .sort((a, b) => b.updatedAt - a.updatedAt)
+                    .slice(0, limit),
+            };
+        }
+        catch (err) {
+            return { success: false, runs: [], error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    getDurableRecoverySnapshot(request = {}) {
+        try {
+            const now = typeof request.now === 'number' && Number.isFinite(request.now) ? request.now : Date.now();
+            const runTimeoutMs = clampRunTimeoutMs(request.runTimeoutMs);
+            const staleHeartbeatMs = clampStaleHeartbeatMs(request.staleHeartbeatMs);
+            const runs = this.load().runs;
+            const queued = runs.filter((run) => run.status === 'queued');
+            const launchRequested = runs.filter((run) => run.status === 'launch-requested');
+            const running = runs.filter((run) => run.status === 'running');
+            const waiting = runs.filter((run) => run.status === 'waiting-for-permission' || run.status === 'waiting-for-user');
+            const terminal = runs.filter((run) => TERMINAL_STATUSES.has(run.status));
+            const recoverable = runs.filter((run) => activeLeaseExpired(run, now));
+            const timedOut = runs.filter((run) => activeRunTimedOut(run, now, runTimeoutMs));
+            const stale = runs.filter((run) => activeHeartbeatStale(run, now, staleHeartbeatMs));
+            const pending = runs.filter((run) => run.status === 'queued' || run.status === 'launch-requested');
+            return {
+                success: true,
+                snapshot: {
+                    now,
+                    queuedCount: queued.length,
+                    launchRequestedCount: launchRequested.length,
+                    runningCount: running.length,
+                    waitingCount: waiting.length,
+                    terminalCount: terminal.length,
+                    activeRunIds: runs.filter((run) => ACTIVE_STATUSES.has(run.status)).map((run) => run.id),
+                    pendingRunIds: pending.map((run) => run.id),
+                    launchableRunIds: queued
+                        .filter((run) => !recoverable.some((recoverableRun) => recoverableRun.id === run.id))
+                        .map((run) => run.id),
+                    launchRequestedRunIds: launchRequested.map((run) => run.id),
+                    runningRunIds: running.map((run) => run.id),
+                    activeHeartbeats: runs
+                        .filter((run) => ACTIVE_STATUSES.has(run.status))
+                        .map((run) => ({
+                        runId: run.id,
+                        workerId: run.leaseOwner,
+                        heartbeatAt: run.heartbeatAt,
+                        leaseExpiresAt: run.leaseExpiresAt,
+                    })),
+                    recoverableRunIds: recoverable.map((run) => run.id),
+                    timedOutRunIds: timedOut.map((run) => run.id),
+                    staleRunIds: stale.map((run) => run.id),
+                    oldestQueuedAt: queued.reduce((oldest, run) => oldest === undefined || run.createdAt < oldest ? run.createdAt : oldest, undefined),
+                    oldestLaunchRequestedAt: launchRequested.reduce((oldest, run) => {
+                        const launchRequestedAt = run.launchRequestedAt || run.updatedAt;
+                        return oldest === undefined || launchRequestedAt < oldest ? launchRequestedAt : oldest;
+                    }, undefined),
+                    oldestRunningAt: running.reduce((oldest, run) => {
+                        const startedAt = run.startedAt || run.updatedAt;
+                        return oldest === undefined || startedAt < oldest ? startedAt : oldest;
+                    }, undefined),
+                },
+            };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    getAgentStatus(agentId) {
+        try {
+            const id = requiredString(agentId, 'agentId');
+            const allRuns = this.load().runs.filter((run) => run.childAgentId === id);
+            const activeRuns = allRuns.filter((run) => ACTIVE_STATUSES.has(run.status));
+            return {
+                success: true,
+                status: {
+                    agentId: id,
+                    availability: activeRuns.length > 0 ? 'busy' : 'idle',
+                    activeRunCount: activeRuns.length,
+                    activeRunIds: activeRuns.map((run) => run.id),
+                    activeRuns,
+                    lastRunAt: allRuns.reduce((latest, run) => {
+                        if (latest === undefined || run.updatedAt > latest)
+                            return run.updatedAt;
+                        return latest;
+                    }, undefined),
+                },
+            };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    matchCapabilities(request) {
+        try {
+            return { success: true, capabilityMatch: matchSubagentCapabilities(request) };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    load() {
+        const primary = this.readStoreFile(this.storePath);
+        if (primary.store)
+            return primary.store;
+        if (!existsSync(this.storePath))
+            return { version: 1, runs: [] };
+        this.preserveCorruptStore(this.storePath);
+        const backup = this.readStoreFile(this.backupPath());
+        if (backup.store) {
+            this.atomicWrite(this.storePath, JSON.stringify(backup.store, null, 2));
+            return backup.store;
+        }
+        return { version: 1, runs: [] };
+    }
+    save(store) {
+        mkdirSync(dirname(this.storePath), { recursive: true });
+        const current = this.readStoreFile(this.storePath);
+        if (current.store) {
+            copyFileSync(this.storePath, this.backupPath());
+        }
+        this.atomicWrite(this.storePath, JSON.stringify(store, null, 2));
+    }
+    readStoreFile(path) {
+        try {
+            if (!existsSync(path))
+                return {};
+            const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+            if (parsed.version !== 1)
+                return { error: 'Unsupported subagent run store version.' };
+            if (!Array.isArray(parsed.runs))
+                return { error: 'Subagent run store is missing runs array.' };
+            if (!parsed.runs.every(isPersistedSubagentRun))
+                return { error: 'Subagent run store contains malformed run records.' };
+            return {
+                store: {
+                    version: 1,
+                    runs: parsed.runs.map((run) => ({
+                        ...run,
+                        recoveryHistory: normalizeRecoveryHistory(run.recoveryHistory),
+                        executionMetadata: normalizeRecordMetadata(run.executionMetadata),
+                        executionAttempts: normalizeExecutionAttempts(run.executionAttempts),
+                    })),
+                },
+            };
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    backupPath() {
+        return `${this.storePath}.bak`;
+    }
+    preserveCorruptStore(path) {
+        try {
+            if (!existsSync(path))
+                return;
+            const corruptPath = `${path}.corrupt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            copyFileSync(path, corruptPath);
+        }
+        catch {
+            // Best effort only; callers still avoid overwriting a valid backup with corrupt data.
+        }
+    }
+    atomicWrite(path, contents) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmpPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+        const fd = openSync(tmpPath, 'w');
+        try {
+            writeSync(fd, contents, 0, 'utf-8');
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmpPath, path);
+    }
+}
+let singleton = null;
+/**
+ * The ONE subagent run store for this process.
+ *
+ * 🔴 A SINGLETON ON PURPOSE, and that is why the path is configured here rather than by
+ * constructing a private instance. `SubagentScheduler` and `TeamAgentRouter` both default their
+ * service parameter to this function, so a composition holding its own instance while they hold
+ * the singleton would create runs in one store and launch them from another.
+ *
+ * ⚠️ The default path is the real user's home. A host running with its own home — a dev
+ * profile, a test, CI — must pass `storePath` on the FIRST call, before anything else resolves
+ * the singleton. Until 2026-08-18 nothing did, so an isolated host wrote its subagent runs into
+ * the operator's actual `~/.xeno`, and two hosts shared one roster.
+ */
+/**
+ * Drop the process-wide instance so the next `getSubagentRunService` can open a different home.
+ *
+ * 🔴 FOR TESTS ONLY, and the guard above is why it must exist rather than why it should not.
+ * That guard is correct — two homes in one process is a real misconfiguration and silently serving
+ * the wrong one would present as runs that vanish. But it left a suite that composes several hosts,
+ * each with its own `mkdtemp` home, unable to run at all: `composeHostHeadless.test.ts` was RED from
+ * the day the guard landed (2026-08-18), failing 9 of 11 cases with the guard's own error.
+ *
+ * ⚠️ Calling this from production code is the bug the guard exists to catch, not a way around
+ * it — a running host has exactly one home for its whole life. It is exported separately, named
+ * unmistakably, and touches nothing but the singleton reference.
+ */
+export function resetSubagentRunServiceForTests() {
+    singleton = null;
+}
+export function getSubagentRunService(storePath) {
+    if (!singleton) {
+        singleton = new SubagentRunService(storePath);
+        return singleton;
+    }
+    if (storePath && storePath !== singleton.storePath) {
+        // Throws rather than returning the existing store. Two homes in one process is a real
+        // misconfiguration, and silently handing back the wrong one is the split-brain this exists
+        // to prevent — it would present as runs that vanish rather than as an error.
+        throw new Error('The subagent run store is already open at a different path '
+            + `(${singleton.storePath}); refusing to serve ${storePath} from the same process.`);
+    }
+    return singleton;
+}
+//# sourceMappingURL=SubagentRunService.js.map