comisai 1.0.44 → 1.0.46

package/node_modules/@comis/cli/dist/commands/support-bundle.js

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `comis support-bundle` — assemble an offline, paste-ready support bundle.
+ *
+ * The command is the sanctioned throw/exit boundary for the bundle pipeline: it
+ * resolves the data dir + config paths, validates the flag combination, calls
+ * the offline orchestrator, and maps the `Result` to a named `ExitCode`. A
+ * written bundle is a success even when the triage is degraded or the bundle is
+ * partial — the degraded verdict is the content, not a failure. Only a bundle
+ * that could not be produced at all is a `GeneralFailure`, and a misused flag is
+ * a `UsageError`.
+ *
+ * In table format it prints the bundle path, the triage status, the reporter
+ * next-steps, the privacy notice, and the two copy-paste lines — the `tar`
+ * archive command and the `gh issue create` command. Those lines are PRINTED
+ * for the operator to run; the command never runs them itself, so the bundle is
+ * never transmitted or published on the operator's behalf.
+ *
+ * @module
+ */
+import * as os from "node:os";
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { systemGetEnv, systemNowMs } from "@comis/core";
+import { info, warn, error, json } from "../output/format.js";
+import { ExitCode } from "../util/exit-codes.js";
+import { resolveOfflineDataDir } from "../util/offline-obs.js";
+import { generateSupportBundle } from "../support-bundle/generate.js";
+/**
+ * Resolve default config paths from COMIS_CONFIG_PATHS or the standard
+ * locations. The environment is read via `systemGetEnv` (the sanctioned env
+ * reader — never a raw env global) so the globals architecture test passes, and
+ * the value is split on ":" exactly as the daemon and the doctor command split
+ * it. When the variable is unset, the standard candidate files that exist on
+ * disk are used.
+ */
+function resolveDefaultConfigPaths() {
+    const envPaths = systemGetEnv("COMIS_CONFIG_PATHS");
+    if (envPaths) {
+        return envPaths.split(":").filter((p) => p.length > 0);
+    }
+    const candidates = [
+        os.homedir() + "/.comis/config.yaml",
+        os.homedir() + "/.comis/config.local.yaml",
+        "/etc/comis/config.yaml",
+        "/etc/comis/config.local.yaml",
+    ];
+    return candidates.filter((p) => existsSync(p));
+}
+/**
+ * Register the `support-bundle` command on the program.
+ *
+ * Flags: `--since <hours>` (window, default 24), `--format table|json`
+ * (default table), `-c/--config <paths...>`, `--session <ref>`, and `--deep`
+ * (requires `--session`). `--session` focuses the bundle on one session and
+ * embeds its `explain.json` digest; `--deep` additionally embeds that session's
+ * redacted per-session trace bundle.
+ *
+ * @param program - The root Commander program
+ */
+export function registerSupportBundleCommand(program) {
+    program
+        .command("support-bundle")
+        .description("Assemble an offline, paste-ready support bundle (triage verdict, health findings, host facts) — works with a stopped daemon")
+        .option("--since <hours>", "Window in hours", "24")
+        .option("--format <format>", 'Output format: "table" or "json"', "table")
+        .option("-c, --config <paths...>", "Config file paths")
+        .option("--session <sessionKeyOrTraceId>", "Focus the bundle on one session — embeds its explain.json digest (add --deep for the full trace bundle)")
+        .option("--deep", "Include deep per-session evidence (requires --session)")
+        .action(async (options) => {
+        // Usage guard: --deep only means something with a --session to deepen.
+        if (options.deep && !options.session) {
+            error("--deep requires --session <sessionKeyOrTraceId>");
+            process.exit(ExitCode.UsageError);
+        }
+        const startedAtMs = systemNowMs();
+        const configPaths = options.config ?? resolveDefaultConfigPaths();
+        const dataDir = resolveOfflineDataDir();
+        // The window must be a positive number of hours. A non-numeric or
+        // non-positive value would otherwise ride through as NaN/≤0 with no
+        // feedback to the operator and misbehave the moment a fleet read consumes
+        // it — reject it at the boundary (the fleet window is likewise constrained
+        // to a positive number).
+        const sinceHours = Number.parseFloat(options.since);
+        if (!Number.isFinite(sinceHours) || sinceHours <= 0) {
+            error("--since must be a positive number of hours");
+            process.exit(ExitCode.UsageError);
+        }
+        const result = await generateSupportBundle({
+            dataDir,
+            configPaths,
+            sinceHours,
+            nowMs: startedAtMs,
+            ...(options.session !== undefined ? { session: options.session } : {}),
+            ...(options.deep === true ? { deep: true } : {}),
+        });
+        // The one hard failure: the bundle directory could not be produced.
+        if (!result.ok) {
+            error(`Support bundle could not be produced (${result.error.errorKind}): ${result.error.reason}`);
+            error(`hint: ${result.error.hint}`);
+            process.exit(ExitCode.GeneralFailure);
+        }
+        const { bundleDir, status, activeSignals, warnings, worstSessionKey } = result.value;
+        // Machine-readable surface: exactly the triage digest, nothing else.
+        if (options.format === "json") {
+            json({ bundleDir, status, activeSignals });
+            process.exit(ExitCode.Success);
+        }
+        // Human-readable surface.
+        const bundleName = basename(bundleDir);
+        const parentDir = dirname(bundleDir);
+        const durationMs = systemNowMs() - startedAtMs;
+        info(`Bundle written to: ${bundleDir}`);
+        info(`Triage status: ${status}`);
+        if (activeSignals.length > 0) {
+            info(`Active signals: ${activeSignals.join(", ")}`);
+        }
+        if (warnings.length > 0) {
+            warn(`${warnings.length} section(s) were partial — see manifest.json for details`);
+        }
+        // Reporter next-steps: what to do with the freshly-written bundle. The
+        // tar and gh lines are printed for the operator to run — the command
+        // never executes them, so nothing is transmitted or published here.
+        info("Next steps:");
+        info(`  1. Review the bundle, starting with ${bundleName}/issue-summary.md`);
+        info("  2. Compress it and attach the archive to your report:");
+        info(`       tar czf ${bundleName}.tar.gz -C ${parentDir} ${bundleName}`);
+        info("  3. Or open an issue directly from the summary:");
+        info(`       gh issue create --body-file ${bundleDir}/issue-summary.md`);
+        // Worst-session tip (CLI-side stopgap): when the operator did not focus a
+        // session, a best-effort local scan of the rollups may surface the most
+        // degraded recent session. Name it and the focused re-run so the operator
+        // can drill in — content-free (a sessionKey only), and omitted cleanly when
+        // nothing ranked.
+        if (worstSessionKey !== undefined) {
+            info(`Tip: the most-degraded session in a local scan is ${worstSessionKey}. ` +
+                `Re-run with --session ${worstSessionKey} --deep for a focused per-session bundle.`);
+        }
+        // Privacy notice: the default bundle is content-free by construction, but
+        // treat it as sensitive all the same. With --deep the bundle additionally
+        // embeds the redacted RAW session trajectory (session content, PII-adjacent),
+        // so the notice ESCALATES to the trace-bundle discipline — strictly more
+        // sensitive than the digest, and never safe to post publicly.
+        if (options.deep === true) {
+            warn("Privacy (--deep): this bundle embeds the per-session trace export — redacted " +
+                "RAW session trajectory (session content, PII-adjacent) that is strictly more " +
+                "sensitive than the default digest bundle. Redaction is heuristic, not a " +
+                "guarantee — share it ONLY with authorized engineers over a secure channel and " +
+                "DELETE it after triage.");
+        }
+        else {
+            warn("Privacy: this bundle excludes secrets, message bodies, and raw config " +
+                "values by construction, but treat it as sensitive — share it only " +
+                "with authorized engineers over a secure channel and delete it after triage.");
+        }
+        info(`Support bundle ready in ${durationMs}ms.`);
+        process.exit(ExitCode.Success);
+    });
+}

