comisai 1.0.42 → 1.0.45

package/node_modules/@comis/daemon/dist/wiring/mcp-token-port-adapter.js

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: server-name validator at the wrapper boundary; the throw
+// surfaces to the SDK's OAuthClientProvider.saveTokens callback (which has no
+// Result-typed surface). Disk + port writes are guarded so a malformed server
+// name cannot corrupt either store.
+/**
+ * Port-backed MCP token store adapter.
+ *
+ * Wraps the existing `createTokenStore` (chokidar watch + 0600 fs-safe substrate
+ * preserved). Syncs the OAuth token triple (access/refresh/expires) to the
+ * `OAuthCredentialStorePort` on every `saveTokens` call, unifying MCP OAuth
+ * tokens onto the same credential store used for provider tokens.
+ *
+ * LOCATION INVARIANT: This file MUST live in `packages/daemon/src/wiring/`.
+ * The adapter is constructed in daemon wiring — never in packages/skills
+ * (skills→memory is a forbidden edge in the architecture graph).
+ * See architecture-graph.test.ts: daemon = { ..., skills, memory, ... }.
+ *
+ * SECURITY:
+ * - No AES-at-rest: the disk-backed createTokenStore owns 0o600 perms + the
+ *   fs-safe substrate. AES-at-rest for MCP tokens is deferred to a later phase.
+ * - Server-name validation is ENFORCED at the wrapper boundary: every method
+ *   that uses the server identity to compose a profileId or filename rejects
+ *   names that do not match the same /^[a-zA-Z0-9_-]+$/ class enforced by
+ *   `McpServerEntrySchema`. This guards against profileId corruption (e.g. a
+ *   `:` would split "mcp-oauth:<server>" ambiguously) and against the unsaved/
+ *   runtime-only paths that skip the config schema.
+ * - Port write failure is NON-FATAL: the disk store is authoritative.
+ *   A port.set failure is silently suppressed (non-fatal) to preserve the
+ *   existing MCP OAuth flow; callers must not rely on the port for read-back.
+ * - Token values are NEVER logged (Pino redaction is a safety net, not a
+ *   license to log them).
+ *
+ * INVARIANTS:
+ * - `startWatch()` and `close()` delegate to the underlying createTokenStore
+ *   verbatim — the chokidar disk-watch refresh rotation survives port wrapping.
+ * - The adapter does NOT introduce a new token-file path; it reuses exactly the
+ *   tokensDir passed to createTokenStore deps.
+ *
+ * @module
+ */
+import { createTokenStore, } from "@comis/skills";
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+/**
+ * Provider identifier for MCP OAuth profiles stored in OAuthCredentialStorePort.
+ * Using "mcp-oauth" as the provider makes it easy to filter MCP tokens via
+ * `port.list({ provider: "mcp-oauth" })`.
+ */
+const MCP_OAUTH_PROVIDER = "mcp-oauth";
+/**
+ * Identifier character class shared with `McpServerEntrySchema` in
+ * `packages/core/src/config/schema-skills.ts`. Any server name that flows into
+ * the wrapper's filename or profileId composition MUST satisfy this pattern.
+ */
+const MCP_SERVER_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Assert that a server name is safe to interpolate into both the disk filename
+ * (`<server>.json` under `tokensDir`) and the composed profileId
+ * (`mcp-oauth:<server>`). Throws: a `:` would split the profileId
+ * ambiguously, and a `/` would risk traversal at the inner store's safePath
+ * boundary. Schema-validated config names already pass; this guard exists for
+ * the unsaved/runtime callers that skip the schema (e.g. mcp.connect with a
+ * runtime-only `name`, future SDK lifecycle callbacks).
+ */
+function assertValidServerName(serverName) {
+    if (typeof serverName !== "string" || !MCP_SERVER_NAME_RE.test(serverName)) {
+        throw new Error(`[invalid_server_name] MCP server name "${String(serverName)}" must match /^[a-zA-Z0-9_-]+$/. ` +
+            `This guards against profileId corruption in OAuthCredentialStorePort and traversal at the disk filename.`);
+    }
+}
+/**
+ * Compose the profileId for a given MCP server name.
+ * Format: "mcp-oauth:<serverName>" — matches the OAuthProfile.profileId convention
+ * of "<provider>:<identity>". Callers MUST `assertValidServerName(serverName)`
+ * first; this helper does not re-validate.
+ */
+function mcpProfileId(serverName) {
+    return `${MCP_OAUTH_PROVIDER}:${serverName}`;
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a port-backed MCP token store.
+ *
+ * Returns a `TokenStore` that:
+ * 1. Delegates ALL methods to the underlying `createTokenStore` (disk-backed,
+ *    chokidar watch, 0o600 perms, 0o700 dir — all preserved).
+ * 2. On every `saveTokens` call, additionally writes the token triple
+ *    (access/refresh/expires) to the injected `OAuthCredentialStorePort`.
+ *
+ * The port write is best-effort (non-fatal): a failure does NOT interrupt the
+ * token save or throw to the caller. The disk store remains authoritative.
+ *
+ * @param port - The unified OAuth credential store port (injection from daemon).
+ * @param deps - Dependencies forwarded verbatim to `createTokenStore`.
+ */
+export function createPortBackedMcpTokenStore(port, deps) {
+    const inner = createTokenStore(deps);
+    return {
+        tokens(server) {
+            return inner.tokens(server);
+        },
+        async saveTokens(server, sdkTokens) {
+            // Reject malformed server names BEFORE any side effect (disk write
+            // OR port write). Schema-validated config names already pass; this guard
+            // covers unsaved/runtime callers and future SDK lifecycle callbacks that
+            // skip `McpServerEntrySchema`.
+            assertValidServerName(server);
+            // Write to disk first (disk store is authoritative).
+            await inner.saveTokens(server, sdkTokens);
+            // Sync to the unified credential port — best-effort, non-fatal.
+            // The token triple is the minimum needed for cross-store visibility.
+            // The `expires` field: the inner store computes an absolute expiresAt
+            // from sdkTokens.expires_in; we replicate the same arithmetic here so
+            // the port receives the same absolute epoch-ms value.
+            const now = deps.now ?? Date.now;
+            const SENTINEL_TTL_SEC = 10 * 365 * 24 * 60 * 60;
+            const ttlSec = sdkTokens.expires_in ?? SENTINEL_TTL_SEC;
+            const expiresAtMs = now() + ttlSec * 1000;
+            const profileId = mcpProfileId(server);
+            const profile = {
+                provider: MCP_OAUTH_PROVIDER,
+                profileId,
+                access: sdkTokens.access_token,
+                refresh: sdkTokens.refresh_token ?? "",
+                expires: expiresAtMs,
+                version: 1,
+            };
+            // Non-fatal: a port-set failure must NOT interrupt the disk write or
+            // throw to the SDK saveTokens caller. But silence is an observability
+            // regression: without a log, a persistent port-side error (disk
+            // corruption on the credential partition, future schema mismatch, etc.)
+            // leaves the disk store and the unified credential port silently
+            // desynced. Surface both failure shapes (ok:false Result + thrown
+            // rejection) at WARN with the canonical Pino fields so an operator
+            // querying port.list({provider:"mcp-oauth"}) has a diagnostic trail.
+            let portSetResult;
+            let thrown;
+            try {
+                portSetResult = await port.set(profileId, profile);
+            }
+            catch (err) {
+                thrown = err;
+            }
+            if (thrown !== undefined || (portSetResult !== undefined && !portSetResult.ok)) {
+                const errPayload = thrown !== undefined
+                    ? thrown instanceof Error
+                        ? thrown.message
+                        : String(thrown)
+                    : portSetResult.error.message;
+                deps.logger.warn({
+                    serverName: server,
+                    provider: MCP_OAUTH_PROVIDER,
+                    err: errPayload,
+                    hint: "OAuthCredentialStorePort.set failed; disk-backed MCP token store remains authoritative",
+                    errorKind: "internal",
+                    submodule: "mcp-token-port-adapter",
+                }, "MCP OAuth credential-port sync failed (non-fatal)");
+            }
+        },
+        saveClientInformation(server, info) {
+            return inner.saveClientInformation(server, info);
+        },
+        clientInformation(server) {
+            return inner.clientInformation(server);
+        },
+        saveDiscoveryState(server, state) {
+            return inner.saveDiscoveryState(server, state);
+        },
+        discoveryState(server) {
+            return inner.discoveryState(server);
+        },
+        deleteAll(server) {
+            return inner.deleteAll(server);
+        },
+        // CRITICAL: startWatch and close MUST delegate to the inner store.
+        // The chokidar disk-watch (atomic:100 debounce + cache-invalidation) lives
+        // in the inner createTokenStore. Overriding these would break cross-process
+        // refresh rotation.
+        startWatch() {
+            return inner.startWatch();
+        },
+        close() {
+            return inner.close();
+        },
+    };
+}

package/node_modules/@comis/daemon/dist/wiring/mcp-token-store-encrypted.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Encrypted SQLite-backed TokenStore implementation for MCP OAuth credentials.
+ *
+ * Stores all three MCP OAuth artifacts (tokens, clientInformation, discoveryState)
+ * as AES-256-GCM blobs in the `mcp_credentials` table in secrets.db.
+ *
+ * Key design invariants:
+ * - Does NOT own the db lifecycle (mirrors createOAuthProfileStoreEncrypted).
+ *   close() is a no-op — the db handle is never closed here.
+ * - Writes zero plaintext files; no mcp-tokens/ directory is ever created.
+ * - client_secret is inside the encrypted JSON blob — never written plaintext.
+ * - expires_at stores absolute epoch-ms; tokens() reconstructs relative expires_in.
+ * - startWatch() is a no-op (no chokidar — no disk presence).
+ * - Row validation via createRowMapper / Zod — no untyped casts.
+ *
+ * @module
+ */
+import type Database from "better-sqlite3";
+import type { SecretsCrypto } from "@comis/core";
+import type { TokenStore } from "@comis/skills";
+/**
+ * Create a fully encrypted TokenStore backed by the `mcp_credentials` table
+ * in the shared secrets.db.
+ *
+ * The caller supplies the pre-opened db handle and SecretsCrypto instance.
+ * This factory does NOT open or close the database.
+ */
+export declare function createMcpTokenStoreEncrypted(db: Database.Database, crypto: SecretsCrypto): TokenStore;

package/node_modules/@comis/daemon/dist/wiring/mcp-token-store-encrypted.js

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: server-name validation (precondition) + encrypt/decrypt error propagation
+/**
+ * Encrypted SQLite-backed TokenStore implementation for MCP OAuth credentials.
+ *
+ * Stores all three MCP OAuth artifacts (tokens, clientInformation, discoveryState)
+ * as AES-256-GCM blobs in the `mcp_credentials` table in secrets.db.
+ *
+ * Key design invariants:
+ * - Does NOT own the db lifecycle (mirrors createOAuthProfileStoreEncrypted).
+ *   close() is a no-op — the db handle is never closed here.
+ * - Writes zero plaintext files; no mcp-tokens/ directory is ever created.
+ * - client_secret is inside the encrypted JSON blob — never written plaintext.
+ * - expires_at stores absolute epoch-ms; tokens() reconstructs relative expires_in.
+ * - startWatch() is a no-op (no chokidar — no disk presence).
+ * - Row validation via createRowMapper / Zod — no untyped casts.
+ *
+ * @module
+ */
+import { z } from "zod";
+import { systemNowMs } from "@comis/core";
+import { createRowMapper } from "@comis/memory";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Sentinel TTL for tokens with no expires_in: ~10 years in seconds. */
+const SENTINEL_TTL_SEC = 10 * 365 * 24 * 60 * 60;
+/** Regex for valid MCP server names — prevents SQL injection via parameterised key. */
+const MCP_SERVER_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+// ---------------------------------------------------------------------------
+// Server-name validation (precondition guard — @allow-throw)
+// ---------------------------------------------------------------------------
+function assertServerName(server) {
+    if (typeof server !== "string" || !MCP_SERVER_NAME_RE.test(server)) {
+        throw new Error(`Invalid MCP server name: ${JSON.stringify(server)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Row schema + mapper
+// ---------------------------------------------------------------------------
+const McpCredRowSchema = z.strictObject({
+    server: z.string(),
+    artifact: z.enum(["tokens", "client", "discovery"]),
+    ciphertext: z.instanceof(Buffer),
+    iv: z.instanceof(Buffer),
+    auth_tag: z.instanceof(Buffer),
+    salt: z.instanceof(Buffer),
+    expires_at: z.number().nullable(),
+    created_at: z.number(),
+    updated_at: z.number(),
+});
+const mcpCredMapper = createRowMapper(McpCredRowSchema);
+// ---------------------------------------------------------------------------
+// DDL
+// ---------------------------------------------------------------------------
+function initMcpCredSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS mcp_credentials (
+      server      TEXT    NOT NULL,
+      artifact    TEXT    NOT NULL CHECK(artifact IN ('tokens','client','discovery')),
+      ciphertext  BLOB    NOT NULL,
+      iv          BLOB    NOT NULL,
+      auth_tag    BLOB    NOT NULL,
+      salt        BLOB    NOT NULL,
+      expires_at  INTEGER,
+      created_at  INTEGER NOT NULL,
+      updated_at  INTEGER NOT NULL,
+      PRIMARY KEY (server, artifact)
+    )
+  `);
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a fully encrypted TokenStore backed by the `mcp_credentials` table
+ * in the shared secrets.db.
+ *
+ * The caller supplies the pre-opened db handle and SecretsCrypto instance.
+ * This factory does NOT open or close the database.
+ */
+export function createMcpTokenStoreEncrypted(db, crypto) {
+    initMcpCredSchema(db);
+    // Prepared statements — compiled once at construction time.
+    const upsertStmt = db.prepare(`
+    INSERT INTO mcp_credentials
+      (server, artifact, ciphertext, iv, auth_tag, salt, expires_at, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(server, artifact) DO UPDATE SET
+      ciphertext = excluded.ciphertext,
+      iv         = excluded.iv,
+      auth_tag   = excluded.auth_tag,
+      salt       = excluded.salt,
+      expires_at = excluded.expires_at,
+      updated_at = excluded.updated_at
+  `);
+    const getStmt = db.prepare("SELECT * FROM mcp_credentials WHERE server = ? AND artifact = ?");
+    const deleteAllStmt = db.prepare("DELETE FROM mcp_credentials WHERE server = ?");
+    // ---- Internal helpers --------------------------------------------------
+    function encryptAndUpsert(server, artifact, payload, expiresAt) {
+        const encResult = crypto.encrypt(payload);
+        if (!encResult.ok)
+            throw encResult.error;
+        const { ciphertext, iv, authTag, salt } = encResult.value;
+        const now = systemNowMs();
+        upsertStmt.run(server, artifact, ciphertext, iv, authTag, salt, expiresAt, now, now);
+    }
+    function getDecryptedRow(server, artifact) {
+        const raw = getStmt.get(server, artifact);
+        const parsed = mcpCredMapper.parseOptionalRow(raw);
+        if (!parsed.ok) {
+            throw new Error(`mcp_credentials row validation failed: ${parsed.error.message}`);
+        }
+        const row = parsed.value;
+        if (!row)
+            return undefined;
+        const encrypted = {
+            ciphertext: row.ciphertext,
+            iv: row.iv,
+            authTag: row.auth_tag, // SQL column auth_tag → TS field authTag
+            salt: row.salt,
+        };
+        const decResult = crypto.decrypt(encrypted);
+        if (!decResult.ok)
+            throw decResult.error;
+        return { plaintext: decResult.value, expiresAt: row.expires_at };
+    }
+    // ---- TokenStore implementation ----------------------------------------
+    return {
+        async tokens(server) {
+            assertServerName(server);
+            const meta = getDecryptedRow(server, "tokens");
+            if (meta === undefined)
+                return undefined;
+            const raw = JSON.parse(meta.plaintext);
+            let expiresIn;
+            if (meta.expiresAt !== null) {
+                expiresIn = Math.max(0, Math.floor((meta.expiresAt - systemNowMs()) / 1000));
+            }
+            const result = {
+                access_token: raw.access_token,
+                token_type: raw.token_type,
+                ...(expiresIn !== undefined ? { expires_in: expiresIn } : {}),
+                ...(raw.refresh_token !== undefined ? { refresh_token: raw.refresh_token } : {}),
+                ...(raw.scope !== undefined ? { scope: raw.scope } : {}),
+            };
+            return result;
+        },
+        async saveTokens(server, sdkTokens) {
+            assertServerName(server);
+            const ttlSec = sdkTokens.expires_in ?? SENTINEL_TTL_SEC;
+            const expiresAt = systemNowMs() + ttlSec * 1000;
+            const payload = JSON.stringify(sdkTokens);
+            encryptAndUpsert(server, "tokens", payload, expiresAt);
+        },
+        async clientInformation(server) {
+            assertServerName(server);
+            const meta = getDecryptedRow(server, "client");
+            if (meta === undefined)
+                return undefined;
+            return JSON.parse(meta.plaintext);
+        },
+        async saveClientInformation(server, info) {
+            assertServerName(server);
+            // Encrypt the entire SDK object as a JSON blob — client_secret stays inside the blob.
+            const payload = JSON.stringify(info);
+            encryptAndUpsert(server, "client", payload, null);
+        },
+        async discoveryState(server) {
+            assertServerName(server);
+            const meta = getDecryptedRow(server, "discovery");
+            if (meta === undefined)
+                return undefined;
+            return JSON.parse(meta.plaintext);
+        },
+        async saveDiscoveryState(server, state) {
+            assertServerName(server);
+            const payload = JSON.stringify(state);
+            encryptAndUpsert(server, "discovery", payload, null);
+        },
+        async deleteAll(server) {
+            assertServerName(server);
+            deleteAllStmt.run(server);
+        },
+        startWatch() {
+            // No-op — no disk presence, no chokidar watch.
+            return Promise.resolve();
+        },
+        close() {
+            // No-op — does NOT own the db lifecycle. The caller (selectSecretStore)
+            // closes the shared secretsDb handle.
+            return Promise.resolve();
+        },
+    };
+}

package/node_modules/@comis/daemon/dist/wiring/oauth-preflight.js

@@ -25,11 +25,11 @@
  *
  * Distro detection (`/etc/os-release` parser + 5-distro install-hint switch)
  * is duplicated inline from `packages/cli/src/doctor/checks/oauth-health.ts`.
- * Per AGENTS.md §2.3 rule of three, two callers do not yet justify a shared
- * helper. If a third caller appears, extract the pair to
+ * Two callers do not yet justify a shared helper (rule of three). If a third
+ * caller appears, extract the pair to
  * `packages/agent/src/model/oauth-os-release.ts`.
  *
- * Per AGENTS.md §2.4 the logger is injected — no `@comis/infra` import.
+ * The logger is injected — no `@comis/infra` import.
  *
  * @module
  */
@@ -56,7 +56,7 @@ export function hasAnyOAuthAgent(agents) {
  * error (missing file, permission denied, malformed contents).
  *
  * Verbatim duplication from `oauth-health.ts` — see module JSDoc for the
- * AGENTS.md §2.3 deferral rationale.
+ * rule-of-three deferral rationale.
  */
 async function readOsRelease(path = "/etc/os-release") {
     try {
@@ -79,7 +79,7 @@ async function readOsRelease(path = "/etc/os-release") {
  * Produces a distro-aware install command for the system CA bundle.
  *
  * Verbatim duplication from `oauth-health.ts` — see module JSDoc for the
- * AGENTS.md §2.3 deferral rationale.
+ * rule-of-three deferral rationale.
  */
 function caCertificatesInstallHint(os) {
     if (!os)

package/node_modules/@comis/daemon/dist/wiring/obs-mcp-closures.d.ts

@@ -0,0 +1,39 @@
+import { assembleFleetHealthReport } from "../api/obs-handlers/index.js";
+/**
+ * The trust-flag-FREE obs.explain + obs.fleet.health MCP-client closures
+ * (operator-allowlisted `obs_explain` / `obs_fleet_health` tools). Extracted from
+ * daemon.ts `bootGateway` to keep daemon.ts within the ≤3000-line architecture cap.
+ *
+ * SECURITY (154-03 / 161-02): these closures run the SAME assemblers the admin RPC
+ * handlers delegate to, DIRECTLY under daemon authority — they do NOT go through the
+ * admin-gated obs.* RPC, do NOT inject `_trustLevel:"admin"`, and are NOT reached via
+ * daemonRpcForMcpClient. The only authorization boundary is the per-client
+ * `mcpClient.allowlist` (the MCP dispatcher's registration filter + live re-check)
+ * plus the digest-only/bounded report. `params` arrive already `_trustLevel`-stripped
+ * (the MCP dispatcher strips for every tool); the contract `request.parse` validates
+ * the shape (its `.refine` rejects an invalid call → the dispatcher's try/catch turns
+ * the throw into a generic `dispatch_error` sentinel, no raw leak) before the
+ * assembler reads any source.
+ *
+ * `dataDir` MUST be the ABSOLUTE boot data dir (never "."). `makeRealReader` builds
+ * `safePath(dataDir, "sessions"|"logs")` eagerly, and safePath rejects a relative base
+ * — a "." crashes boot with PathTraversalError.
+ *
+ * `clock` is the SAME ClockPort wired into the RPC handler deps (load-bearing,
+ * `deps.clock!`). `durableRuns` (FLEET-01/02/04, Phase 220-03) is the live durable-run
+ * store for the autonomy block — this closure bypasses buildRpcDispatchDeps (the RPC
+ * path already wires it at daemon.ts:893), so it is the NET-NEW thread; pass
+ * `boot.durableRunStore`. Absent (durability off) ⇒ honest degradation (the autonomy
+ * block is omitted), byte-identical with the offline path.
+ */
+type FleetAssemblerDeps = Parameters<typeof assembleFleetHealthReport>[0];
+export declare function buildObsMcpClientClosures(deps: {
+    dataDir: string;
+    obsStore: FleetAssemblerDeps["obsStore"];
+    clock: FleetAssemblerDeps["clock"];
+    durableRuns: FleetAssemblerDeps["durableRuns"];
+}): {
+    obsExplainForMcpClient: (params: Record<string, unknown>) => Promise<unknown>;
+    obsFleetHealthForMcpClient: (params: Record<string, unknown>) => Promise<unknown>;
+};
+export {};

package/node_modules/@comis/daemon/dist/wiring/obs-mcp-closures.js

@@ -0,0 +1,14 @@
+import { assembleIncidentReportFromSources, assembleFleetHealthReport, makeRealReader } from "../api/obs-handlers/index.js";
+import { ObsExplainContract, ObsFleetHealthContract } from "@comis/core";
+export function buildObsMcpClientClosures(deps) {
+    const reader = makeRealReader(deps.dataDir, deps.obsStore);
+    const obsExplainForMcpClient = (params) => {
+        const parsed = ObsExplainContract.request.parse(params);
+        return assembleIncidentReportFromSources(reader, deps.dataDir, parsed);
+    };
+    const obsFleetHealthForMcpClient = (params) => {
+        const parsed = ObsFleetHealthContract.request.parse(params);
+        return assembleFleetHealthReport({ obsStore: deps.obsStore, dataDir: deps.dataDir, clock: deps.clock, durableRuns: deps.durableRuns }, parsed.sinceHours ?? 24);
+    };
+    return { obsExplainForMcpClient, obsFleetHealthForMcpClient };
+}

package/node_modules/@comis/daemon/dist/wiring/preflight-doctor.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Preflight native-dependency doctor — extracted from `daemon.ts` to keep the
+ * composition root under its 3000-line architecture cap (the v2.25 audio wiring
+ * pushed daemon.ts to 3001; this self-contained, behavior-neutral probe is the
+ * natural extraction). `daemon.ts` re-exports `runPreflightDoctor` so its public
+ * surface (and `daemon.test.ts`'s `import … from "./daemon.js"`) is unchanged.
+ *
+ * The timestamp is read via `@comis/core`'s `systemNowDate()` (the sanctioned
+ * runtime-root clock indirection) rather than a bare `new Date()`: extracting
+ * this probe out of the globals-exempt `daemon.ts` bootstrap root would
+ * otherwise trip the `globals` architecture gate (Phase 196 CR-01). The helper
+ * keeps the same wall-clock behavior while routing the read through the
+ * classifier-exempt `packages/core/src/runtime/` root.
+ *
+ * @module
+ */
+import { type AutonomyConfig, type AutonomyProfileName, type AgentCapability, type AutonomyPreflightResult } from "@comis/core";
+interface PreflightProbeDatabase {
+    prepare(sql: string): {
+        get(): unknown;
+    };
+    close(): void;
+}
+type PreflightDatabaseCtor = new (path: string) => PreflightProbeDatabase;
+/**
+ * Probe better-sqlite3 before any subsystem init. A missing transitive
+ * `bindings` folder (known failure mode from partial npm upgrades) makes
+ * better-sqlite3 throw at first require, which otherwise surfaces as an
+ * opaque mid-boot crash and a systemd restart loop. Here we catch it up
+ * front and exit 78 (EX_CONFIG) with an actionable hint, so operators can
+ * repair instead of chasing a cascading failure.
+ */
+export declare function runPreflightDoctor(exitFn: (code: number) => void, opts?: {
+    stderrWrite?: (s: string) => void;
+    loadBetterSqlite3?: () => Promise<PreflightDatabaseCtor>;
+}): Promise<void>;
+/** The agent-config shape the boot-log builder reads (only the autonomy block). */
+interface AgentAutonomySlice {
+    readonly autonomy?: AutonomyConfig;
+}
+/**
+ * One per-agent record the boot banner logs at INFO — the legible resolved
+ * posture (PROFILE-03 / CLAUDE.md "promote load-bearing evidence to INFO").
+ * Carries exactly the four legibility facts (profile, enabled caps, the budget
+ * ceiling, the one field to change it) plus the M1 over-grant notice.
+ */
+export interface AutonomyBootLogRecord {
+    readonly agentId: string;
+    readonly profile: AutonomyProfileName;
+    readonly enabled: boolean;
+    /** The resolved orch:* caps the profile turned on. */
+    readonly capabilities: readonly AgentCapability[];
+    /** The per-root-run aggregate $ ceiling (the budget guard, §8.7). */
+    readonly aggregateBudgetUsd: number;
+    /** The ONE config field that changes all of the above — the legibility contract. */
+    readonly changeField: "autonomy.profile";
+    /** Present for `unattended` (Phase-217 mode-active notice) + `max` (M3 clamp notice). */
+    readonly m1Notice?: string;
+}
+/**
+ * Build the per-agent legible-posture records the boot banner logs at INFO.
+ *
+ * PURE — resolves each agent's `autonomy` block via {@link resolveAutonomy} and
+ * projects the four legibility facts + the M1 notice. One record per agent, in
+ * config order. The daemon logs each as an INFO line so an operator can read,
+ * from boot logs alone, exactly what every agent was granted and how to change
+ * it — without `logLevel: debug`.
+ *
+ * @param agents the daemon's agents config map (only `autonomy` is read).
+ */
+export declare function buildAutonomyBootLog(agents: Record<string, AgentAutonomySlice>): AutonomyBootLogRecord[];
+/**
+ * A `doctor` finding mirroring the file's existing finding shape (severity +
+ * message + hint + errorKind). The PROFILE-03 namespace-downshift finding is
+ * WARN-class — autonomy degrades to `assistant`, the daemon still serves — so it
+ * never exits the process (unlike the fatal better-sqlite3 probe above).
+ */
+export interface PreflightFinding {
+    readonly severity: "warn";
+    readonly message: string;
+    readonly hint: string;
+    readonly errorKind: "precondition";
+}
+/**
+ * Build the namespace-preflight downshift `doctor` finding (PROFILE-03).
+ *
+ * PURE — driven by the preflight-RESULT INPUT (the probe is Phase 211). Returns
+ * `undefined` when the preflight passed. When it failed, derives the finding's
+ * reason/hint from {@link degradeAutonomy} (a `standard` posture is the canonical
+ * "would have been autonomy-bearing" case) so the doctor finding and the
+ * resolver's surfaced WARN share ONE source of truth — same hint, same
+ * `errorKind`, no drift.
+ *
+ * @param preflight the host preconditions (210: caller-supplied; 211: probed).
+ */
+export declare function buildNamespaceDownshiftFinding(preflight: AutonomyPreflightResult): PreflightFinding | undefined;
+export {};