@phigon/observer 8.0.1

package/dist/src/guardian-process-monitor.d.ts

@@ -0,0 +1,20 @@
+import type { AgentInventory } from "./generated/phigon/v1/identity_pb.js";
+import type { ActionPolicyPersistence } from "./action-policy.js";
+import type { HTTPGuardianDecisionClient } from "./agentic-guardian.js";
+import type { GuardianContainmentExecutor } from "./guardian-containment.js";
+import type { GuardianDecisionJournal } from "./guardian-decision-journal.js";
+import type { GuardianHostedClient } from "./guardian-hosted-client.js";
+export declare class GuardianProcessMonitor {
+    private readonly options;
+    constructor(options: Readonly<{
+        machineId: string;
+        policyStore: Pick<ActionPolicyPersistence, "load">;
+        decisionClient: Pick<HTTPGuardianDecisionClient, "decide">;
+        containment: Pick<GuardianContainmentExecutor, "execute">;
+        journal: Pick<GuardianDecisionJournal, "append">;
+        onStatus: (message: string) => void;
+        coverageClient?: Pick<GuardianHostedClient, "post">;
+    }>);
+    review(inventory: AgentInventory, signal: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=guardian-process-monitor.d.ts.map

package/dist/src/guardian-process-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardian-process-monitor.d.ts","sourceRoot":"","sources":["../../src/guardian-process-monitor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAIxE,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,QAAQ,CAAC;QAC7C,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;QACnD,cAAc,EAAE,IAAI,CAAC,0BAA0B,EAAE,QAAQ,CAAC,CAAC;QAC3D,WAAW,EAAE,IAAI,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAC;QAC1D,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,CAAC;QACjD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;QACpC,cAAc,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;KACrD,CAAC;IAEI,MAAM,CAAC,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAuE5E"}

package/dist/src/guardian-process-monitor.js

@@ -0,0 +1,98 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { AgentState } from "./generated/phigon/v1/common_pb.js";
+// Discovery is a detection boundary, not a pre-execution sandbox. It can contain
+// agents launched outside the managed CLI only after a central admin decision.
+export class GuardianProcessMonitor {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async review(inventory, signal) {
+        if (signal.aborted)
+            return;
+        const policy = await this.options.policyStore.load(this.options.machineId);
+        if (policy === null) {
+            this.options.onStatus("Guardian process review is waiting for its administrator policy.");
+            return;
+        }
+        let reviewed = 0;
+        let denied = 0;
+        let containmentFailed = 0;
+        let unverified = 0;
+        if (inventory.partial)
+            this.options.onStatus("Guardian discovery is incomplete; process protection coverage is degraded.");
+        for (const agent of inventory.agents) {
+            if (signal.aborted)
+                return;
+            if (agent.state !== AgentState.RUNNING || agent.startedAt === undefined ||
+                agent.processId < 1n || agent.processId > BigInt(Number.MAX_SAFE_INTEGER) ||
+                !agent.capabilities.includes("process-instance")) {
+                if (agent.state === AgentState.RUNNING)
+                    unverified++;
+                continue;
+            }
+            const resource = JSON.stringify({
+                claimed_agent_id: agent.agentId,
+                display_name: agent.displayName,
+                runtime: agent.runtime,
+                executable_path_digest: agent.executablePathDigest,
+                lifecycle: "already_running",
+            });
+            const context = {
+                expectedEffect: "Continue running this discovered AI agent. This is a periodic process review; no proposed command or verified model selection is available.",
+            };
+            try {
+                const decision = await this.options.decisionClient.decide({
+                    policyDigest: policy.policyDigest, agentId: agent.agentId,
+                    processId: Number(agent.processId), processStartedAt: timestampDate(agent.startedAt).toISOString(),
+                    action: "agent.start", resource, context,
+                }, signal);
+                if (signal.aborted)
+                    return;
+                reviewed++;
+                const containment = decision.decision === "deny" && decision.intervention !== "none" && decision.intervention !== "block_action"
+                    ? await this.options.containment.execute({
+                        intervention: decision.intervention, agentId: agent.agentId,
+                        processId: Number(agent.processId), expectedStartedAt: timestampDate(agent.startedAt).toISOString(),
+                    }) : undefined;
+                // Allows are already audited centrally. Report denied running processes
+                // even when the admin authorized only action blocking, never escalation.
+                if (decision.decision !== "allow") {
+                    denied++;
+                    if (containment !== undefined && containment.state !== "succeeded")
+                        containmentFailed++;
+                    const detail = containment?.detail ?? "The running process was not stopped: its policy did not authorize process containment.";
+                    this.options.onStatus(`Phigon Guardian: ${agent.agentId}. ${decision.reason} ${detail}`);
+                    await this.options.journal.append({
+                        agentId: agent.agentId, action: "agent.start", resource,
+                        outcome: decision.decision === "deny" ? "denied" : "approval_required",
+                        reason: decision.reason, decisionSource: "guardian_process_monitor",
+                        latencyMs: decision.latencyMs, policyDigest: policy.policyDigest, context,
+                        ...(decision.adminContract === undefined ? {} : { adminContract: decision.adminContract }),
+                        ...(decision.intervention === "none" ? {} : { intervention: decision.intervention }),
+                        ...(containment === undefined ? {} : { containment }),
+                        model: decision.model, risk: decision.risk, confidence: decision.confidence,
+                    });
+                }
+            }
+            catch {
+                unverified++;
+                this.options.onStatus(`Guardian could not verify process ${agent.agentId}; containment coverage is unavailable for this review.`);
+            }
+        }
+        if (!signal.aborted && this.options.coverageClient) {
+            try {
+                await this.options.coverageClient.post("/v1/machine/guardian/coverage", {
+                    policy_digest: policy.policyDigest, platform: process.platform,
+                    process_review: inventory.partial || unverified > 0 || containmentFailed > 0 ? "degraded" : "active",
+                    discovery_partial: inventory.partial === true,
+                    reviewed, denied, containment_failed: containmentFailed, unverified,
+                }, signal, 10_000);
+            }
+            catch {
+                this.options.onStatus("Guardian could not deliver its coverage report; central protection status will become stale.");
+            }
+        }
+    }
+}
+//# sourceMappingURL=guardian-process-monitor.js.map

package/dist/src/guardian-process-monitor.js.map

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

package/dist/src/health.d.ts

@@ -0,0 +1,35 @@
+import type { ObserverConfig } from "./config.js";
+export type ObserverStreamCursorHealth = Readonly<{
+    machineId: string;
+    acknowledgedSequence: string;
+    updatedAt: string;
+}>;
+export type ObserverHealth = Readonly<{
+    status: "ready" | "needs-pairing";
+    observerVersion: string;
+    controlPlaneOrigin: string;
+    grpcOrigin: string;
+    dataDirectory: string;
+    heartbeatIntervalMs: number;
+    discoveryIntervalMs: number;
+    activityRateLimitPerMinute: number;
+    activityQueueCapacity: number;
+    machineTokenConfigured: boolean;
+    observabilityProfile: string;
+    enabledCollectionCategories: readonly string[];
+    safeCollectionDefaults: boolean;
+    host: Readonly<{
+        architecture: string;
+        hostname: string;
+        platform: NodeJS.Platform;
+        release: string;
+    }>;
+    runtime: Readonly<{
+        node: string;
+    }>;
+    streamCursor?: ObserverStreamCursorHealth;
+    streamCursorIssue?: string;
+    checkedAt: string;
+}>;
+export declare function createHealthSnapshot(config: ObserverConfig, observerVersion: string, now?: Date, streamCursor?: ObserverStreamCursorHealth, streamCursorIssue?: string): ObserverHealth;
+//# sourceMappingURL=health.d.ts.map

package/dist/src/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/health.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,MAAM,EAAE,OAAO,GAAG,eAAe,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0BAA0B,EAAE,MAAM,CAAC;IACnC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,OAAO,CAAC;IAChC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,sBAAsB,EAAE,OAAO,CAAC;IAChC,IAAI,EAAE,QAAQ,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,MAAM,EACvB,GAAG,GAAE,IAAiB,EACtB,YAAY,CAAC,EAAE,0BAA0B,EACzC,iBAAiB,CAAC,EAAE,MAAM,GACzB,cAAc,CAoChB"}

package/dist/src/health.js

@@ -0,0 +1,41 @@
+import { arch, hostname, platform, release } from "node:os";
+const metadataOnlyCategories = new Set([
+    "processMetadata",
+    "fileMetadata",
+    "networkMetadata",
+    "browserMetadata",
+]);
+export function createHealthSnapshot(config, observerVersion, now = new Date(), streamCursor, streamCursorIssue) {
+    return Object.freeze({
+        status: config.machineTokenConfigured ? "ready" : "needs-pairing",
+        observerVersion,
+        controlPlaneOrigin: config.controlPlaneUrl.origin,
+        grpcOrigin: config.grpcUrl.origin,
+        dataDirectory: config.dataDirectory,
+        heartbeatIntervalMs: config.heartbeatIntervalMs,
+        discoveryIntervalMs: config.discoveryIntervalMs,
+        activityRateLimitPerMinute: config.activityRateLimitPerMinute,
+        activityQueueCapacity: config.activityQueueCapacity,
+        machineTokenConfigured: config.machineTokenConfigured,
+        observabilityProfile: config.observabilityProfile,
+        enabledCollectionCategories: Object.freeze(Object.entries(config.policy)
+            .filter(([, enabled]) => enabled)
+            .map(([category]) => category)),
+        safeCollectionDefaults: Object.entries(config.policy).every(([category, enabled]) => !enabled || metadataOnlyCategories.has(category)),
+        host: Object.freeze({
+            architecture: arch(),
+            hostname: hostname(),
+            platform: platform(),
+            release: release(),
+        }),
+        runtime: Object.freeze({
+            node: process.version,
+        }),
+        ...(streamCursor === undefined
+            ? {}
+            : { streamCursor: Object.freeze(streamCursor) }),
+        ...(streamCursorIssue === undefined ? {} : { streamCursorIssue }),
+        checkedAt: now.toISOString(),
+    });
+}
+//# sourceMappingURL=health.js.map

package/dist/src/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAG5D,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACrC,iBAAiB;IACjB,cAAc;IACd,iBAAiB;IACjB,iBAAiB;CAClB,CAAC,CAAC;AAoCH,MAAM,UAAU,oBAAoB,CAClC,MAAsB,EACtB,eAAuB,EACvB,MAAY,IAAI,IAAI,EAAE,EACtB,YAAyC,EACzC,iBAA0B;IAE1B,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;QACjE,eAAe;QACf,kBAAkB,EAAE,MAAM,CAAC,eAAe,CAAC,MAAM;QACjD,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM;QACjC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,0BAA0B,EAAE,MAAM,CAAC,0BAA0B;QAC7D,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;QACnD,sBAAsB,EAAE,MAAM,CAAC,sBAAsB;QACrD,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,2BAA2B,EAAE,MAAM,CAAC,MAAM,CACxC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC;aAChC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CACjC;QACD,sBAAsB,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CACzD,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,IAAI,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAC1E;QACD,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC;YAClB,YAAY,EAAE,IAAI,EAAE;YACpB,QAAQ,EAAE,QAAQ,EAAE;YACpB,QAAQ,EAAE,QAAQ,EAAE;YACpB,OAAO,EAAE,OAAO,EAAE;SACnB,CAAC;QACF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,IAAI,EAAE,OAAO,CAAC,OAAO;SACtB,CAAC;QACF,GAAG,CAAC,YAAY,KAAK,SAAS;YAC5B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjE,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;KAC7B,CAAC,CAAC;AACL,CAAC"}

package/dist/src/historical-identity-store.d.ts

@@ -0,0 +1,20 @@
+import { type AgentIdentity, type AgentInventory } from "./generated/phigon/v1/identity_pb.js";
+export type HistoricalIdentityScope = Readonly<{
+    tenantId: string;
+    machineId: string;
+}>;
+/**
+ * Stores only sanitized inventory metadata needed to keep stopped runtime and
+ * unattributed source history targets addressable after observer restart.
+ * Activity content, raw source IDs, raw process keys, credentials, and paths
+ * are never accepted by this catalog.
+ */
+export declare class HistoricalIdentityStore {
+    #private;
+    constructor(dataDirectory: string, scope: HistoricalIdentityScope);
+    load(): Promise<readonly AgentIdentity[]>;
+    remember(candidates: readonly AgentIdentity[]): Promise<readonly AgentIdentity[]>;
+    identities(): readonly AgentIdentity[];
+}
+export declare function mergeInventoryWithHistoricalIdentities(inventory: AgentInventory, historical: readonly AgentIdentity[]): AgentInventory;
+//# sourceMappingURL=historical-identity-store.d.ts.map

package/dist/src/historical-identity-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"historical-identity-store.d.ts","sourceRoot":"","sources":["../../src/historical-identity-store.ts"],"names":[],"mappings":"AAoBA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,sCAAsC,CAAC;AAW9C,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAwBH;;;;;GAKG;AACH,qBAAa,uBAAuB;;gBAUhC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,uBAAuB;IAQhC,IAAI,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAKnC,QAAQ,CACZ,UAAU,EAAE,SAAS,aAAa,EAAE,GACnC,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAgCpC,UAAU,IAAI,SAAS,aAAa,EAAE;CAyFvC;AAED,wBAAgB,sCAAsC,CACpD,SAAS,EAAE,cAAc,EACzB,UAAU,EAAE,SAAS,aAAa,EAAE,GACnC,cAAc,CAyChB"}

package/dist/src/historical-identity-store.js

@@ -0,0 +1,391 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { timestampDate, timestampFromDate, } from "@bufbuild/protobuf/wkt";
+import { AgentKind, AgentState, } from "./generated/phigon/v1/common_pb.js";
+import { AgentIdentitySchema, AgentInventorySchema, } from "./generated/phigon/v1/identity_pb.js";
+const catalogVersion = 1;
+const maxCatalogBytes = 1 << 20;
+const maxHistoricalIdentities = 256;
+const catalogFileName = "historical-agent-identities.json";
+const processKeyCapabilityPattern = /^process-key-sha256:[a-f0-9]{32}$/u;
+const capabilityPattern = /^[a-z0-9][a-z0-9:._+-]{0,63}$/u;
+const scopedIDPattern = /^[A-Za-z0-9._:-]{1,128}$/u;
+/**
+ * Stores only sanitized inventory metadata needed to keep stopped runtime and
+ * unattributed source history targets addressable after observer restart.
+ * Activity content, raw source IDs, raw process keys, credentials, and paths
+ * are never accepted by this catalog.
+ */
+export class HistoricalIdentityStore {
+    #dataDirectory;
+    #path;
+    #scope;
+    #identities = new Map();
+    #loadPromise;
+    #saveChain = Promise.resolve();
+    #needsRewrite = false;
+    constructor(dataDirectory, scope) {
+        validateScope(scope);
+        this.#dataDirectory = dataDirectory;
+        this.#path = join(dataDirectory, catalogFileName);
+        this.#scope = Object.freeze({ ...scope });
+    }
+    load() {
+        this.#loadPromise ??= this.#loadOnce();
+        return this.#loadPromise;
+    }
+    async remember(candidates) {
+        await this.load();
+        const operation = this.#saveChain
+            .catch(() => undefined)
+            .then(async () => {
+            let changed = this.#needsRewrite;
+            for (const candidate of candidates) {
+                const sanitized = sanitizedHistoricalIdentity(candidate);
+                if (sanitized === undefined)
+                    continue;
+                const previous = this.#identities.get(sanitized.agentId);
+                if (previous === undefined ||
+                    serializedIdentity(previous) !== serializedIdentity(sanitized)) {
+                    this.#identities.set(sanitized.agentId, sanitized);
+                    changed = true;
+                }
+            }
+            if (this.#bound())
+                changed = true;
+            if (changed) {
+                await this.#save();
+                this.#needsRewrite = false;
+            }
+            return this.identities();
+        });
+        this.#saveChain = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    identities() {
+        return [...this.#identities.values()].sort((left, right) => left.agentId.localeCompare(right.agentId));
+    }
+    async #loadOnce() {
+        let raw;
+        try {
+            const metadata = await stat(this.#path);
+            if (!metadata.isFile() || metadata.size > maxCatalogBytes) {
+                this.#needsRewrite = true;
+                return [];
+            }
+            raw = await readFile(this.#path, "utf8");
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.#needsRewrite = true;
+            return [];
+        }
+        const catalog = parsedCatalog(parsed);
+        if (catalog === undefined ||
+            catalog.tenant_id !== this.#scope.tenantId ||
+            catalog.machine_id !== this.#scope.machineId) {
+            this.#needsRewrite = true;
+            return [];
+        }
+        for (const stored of catalog.identities) {
+            const identity = parsedIdentity(stored);
+            if (identity === undefined) {
+                this.#identities.clear();
+                this.#needsRewrite = true;
+                return [];
+            }
+            this.#identities.set(identity.agentId, identity);
+        }
+        return this.identities();
+    }
+    #bound() {
+        if (this.#identities.size <= maxHistoricalIdentities)
+            return false;
+        const retained = [...this.#identities.values()]
+            .sort(recentIdentityFirst)
+            .slice(0, maxHistoricalIdentities);
+        this.#identities.clear();
+        for (const identity of retained) {
+            this.#identities.set(identity.agentId, identity);
+        }
+        return true;
+    }
+    async #save() {
+        await mkdir(this.#dataDirectory, { recursive: true, mode: 0o700 });
+        await chmod(this.#dataDirectory, 0o700);
+        const temporaryPath = `${this.#path}.${process.pid}.${randomUUID()}.tmp`;
+        const catalog = {
+            version: catalogVersion,
+            tenant_id: this.#scope.tenantId,
+            machine_id: this.#scope.machineId,
+            updated_at: new Date().toISOString(),
+            identities: this.identities().map(storedIdentity),
+        };
+        try {
+            await writeFile(temporaryPath, `${JSON.stringify(catalog)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await rename(temporaryPath, this.#path);
+            await chmod(this.#path, 0o600);
+        }
+        catch (error) {
+            try {
+                await unlink(temporaryPath);
+            }
+            catch {
+                // The temporary file may not have been created.
+            }
+            throw error;
+        }
+    }
+}
+export function mergeInventoryWithHistoricalIdentities(inventory, historical) {
+    const byID = new Map();
+    for (const identity of historical) {
+        const sanitized = sanitizedHistoricalIdentity(identity);
+        if (sanitized !== undefined)
+            byID.set(sanitized.agentId, sanitized);
+    }
+    // A fresh discovery observation is authoritative for the same lifetime.
+    for (const identity of inventory.agents) {
+        byID.set(identity.agentId, identity);
+    }
+    const candidates = [...byID.values()];
+    const runtimeProducts = new Set(candidates
+        .filter((identity) => identity.capabilities.includes("process-instance"))
+        .flatMap(agentProductCapabilities));
+    const combined = candidates.filter((identity) => identity.capabilities.includes("process-instance") ||
+        !agentProductCapabilities(identity).some((capability) => runtimeProducts.has(capability)));
+    const selected = combined
+        .sort(inventoryRetentionOrder)
+        .slice(0, maxHistoricalIdentities)
+        .sort((left, right) => left.agentId.localeCompare(right.agentId));
+    const overflow = combined.length > selected.length;
+    const overflowNotice = "Historical agent identities exceeded inventory capacity.";
+    const notices = overflow && !inventory.notices.includes(overflowNotice)
+        ? [...inventory.notices.slice(0, 31), overflowNotice]
+        : [...inventory.notices];
+    return create(AgentInventorySchema, {
+        ...inventory,
+        agents: selected,
+        partial: inventory.partial || overflow,
+        notices,
+    });
+}
+function sanitizedHistoricalIdentity(value) {
+    const capabilities = validatedCapabilities(value.capabilities);
+    if (!/^agt_[a-f0-9]{32}$/u.test(value.agentId) ||
+        value.kind < AgentKind.CLAUDE ||
+        value.kind > AgentKind.GENERIC ||
+        !validBoundedText(value.displayName, 128, true) ||
+        !validBoundedText(value.version, 64, false) ||
+        !validBoundedText(value.runtime, 128, false) ||
+        !validDigest(value.executablePathDigest) ||
+        capabilities === undefined ||
+        value.lastObservedAt === undefined) {
+        return undefined;
+    }
+    const processIdentity = capabilities.includes("process-instance");
+    const sourceIdentity = capabilities.includes("source-isolated");
+    if (processIdentity === sourceIdentity)
+        return undefined;
+    if (processIdentity &&
+        capabilities.filter((capability) => processKeyCapabilityPattern.test(capability)).length !== 1) {
+        return undefined;
+    }
+    if (sourceIdentity &&
+        (!capabilities.includes("unattributed") || value.processId !== 0n)) {
+        return undefined;
+    }
+    const lastObserved = validTimestamp(timestampDate(value.lastObservedAt));
+    const startedAt = value.startedAt === undefined
+        ? undefined
+        : validTimestamp(timestampDate(value.startedAt));
+    if (lastObserved === undefined ||
+        (value.startedAt !== undefined && startedAt === undefined)) {
+        return undefined;
+    }
+    return create(AgentIdentitySchema, {
+        agentId: value.agentId,
+        kind: value.kind,
+        displayName: value.displayName,
+        version: value.version,
+        runtime: value.runtime,
+        state: processIdentity ? AgentState.STOPPED : AgentState.UNKNOWN,
+        processId: processIdentity ? value.processId : 0n,
+        ...(startedAt === undefined
+            ? {}
+            : { startedAt: timestampFromDate(startedAt) }),
+        lastObservedAt: timestampFromDate(lastObserved),
+        capabilities,
+        executablePathDigest: value.executablePathDigest,
+    });
+}
+function storedIdentity(value) {
+    return {
+        agent_id: value.agentId,
+        kind: value.kind,
+        display_name: value.displayName,
+        version: value.version,
+        runtime: value.runtime,
+        state: value.state,
+        process_id: value.processId.toString(),
+        ...(value.startedAt === undefined
+            ? {}
+            : { started_at: timestampDate(value.startedAt).toISOString() }),
+        last_observed_at: value.lastObservedAt === undefined
+            ? new Date(0).toISOString()
+            : timestampDate(value.lastObservedAt).toISOString(),
+        capabilities: [...value.capabilities],
+        executable_path_digest: value.executablePathDigest,
+    };
+}
+function parsedCatalog(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("version" in value) ||
+        value.version !== catalogVersion ||
+        !("tenant_id" in value) ||
+        typeof value.tenant_id !== "string" ||
+        !("machine_id" in value) ||
+        typeof value.machine_id !== "string" ||
+        !("updated_at" in value) ||
+        typeof value.updated_at !== "string" ||
+        validDateString(value.updated_at) === undefined ||
+        !("identities" in value) ||
+        !Array.isArray(value.identities) ||
+        value.identities.length > maxHistoricalIdentities) {
+        return undefined;
+    }
+    return value;
+}
+function parsedIdentity(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("agent_id" in value) ||
+        typeof value.agent_id !== "string" ||
+        !("kind" in value) ||
+        typeof value.kind !== "number" ||
+        !("display_name" in value) ||
+        typeof value.display_name !== "string" ||
+        !("version" in value) ||
+        typeof value.version !== "string" ||
+        !("runtime" in value) ||
+        typeof value.runtime !== "string" ||
+        !("state" in value) ||
+        typeof value.state !== "number" ||
+        !("process_id" in value) ||
+        typeof value.process_id !== "string" ||
+        !/^\d{1,20}$/u.test(value.process_id) ||
+        !("last_observed_at" in value) ||
+        typeof value.last_observed_at !== "string" ||
+        !("capabilities" in value) ||
+        !Array.isArray(value.capabilities) ||
+        value.capabilities.some((capability) => typeof capability !== "string") ||
+        !("executable_path_digest" in value) ||
+        typeof value.executable_path_digest !== "string") {
+        return undefined;
+    }
+    const startedAt = "started_at" in value
+        ? typeof value.started_at === "string"
+            ? validDateString(value.started_at)
+            : undefined
+        : null;
+    const lastObservedAt = validDateString(value.last_observed_at);
+    if (startedAt === undefined || lastObservedAt === undefined) {
+        return undefined;
+    }
+    let processID;
+    try {
+        processID = BigInt(value.process_id);
+    }
+    catch {
+        return undefined;
+    }
+    if (processID > 18446744073709551615n)
+        return undefined;
+    const candidate = create(AgentIdentitySchema, {
+        agentId: value.agent_id,
+        kind: value.kind,
+        displayName: value.display_name,
+        version: value.version,
+        runtime: value.runtime,
+        state: value.state,
+        processId: processID,
+        ...(startedAt === null
+            ? {}
+            : { startedAt: timestampFromDate(startedAt) }),
+        lastObservedAt: timestampFromDate(lastObservedAt),
+        capabilities: value.capabilities,
+        executablePathDigest: value.executable_path_digest,
+    });
+    return sanitizedHistoricalIdentity(candidate);
+}
+function validatedCapabilities(capabilities) {
+    if (capabilities.length === 0 ||
+        capabilities.length > 64 ||
+        capabilities.some((capability) => !capabilityPattern.test(capability))) {
+        return undefined;
+    }
+    return [...new Set(capabilities)].sort();
+}
+function agentProductCapabilities(identity) {
+    return identity.capabilities.filter((capability) => capability.startsWith("agent-product:"));
+}
+function validBoundedText(value, maxBytes, required) {
+    return ((!required || value.length > 0) &&
+        Buffer.byteLength(value, "utf8") <= maxBytes &&
+        !/[\u0000-\u001f\u007f]/u.test(value));
+}
+function validDigest(value) {
+    return value.length <= 128 && /^[A-Za-z0-9._:-]*$/u.test(value);
+}
+function validDateString(value) {
+    if (value.length > 64)
+        return undefined;
+    return validTimestamp(new Date(value));
+}
+function validTimestamp(value) {
+    return Number.isNaN(value.getTime()) ? undefined : value;
+}
+function validateScope(scope) {
+    if (!scopedIDPattern.test(scope.tenantId) ||
+        !scopedIDPattern.test(scope.machineId)) {
+        throw new Error("Historical identity scope is invalid.");
+    }
+}
+function recentIdentityFirst(left, right) {
+    const leftObserved = left.lastObservedAt === undefined
+        ? 0
+        : timestampDate(left.lastObservedAt).getTime();
+    const rightObserved = right.lastObservedAt === undefined
+        ? 0
+        : timestampDate(right.lastObservedAt).getTime();
+    return rightObserved - leftObserved || left.agentId.localeCompare(right.agentId);
+}
+function inventoryRetentionOrder(left, right) {
+    const leftCurrent = left.state === AgentState.RUNNING ? 1 : 0;
+    const rightCurrent = right.state === AgentState.RUNNING ? 1 : 0;
+    if (leftCurrent !== rightCurrent)
+        return rightCurrent - leftCurrent;
+    const leftSource = left.capabilities.includes("source-isolated") ? 1 : 0;
+    const rightSource = right.capabilities.includes("source-isolated") ? 1 : 0;
+    if (leftSource !== rightSource)
+        return rightSource - leftSource;
+    return recentIdentityFirst(left, right);
+}
+function serializedIdentity(value) {
+    return JSON.stringify(storedIdentity(value));
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+//# sourceMappingURL=historical-identity-store.js.map