package/node_modules/@comis/cli/dist/commands/whoami.d.ts

@@ -1,5 +1,5 @@
 /**
- * `comis whoami` — operator/agent CLI for the Phase-215 `capabilities.introspect`
+ * `comis whoami` — operator/agent CLI for the `capabilities.introspect`
  * read: the run's resolved orchestration capabilities + the remaining per-root
  * budget/quota.
  *
@@ -16,7 +16,7 @@
  * never raw `client.call`. `callTyped` runs `CapabilitiesIntrospectContract`
  * request + response parse.
  *
- * LIVE-ONLY (Pitfall 4 / G5 / T-215-13): unlike `comis explain`, `whoami` has NO
+ * LIVE-ONLY: unlike `comis explain`, `whoami` has NO
  * `--offline` mode and NO unreachable-fallback. The remaining budget/quota lives
  * ONLY in the running daemon's `BoundedAutonomy` maps — never on disk — so a
  * post-mortem reconstruction is impossible. On an unreachable (or token-rejected)

package/node_modules/@comis/cli/dist/commands/whoami.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * `comis whoami` — operator/agent CLI for the Phase-215 `capabilities.introspect`
+ * `comis whoami` — operator/agent CLI for the `capabilities.introspect`
  * read: the run's resolved orchestration capabilities + the remaining per-root
  * budget/quota.
  *
@@ -17,7 +17,7 @@
  * never raw `client.call`. `callTyped` runs `CapabilitiesIntrospectContract`
  * request + response parse.
  *
- * LIVE-ONLY (Pitfall 4 / G5 / T-215-13): unlike `comis explain`, `whoami` has NO
+ * LIVE-ONLY: unlike `comis explain`, `whoami` has NO
  * `--offline` mode and NO unreachable-fallback. The remaining budget/quota lives
  * ONLY in the running daemon's `BoundedAutonomy` maps — never on disk — so a
  * post-mortem reconstruction is impossible. On an unreachable (or token-rejected)

package/node_modules/@comis/cli/dist/doctor/checks/channel-health.d.ts

@@ -7,9 +7,9 @@
  * doctor resolution substitutes them the way daemon boot does: process env
  * -> `~/.comis/.env` -> the encrypted secret store. A reference nothing
  * resolved is exactly what breaks the adapter at runtime, so that — not a
- * bare env-var probe — is what this check reports. (The env-only probe used
- * to claim "Missing telegram credentials" on a live deployment whose token
- * sits in the encrypted store; 2026-06-12 C1 live finding.)
+ * bare env-var probe — is what this check reports. (An env-only probe would
+ * claim "Missing telegram credentials" on a live deployment whose token
+ * sits in the encrypted store.)
  *
  * Does NOT perform live API validation — resolution presence only.
  *

package/node_modules/@comis/cli/dist/doctor/checks/channel-health.js

@@ -8,9 +8,9 @@
  * doctor resolution substitutes them the way daemon boot does: process env
  * -> `~/.comis/.env` -> the encrypted secret store. A reference nothing
  * resolved is exactly what breaks the adapter at runtime, so that — not a
- * bare env-var probe — is what this check reports. (The env-only probe used
- * to claim "Missing telegram credentials" on a live deployment whose token
- * sits in the encrypted store; 2026-06-12 C1 live finding.)
+ * bare env-var probe — is what this check reports. (An env-only probe would
+ * claim "Missing telegram credentials" on a live deployment whose token
+ * sits in the encrypted store.)
  *
  * Does NOT perform live API validation — resolution presence only.
  *

package/node_modules/@comis/cli/dist/doctor/checks/lcd-health.d.ts

@@ -1,16 +1,18 @@
 /**
- * LCD store health check for comis doctor — DOC-01.
+ * LCD store health check for comis doctor.
  *
  * Six read-only SQL scan classes against memory.db that give operators
- * store-integrity visibility without raw SQL access. Designed per
- * design/lcd-v3-unified-substrate.md §6.11 corruption classification.
+ * store-integrity visibility without raw SQL access. Each scan class
+ * targets one known corruption shape (see the enumeration on the check
+ * export below).
  *
  * Privacy: all finding `message` fields carry ONLY counts, UUIDs, and
  * errorKind strings — never `content` column values, message text, or
- * summary plaintext (threat T-170-02-01).
+ * summary plaintext.
  *
- * Safety: opens memory.db with `readonly: true` (threat T-170-02-02)
- * and sets `busy_timeout = 100` (threat T-170-02-03).
+ * Safety: opens memory.db with `readonly: true` so a scan can never mutate
+ * the store, and sets `busy_timeout = 100` so a locked store degrades the
+ * scan instead of hanging the CLI.
  *
  * @module
  */

package/node_modules/@comis/cli/dist/doctor/checks/lcd-health.js

@@ -1,17 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * LCD store health check for comis doctor — DOC-01.
+ * LCD store health check for comis doctor.
  *
  * Six read-only SQL scan classes against memory.db that give operators
- * store-integrity visibility without raw SQL access. Designed per
- * design/lcd-v3-unified-substrate.md §6.11 corruption classification.
+ * store-integrity visibility without raw SQL access. Each scan class
+ * targets one known corruption shape (see the enumeration on the check
+ * export below).
  *
  * Privacy: all finding `message` fields carry ONLY counts, UUIDs, and
  * errorKind strings — never `content` column values, message text, or
- * summary plaintext (threat T-170-02-01).
+ * summary plaintext.
  *
- * Safety: opens memory.db with `readonly: true` (threat T-170-02-02)
- * and sets `busy_timeout = 100` (threat T-170-02-03).
+ * Safety: opens memory.db with `readonly: true` so a scan can never mutate
+ * the store, and sets `busy_timeout = 100` so a locked store degrades the
+ * scan instead of hanging the CLI.
  *
  * @module
  */
@@ -131,8 +133,8 @@ function scanFtsDrift(db) {
         (SELECT COUNT(*) FROM lcd_summaries) - (SELECT COUNT(*) FROM lcd_summaries_fts) AS sum_drift
     `)
         .get();
-    // WR-03: negative drift = orphaned contentless FTS shadow rows, which are
-    // EXPECTED after a Phase-164 deleteConversationLcd / `sessions reset` (the
+    // Negative drift = orphaned contentless FTS shadow rows, which are
+    // EXPECTED after a deleteConversationLcd / `sessions reset` (the
     // contentless FTS5 table has no FK and is not pruned on message delete). Only
     // POSITIVE drift — messages/summaries present but not yet indexed — is the real
     // corruption signal. Floor at 0 so a healthy post-reset store stays clean.
@@ -155,9 +157,9 @@ function scanFtsDrift(db) {
 /**
  * Detect lcd_messages or lcd_summaries rows with NULL tenant_id or agent_id.
  *
- * These violate the R4 isolation scope invariant (Phase 132-03) — affected
- * rows will be invisible to scope-filtered queries and may leak across
- * agent boundaries.
+ * These violate the R4 isolation scope invariant (every row must carry its
+ * tenant/agent scope) — affected rows will be invisible to scope-filtered
+ * queries and may leak across agent boundaries.
  */
 function scanR4Anomalies(db) {
     const row = db
@@ -193,9 +195,10 @@ function scanR4Anomalies(db) {
  * its scope — equal in single-epoch steady state, strictly less once a prior
  * epoch has accumulated. `ingested_live_len` GREATER than the persisted count is
  * therefore impossible in normal operation and signals a corrupt / hand-edited
- * cursor. Phase-164 note: a cursor with `ingested_live_len = 0` (or small) while
- * many durable messages exist is a NORMAL fresh epoch / continue-append state and
- * is correctly NOT flagged (0 <= msg_count). Content-free: counts only.
+ * cursor. Note: under the epoch model a cursor with `ingested_live_len = 0` (or
+ * small) while many durable messages exist is a NORMAL fresh epoch /
+ * continue-append state and is correctly NOT flagged (0 <= msg_count).
+ * Content-free: counts only.
  */
 function scanCursorInconsistencies(db) {
     const rows = db
@@ -252,7 +255,7 @@ export const lcdHealthCheck = {
         try {
             db = new Database(dbPath, { readonly: true });
             // Short timeout — treat BUSY as a "scan could not acquire read lock"
-            // degradation rather than hanging the CLI (threat T-170-02-03).
+            // degradation rather than hanging the CLI.
             db.pragma("busy_timeout = 100");
             findings.push(...scanOrphanedSummaries(db));
             findings.push(...scanDanglingRefs(db));

package/node_modules/@comis/cli/dist/doctor/checks/msteams-health.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Microsoft Teams health check for `comis doctor`.
+ *
+ * Teams is a webhook channel: it is exempt from the health monitor's stale-reap
+ * (a webhook has no socket to go quiet), so a dead ingress would never surface
+ * through the monitor. An operator therefore needs a one-command answer to "is
+ * my Teams bot actually receiving?" — which this check provides via four probes:
+ *
+ *   1. creds-parse    — authMode-aware credential presence/resolution
+ *                       (secret → appPassword resolved; certificate → certPath
+ *                       present/readable; managedIdentity → clientId present).
+ *   2. endpoint       — an UNAUTH request to the mounted
+ *                       /channels/msteams/api/messages route: 401/405 means the
+ *                       ingress is mounted and rejecting unauth (good); 404 means
+ *                       the route is absent (misconfigured).
+ *   3. recent-inbound — the INBOUND-ONLY lastInboundAt read over the channel-
+ *                       status RPC. It is NEVER the conflated last-activity
+ *                       signal: an outbound send bumps last-activity, so a
+ *                       send-only bot would read as healthy on last-activity
+ *                       while its ingress is dead. The
+ *                       probe reads the dedicated inbound signal so that case is
+ *                       caught.
+ *   4. tenant-present — Teams requires a single-tenant directory (tenant) ID.
+ *
+ * The endpoint + recent-inbound probes degrade to `skip` when the daemon/gateway
+ * is unreachable (mirrors the other daemon-dependent doctor checks). The probe
+ * never calls the adapter directly — the daemon owns live adapter state and
+ * surfaces it over RPC.
+ *
+ * @module
+ */
+import type { DoctorCheck } from "../types.js";
+/**
+ * Doctor check: Microsoft Teams health.
+ *
+ * Never throws — every probe returns a finding (or degrades to `skip` when the
+ * daemon/gateway is unreachable). Returns a single `skip` when Teams is not
+ * enabled or the config did not resolve.
+ */
+export declare const msteamsHealthCheck: DoctorCheck;

package/node_modules/@comis/cli/dist/doctor/checks/msteams-health.js

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams health check for `comis doctor`.
+ *
+ * Teams is a webhook channel: it is exempt from the health monitor's stale-reap
+ * (a webhook has no socket to go quiet), so a dead ingress would never surface
+ * through the monitor. An operator therefore needs a one-command answer to "is
+ * my Teams bot actually receiving?" — which this check provides via four probes:
+ *
+ *   1. creds-parse    — authMode-aware credential presence/resolution
+ *                       (secret → appPassword resolved; certificate → certPath
+ *                       present/readable; managedIdentity → clientId present).
+ *   2. endpoint       — an UNAUTH request to the mounted
+ *                       /channels/msteams/api/messages route: 401/405 means the
+ *                       ingress is mounted and rejecting unauth (good); 404 means
+ *                       the route is absent (misconfigured).
+ *   3. recent-inbound — the INBOUND-ONLY lastInboundAt read over the channel-
+ *                       status RPC. It is NEVER the conflated last-activity
+ *                       signal: an outbound send bumps last-activity, so a
+ *                       send-only bot would read as healthy on last-activity
+ *                       while its ingress is dead. The
+ *                       probe reads the dedicated inbound signal so that case is
+ *                       caught.
+ *   4. tenant-present — Teams requires a single-tenant directory (tenant) ID.
+ *
+ * The endpoint + recent-inbound probes degrade to `skip` when the daemon/gateway
+ * is unreachable (mirrors the other daemon-dependent doctor checks). The probe
+ * never calls the adapter directly — the daemon owns live adapter state and
+ * surfaces it over RPC.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { ChannelsHealthContract, systemNowMs } from "@comis/core";
+import { describeConfigUnavailable } from "../config-resolve.js";
+import { isDaemonRunning } from "../../sync-tooling/daemon-guard.js";
+import { withClient, callTyped } from "../../client/rpc-client.js";
+const CATEGORY = "channels";
+const CHANNEL_TYPE = "msteams";
+/** The mounted inbound route (relative to the gateway origin). */
+const MSTEAMS_ENDPOINT_PATH = "/channels/msteams/api/messages";
+/** Endpoint-probe HTTP timeout. */
+const ENDPOINT_PROBE_TIMEOUT_MS = 3_000;
+/** Liveness-probe timeout before the recent-inbound RPC. */
+const LIVENESS_PROBE_TIMEOUT_MS = 1_000;
+/**
+ * Recent-inbound recency window. A `warn` (never `fail`): a webhook bot may
+ * legitimately be quiet, but zero inbound in a full day on a health check is
+ * worth flagging as a possible dead ingress. The continuous, tunable liveness
+ * monitor is a separate concern; this is the point-in-time doctor read.
+ */
+const RECENT_INBOUND_WINDOW_MS = 24 * 60 * 60 * 1000;
+const RECENT_INBOUND_WINDOW_HOURS = RECENT_INBOUND_WINDOW_MS / 3_600_000;
+/** A credential value is blank when absent or all-whitespace. */
+function isBlank(value) {
+    return !value || value.trim() === "";
+}
+/**
+ * appPassword is present when it is a non-blank string (an inline or resolved
+ * `${VAR}`) or a SecretRef object (its resolution is a store concern, not
+ * verifiable offline — presence of the object is what this probe asserts).
+ */
+function appPasswordPresent(value) {
+    if (typeof value === "string")
+        return value.trim() !== "";
+    return value !== undefined && value !== null;
+}
+/** Compact finding constructor (all msteams findings are non-repairable). */
+function finding(status, check, message, suggestion) {
+    return {
+        category: CATEGORY,
+        check,
+        status,
+        message,
+        ...(suggestion !== undefined ? { suggestion } : {}),
+        repairable: false,
+    };
+}
+// ---------------------------------------------------------------------------
+// Probe 1: creds-parse (authMode-aware)
+// ---------------------------------------------------------------------------
+function credsParseFinding(msteams, context) {
+    const check = "Teams credentials";
+    const authMode = msteams.authMode ?? "secret";
+    if (authMode === "certificate") {
+        if (isBlank(msteams.certPath)) {
+            return finding("fail", check, "certPath is empty but certificate mode requires a client certificate path", "Set channels.msteams.certPath to the client certificate path");
+        }
+        // Best-effort readability. The daemon may run on a different host than the
+        // CLI, so a not-found path is a warn (expected on split-host), not a fail.
+        if (!existsSync(msteams.certPath)) {
+            return finding("warn", check, `certPath is set (${msteams.certPath}) but no readable file exists there on this host`, "If the daemon runs on another host this is expected; otherwise fix channels.msteams.certPath");
+        }
+        return finding("pass", check, "certificate credentials present (certPath readable)");
+    }
+    if (authMode === "managedIdentity") {
+        if (isBlank(msteams.managedIdentityClientId)) {
+            return finding("fail", check, "managedIdentityClientId is empty but managed-identity mode requires it", "Set channels.msteams.managedIdentityClientId to the managed-identity client ID");
+        }
+        return finding("pass", check, "managed-identity credentials present");
+    }
+    // secret mode (default): appPassword must be present AND, if a ${VAR} ref, resolved.
+    const unresolvedAppPassword = (context.configResolution?.unresolvedRefs ?? []).find((ref) => ref.path.startsWith("channels.msteams.appPassword"));
+    if (unresolvedAppPassword !== undefined) {
+        return finding("fail", check, `Unresolved appPassword reference: \${${unresolvedAppPassword.varName}} at ${unresolvedAppPassword.path}` +
+            " — not in env, ~/.comis/.env, or the encrypted secret store", "Set the variable in the environment or store it via comis secrets set");
+    }
+    if (!appPasswordPresent(msteams.appPassword)) {
+        return finding("fail", check, "appPassword is empty but secret mode requires an app password / client secret", "Set channels.msteams.appPassword (or a ${VAR} ref resolvable via env or comis secrets set)");
+    }
+    return finding("pass", check, "secret-mode credentials resolved");
+}
+// ---------------------------------------------------------------------------
+// Probe 2: endpoint-reachable
+// ---------------------------------------------------------------------------
+async function endpointReachableFinding(gatewayUrl) {
+    const check = "Teams endpoint";
+    if (gatewayUrl === undefined) {
+        return finding("skip", check, "Endpoint not checked — no gateway URL configured");
+    }
+    const url = `${gatewayUrl.replace(/\/+$/, "")}${MSTEAMS_ENDPOINT_PATH}`;
+    let status;
+    try {
+        // Unauth probe: no Authorization header. The ingress rejects at its
+        // bearer-presence pre-gate (401) BEFORE reading a body — no secret is sent
+        // and no body is processed, so this reads only the status code.
+        const response = await fetch(url, {
+            method: "POST",
+            signal: AbortSignal.timeout(ENDPOINT_PROBE_TIMEOUT_MS),
+        });
+        status = response.status;
+    }
+    catch {
+        // Connection refused / timeout / DNS — the daemon or gateway is unreachable.
+        return finding("skip", check, `Endpoint not reachable at ${url} — daemon/gateway may be down`);
+    }
+    if (status === 401 || status === 405) {
+        return finding("pass", check, `Ingress mounted at ${MSTEAMS_ENDPOINT_PATH} (rejects an unauthenticated request with ${status})`);
+    }
+    if (status === 404) {
+        return finding("fail", check, `The inbound route ${MSTEAMS_ENDPOINT_PATH} returned 404 — the Teams ingress is not mounted`, "Ensure the Teams channel is enabled so the gateway mounts its ingress (check the daemon startup logs)");
+    }
+    return finding("warn", check, `The unauth probe to ${MSTEAMS_ENDPOINT_PATH} returned an unexpected ${status} (expected 401/405 mounted, or 404 absent)`, "Inspect the gateway route table and the daemon logs");
+}
+// ---------------------------------------------------------------------------
+// Probe 3: recent-inbound (INBOUND-ONLY lastInboundAt, never last-activity)
+// ---------------------------------------------------------------------------
+async function recentInboundFinding() {
+    const check = "Teams recent inbound";
+    // Only probe a daemon that is actually up — a down daemon is the daemon
+    // check's signal, not a recent-inbound verdict.
+    const daemonUp = await isDaemonRunning(LIVENESS_PROBE_TIMEOUT_MS);
+    if (!daemonUp) {
+        return finding("skip", check, "Recent-inbound not checked — daemon not reachable");
+    }
+    let lastInboundAt;
+    let found = false;
+    try {
+        const health = await withClient((client) => callTyped(client, ChannelsHealthContract, {}));
+        const entry = health.channels.find((c) => c.channelType === CHANNEL_TYPE);
+        if (entry !== undefined) {
+            found = true;
+            lastInboundAt = entry.lastInboundAt;
+        }
+    }
+    catch (e) {
+        return finding("skip", check, `Recent-inbound not checked — channel-status RPC failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!found) {
+        return finding("warn", check, "No Teams adapter is reporting health — the channel may be enabled in config but not running", "Check that the Teams adapter started (see the daemon/channel doctor findings and the daemon logs)");
+    }
+    if (lastInboundAt === null || lastInboundAt === undefined) {
+        // Null even when last-activity may be fresh: a send-only bot. Webhook
+        // channels are stale-reap-exempt, so this inbound-only signal — not
+        // last-activity — is the liveness check for a dead ingress.
+        return finding("warn", check, "No inbound Teams activity recorded — the ingress has received nothing. This inbound-only signal (not last-activity) is the liveness check, since a webhook channel is exempt from stale detection.", `Verify the Bot Framework messaging endpoint points at this gateway's ${MSTEAMS_ENDPOINT_PATH} route`);
+    }
+    const ageMs = systemNowMs() - lastInboundAt;
+    if (ageMs > RECENT_INBOUND_WINDOW_MS) {
+        return finding("warn", check, `Last inbound Teams activity was ${Math.floor(ageMs / 60_000)} min ago, beyond the ${RECENT_INBOUND_WINDOW_HOURS}h recency window`, "If you expect steady inbound traffic, the ingress may be dead — verify the messaging endpoint and the app registration");
+    }
+    return finding("pass", check, `Recent inbound Teams activity within the last ${RECENT_INBOUND_WINDOW_HOURS}h`);
+}
+// ---------------------------------------------------------------------------
+// Probe 4: tenant-present
+// ---------------------------------------------------------------------------
+function tenantPresentFinding(msteams) {
+    const check = "Teams tenant";
+    if (isBlank(msteams.tenantId)) {
+        return finding("fail", check, "tenantId is not set — Teams requires a single-tenant directory (tenant) ID", "Set channels.msteams.tenantId to your Entra directory (tenant) ID");
+    }
+    return finding("pass", check, "tenantId present");
+}
+/**
+ * Doctor check: Microsoft Teams health.
+ *
+ * Never throws — every probe returns a finding (or degrades to `skip` when the
+ * daemon/gateway is unreachable). Returns a single `skip` when Teams is not
+ * enabled or the config did not resolve.
+ */
+export const msteamsHealthCheck = {
+    id: "msteams-health",
+    name: "Microsoft Teams",
+    run: async (context) => {
+        const channels = context.config?.channels;
+        const msteams = channels?.msteams;
+        if (msteams === undefined) {
+            // A valid config always carries a channels section (schema defaults), so
+            // reaching here means the config itself did not resolve — say WHY.
+            const why = describeConfigUnavailable(context.configResolution);
+            return [
+                finding("skip", "Teams config", why !== undefined
+                    ? `Teams health not checked — ${why}`
+                    : "Microsoft Teams not configured"),
+            ];
+        }
+        if (msteams.enabled !== true) {
+            return [finding("skip", "Teams enabled", "Microsoft Teams channel not enabled")];
+        }
+        return [
+            credsParseFinding(msteams, context),
+            tenantPresentFinding(msteams),
+            await endpointReachableFinding(context.gatewayUrl),
+            await recentInboundFinding(),
+        ];
+    },
+};

package/node_modules/@comis/cli/dist/doctor/checks/oauth-health.js

@@ -34,17 +34,17 @@ import { stat, readFile } from "node:fs/promises";
 // has zero @comis/agent imports.
 import { createFileLock, redactEmailForLog, rewriteOAuthError, runOAuthTlsPreflight, selectOAuthCredentialStore, systemGetEnv, systemNowMs, AuthListContract } from "@comis/core";
 import { formatRelativeExpiry } from "../../output/relative-time.js";
-// OBS-4 (live VPS 2026-06-19): in encrypted mode the CLI can't bootstrap the
-// store, but a RUNNING daemon can — so the profile-expiry check routes through
-// the daemon's auth.list RPC (token-free projection) instead of skipping.
+// In encrypted mode the CLI can't bootstrap the store, but a RUNNING daemon
+// can — so the profile-expiry check routes through the daemon's auth.list RPC
+// (token-free projection) instead of skipping.
 import { isDaemonRunning } from "../../sync-tooling/daemon-guard.js";
 import { withClient, callTyped } from "../../client/rpc-client.js";
 const CATEGORY = "oauth";
 const NEAR_EXPIRY_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 const REFRESH_TEST_TIMEOUT_MS = 10_000;
 const TLS_PREFLIGHT_TIMEOUT_MS = 5_000;
-// Public OpenAI Codex client_id — same value pi-ai uses; using our own
-// would fingerprint Comis traffic in OpenAI's logs.
+// Public OpenAI Codex client_id shared by Codex-compatible clients — using
+// a Comis-specific value would fingerprint Comis traffic in OpenAI's logs.
 const OPENAI_CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 const OPENAI_TOKEN_URL = "https://auth.openai.com/oauth/token";
 const CA_BUNDLE_PATHS = [
@@ -87,9 +87,9 @@ async function checkProfiles(context) {
         // SECRETS_MASTER_KEY), but a RUNNING daemon reads it — so route the
         // per-profile expiry check through the daemon's auth.list RPC (the same
         // token-free projection `comis auth list` uses). Only skip when the daemon
-        // is unreachable (then doctor genuinely cannot read from the CLI). OBS-4:
-        // doctor used to skip unconditionally in encrypted mode, so OAuth expiry
-        // health was invisible in the production posture — exactly when you'd want it.
+        // is unreachable (then doctor genuinely cannot read from the CLI).
+        // Skipping unconditionally in encrypted mode would make OAuth expiry
+        // health invisible in the production posture — exactly when you'd want it.
         const daemonUp = await isDaemonRunning(1000);
         if (!daemonUp) {
             return [