@ouro.bot/cli 0.1.0-alpha.730 → 0.1.0-alpha.731

package/dist/heart/daemon/doctor.js

@@ -35,6 +35,9 @@ const nerves_1 = require("../../nerves");
 const config_1 = require("../../rsvp/config");
 const cutover_1 = require("../../rsvp/cutover");
 const diagnostics_1 = require("../../rsvp/diagnostics");
+const hosted_cache_sync_1 = require("../../mailroom/hosted-cache-sync");
+const search_cache_1 = require("../../mailroom/search-cache");
+const prunable_bundle_1 = require("./prunable-bundle");
 const DEFAULT_BLUEBUBBLES_REQUEST_TIMEOUT_MS = 30_000;
 const DEFAULT_BLUEBUBBLES_PORT = 18_790;
 const DEFAULT_BLUEBUBBLES_WEBHOOK_PATH = "/bluebubbles-webhook";
@@ -87,11 +90,11 @@ async function checkDaemon(deps) {
     }
     return { name: "Daemon", checks };
 }
-/** Discover all *.ouro directories under bundlesRoot. */
+/** Discover doctor candidates: *.ouro directories with a present agent.json. */
 function discoverAgents(deps) {
     if (!deps.existsSync(deps.bundlesRoot))
         return [];
-    return deps.readdirSync(deps.bundlesRoot).filter((name) => name.endsWith(".ouro"));
+    return deps.readdirSync(deps.bundlesRoot).filter((name) => name.endsWith(".ouro") && deps.existsSync(`${deps.bundlesRoot}/${name}/agent.json`));
 }
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -206,13 +209,17 @@ function senseFreshnessOverride(deps, agentDir, sense) {
  * A sense opts in by calling this with its inbound log directory.
  */
 function senseInboundDeliveryCheck(input) {
+    const result = senseInboundDeliveryResult(input);
+    return { id: `senses.${input.sense}.inbound_liveness`, label: `${input.agentDir} ${input.sense} inbound delivery`, status: result.status, detail: result.detail };
+}
+function senseInboundDeliveryResult(input) {
     const suffix = input.logSuffix ?? ".ndjson";
-    return pipelineLivenessCheck({
-        id: `senses.${input.sense}.inbound_liveness`,
-        label: `${input.agentDir} ${input.sense} inbound delivery`,
+    const probe = (0, freshness_1.observeAppendPerEventStore)(input.inboundDir, input.deps, { suffix, maxEntries: SENSE_DELIVERY_MAX_LOG_SCAN });
+    return (0, freshness_1.evaluateFreshness)({
         activity: `${input.sense} inbound delivery`,
         unit: "inbound message",
-        probe: (0, freshness_1.observeAppendPerEventStore)(input.inboundDir, input.deps, { suffix, maxEntries: SENSE_DELIVERY_MAX_LOG_SCAN }),
+        observation: probe.observation,
+        provenance: probe.provenance,
         thresholds: (0, freshness_1.resolveFreshnessThresholds)(exports.DEFAULT_SENSE_DELIVERY_THRESHOLDS, senseFreshnessOverride(input.deps, input.agentDir, input.sense)),
         remediation: input.remediation,
         configuredSinceMs: input.configuredSincePath ? pathMtimeMs(input.deps, input.configuredSincePath) : null,
@@ -220,6 +227,57 @@ function senseInboundDeliveryCheck(input) {
         nowMs: input.nowMs,
     });
 }
+const DEFINITIVE_BLUEBUBBLES_FAILURES = new Set([
+    "auth-failure",
+    "rate-limit",
+    "server-error",
+    "usage-limit",
+]);
+const DEFINITIVE_BLUEBUBBLES_WEBHOOK_STATES = new Set([
+    "missing",
+    "drifted",
+    "auth-failed",
+    "malformed",
+    "listener-not-ready",
+]);
+function blueBubblesUpstreamEvidence(probe) {
+    if (probe.ok)
+        return "healthy";
+    if (DEFINITIVE_BLUEBUBBLES_FAILURES.has(probe.classification)) {
+        return "definitive-fault";
+    }
+    return "unavailable";
+}
+function blueBubblesInboundDeliveryCheck(input, evidence) {
+    const result = senseInboundDeliveryResult(input);
+    const base = {
+        id: "senses.bluebubbles.inbound_liveness",
+        label: `${input.agentDir} bluebubbles inbound delivery`,
+    };
+    if (result.state !== "stale" && result.state !== "never") {
+        return { ...base, status: result.status, detail: result.detail };
+    }
+    const webhookDefinitive = DEFINITIVE_BLUEBUBBLES_WEBHOOK_STATES.has(evidence.webhook);
+    if (evidence.upstream === "definitive-fault" || webhookDefinitive) {
+        const corroboration = evidence.webhook === "missing"
+            ? "missing owned webhook corroborates the silence"
+            : webhookDefinitive
+                ? `${evidence.webhook} owned-webhook evidence corroborates the silence`
+                : "a definitive upstream fault corroborates the silence";
+        return { ...base, status: "fail", detail: `${corroboration}; ${result.detail}` };
+    }
+    const orientation = evidence.upstream === "healthy" && evidence.webhook === "exact"
+        ? "no recent inbound was observed; upstream and exact owned webhook are healthy"
+        : evidence.upstream === "not-run"
+            ? "no recent inbound was observed; infrastructure probes were not run, so delivery is unverified"
+            : "no recent inbound was observed; infrastructure probes were unavailable, so delivery is unverified";
+    const observed = result.detail.replace(/; fix: .*$/u, "");
+    return {
+        ...base,
+        status: "warn",
+        detail: `${orientation}; quiet and delivery failure are indistinguishable without a new message; doctor did not send a test message; ${observed}`,
+    };
+}
 function checkAgents(deps) {
     const checks = [];
     if (!deps.existsSync(deps.bundlesRoot)) {
@@ -228,16 +286,12 @@ function checkAgents(deps) {
     }
     const agents = discoverAgents(deps);
     if (agents.length === 0) {
-        checks.push({ label: "agent bundles", status: "warn", detail: "no *.ouro bundles found" });
+        checks.push({ label: "agent bundles", status: "warn", detail: "no agent bundles found" });
         return { name: "Agents", checks };
     }
     for (const agentDir of agents) {
         const agentPath = `${deps.bundlesRoot}/${agentDir}`;
         const configPath = `${agentPath}/agent.json`;
-        if (!deps.existsSync(configPath)) {
-            checks.push({ label: `${agentDir}/agent.json`, status: "fail", detail: "missing" });
-            continue;
-        }
         let config;
         try {
             config = JSON.parse(deps.readFileSync(configPath));
@@ -414,6 +468,7 @@ async function checkSenses(deps) {
                     detail: serverUrl,
                 });
                 let upstreamContext = "upstream probe not run in this pass";
+                let infrastructure = { upstream: "not-run", webhook: null };
                 if (deps.fetchImpl) {
                     const requestTimeoutMs = numberField(bluebubblesChannel, "requestTimeoutMs", DEFAULT_BLUEBUBBLES_REQUEST_TIMEOUT_MS);
                     const probe = await (0, bluebubbles_health_diagnostics_1.probeBlueBubblesHealth)({
@@ -430,6 +485,7 @@ async function checkSenses(deps) {
                     upstreamContext = probe.ok
                         ? "upstream probe reachable — which does not prove inbound delivery"
                         : "upstream probe failing";
+                    infrastructure = { ...infrastructure, upstream: blueBubblesUpstreamEvidence(probe) };
                     const webhook = await (0, webhook_registration_1.inspectBlueBubblesWebhookRegistration)({
                         serverUrl,
                         password,
@@ -446,9 +502,10 @@ async function checkSenses(deps) {
                         status: webhook.ok ? "pass" : "fail",
                         detail: webhook.detail,
                     });
+                    infrastructure = { ...infrastructure, webhook: webhook.state };
                 }
                 const bluebubblesStateRoot = `${deps.bundlesRoot}/${agentDir}/state/senses/bluebubbles`;
-                checks.push(senseInboundDeliveryCheck({
+                checks.push(blueBubblesInboundDeliveryCheck({
                     deps,
                     agentDir,
                     sense: "bluebubbles",
@@ -457,7 +514,7 @@ async function checkSenses(deps) {
                     context: upstreamContext,
                     remediation: "no iMessage is reaching this agent — confirm the BlueBubbles server's configured webhook URL/port matches the port this daemon is listening on (a stale webhook port is the known cause), then re-attach with `ouro connect bluebubbles --agent <agent>`",
                     nowMs: Date.now(),
-                }));
+                }, infrastructure));
             }
             if (sense === "mail" && senseObj.enabled === true) {
                 const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: true });
@@ -957,7 +1014,29 @@ async function checkMailroom(deps) {
             detail: `${mailboxes.length} mailbox${mailboxes.length === 1 ? "" : "es"}, ${sourceGrants.length} source grant${sourceGrants.length === 1 ? "" : "s"}, ${listing.count} message${listing.count === 1 ? "" : "s"} stored (cumulative — not a liveness signal)`,
         });
         /* v8 ignore stop */
-        checks.push(mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing, await resolveMailStore(agentDir)));
+        const store = await resolveMailStore(agentDir);
+        if (store.hosted === null) {
+            checks.push({
+                id: "mail.ingest_liveness",
+                label: `${agentDir} mail ingest liveness`,
+                status: store.status,
+                detail: `mail store mode is unverified because fresh runtime credentials are unavailable: ${store.detail}; local-file and hosted liveness were not inferred from stale cached configuration`,
+            });
+            checks.push({
+                id: "mail.cache_authority",
+                label: `${agentDir} hosted mail cache authority`,
+                status: store.status,
+                detail: `fresh runtime credentials are unavailable: ${store.detail}; hosted authority was not probed from stale cached coordinates`,
+            });
+            continue;
+        }
+        const authorityCheck = store.hosted && deps.observeHostedMailAuthority
+            ? await hostedMailCacheAuthorityCheck(deps, agentDir, store)
+            : undefined;
+        checks.push(mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing, store, authorityCheck));
+        if (authorityCheck) {
+            checks.push(authorityCheck);
+        }
     }
     return { name: "Mailroom", checks };
 }
@@ -973,18 +1052,135 @@ function listJsonDocuments(deps, dir) {
 }
 async function resolveMailStore(agentDir) {
     const agentName = agentDir.replace(/\.ouro$/, "");
-    // An unreadable vault means the mode is unknown, so this falls back to the
-    // reader's own default — the local file store. `mail config` in checkSenses
-    // is where an unavailable runtime config is reported, and it fails hard.
-    const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: true });
-    if (!runtimeConfig.ok)
-        return { hosted: false };
+    const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: false });
+    if (!runtimeConfig.ok) {
+        return {
+            hosted: null,
+            status: runtimeConfig.reason === "unavailable" ? "warn" : "fail",
+            detail: `${runtimeConfig.error} (${runtimeConfig.itemPath})`,
+        };
+    }
     const mailroom = asRecord(runtimeConfig.config.mailroom);
     const azureAccountUrl = textField(mailroom, "azureAccountUrl");
     if (!azureAccountUrl)
         return { hosted: false };
     const azureContainer = textField(mailroom, "azureContainer") || "mailroom";
-    return { hosted: true, label: `hosted azure-blob ${azureAccountUrl}/${azureContainer}` };
+    const privateKeys = asRecord(mailroom?.privateKeys);
+    return {
+        hosted: true,
+        label: `hosted azure-blob ${azureAccountUrl}/${azureContainer}`,
+        privateKeyIds: new Set(Object.entries(privateKeys ?? {})
+            .filter(([, value]) => typeof value === "string" && value.trim().length > 0)
+            .map(([keyId]) => keyId)),
+    };
+}
+function parseCacheDocument(deps, filePath) {
+    try {
+        const parsed = JSON.parse(deps.readFileSync(filePath));
+        return asRecord(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+async function hostedMailCacheAuthorityCheck(deps, agentDir, store) {
+    const agentName = agentDir.replace(/\.ouro$/, "");
+    const base = { id: "mail.cache_authority", label: `${agentDir} hosted mail cache authority` };
+    let probe;
+    try {
+        probe = await deps.observeHostedMailAuthority(agentName);
+    }
+    catch (error) {
+        return {
+            ...base,
+            status: "warn",
+            detail: `hosted authority is temporarily unverified: ${error instanceof Error ? error.message : String(error)}; no local cache mutation was attempted`,
+        };
+    }
+    if (!probe.ok) {
+        return {
+            ...base,
+            status: probe.definitive ? "fail" : "warn",
+            detail: `hosted authority unavailable: ${probe.detail}; no local cache mutation was attempted`,
+        };
+    }
+    const { observation } = probe;
+    if (observation.parseFailureCount > 0 || observation.duplicateIds.length > 0) {
+        return {
+            ...base,
+            status: "warn",
+            detail: `hosted authority is ambiguous (${observation.parseFailureCount} malformed index name(s), ${observation.duplicateIds.length} duplicate id(s)); no local cache mutation was attempted`,
+        };
+    }
+    if (observation.records.length === 0) {
+        return {
+            ...base,
+            status: "warn",
+            detail: "hosted authority is empty and remains unverified because an empty index namespace cannot prove the mailbox is empty; no local cache mutation was attempted",
+        };
+    }
+    const cacheDir = `${deps.bundlesRoot}/${agentDir}/state/mail-search`;
+    let fileNames = [];
+    if (deps.existsSync(cacheDir)) {
+        try {
+            fileNames = deps.readdirSync(cacheDir).filter((name) => name.endsWith(".json"));
+        }
+        catch (error) {
+            return {
+                ...base,
+                status: "warn",
+                detail: `hosted authority is sound but local cache is unreadable: ${error instanceof Error ? error.message : String(error)}; run \`ouro mail sync-cache --agent ${agentName}\``,
+            };
+        }
+    }
+    const recordsById = new Map(observation.records.map((record) => [record.id, record]));
+    const documentsById = new Map();
+    let malformedOrNoncanonical = 0;
+    for (const fileName of fileNames) {
+        const document = parseCacheDocument(deps, `${cacheDir}/${fileName}`);
+        if (!document || document.agentId !== agentName || fileName !== `${document.messageId}.json` || !recordsById.has(document.messageId)) {
+            malformedOrNoncanonical += 1;
+            continue;
+        }
+        documentsById.set(document.messageId, document);
+    }
+    let mismatched = 0;
+    let invalidKeyProvenance = 0;
+    for (const record of observation.records) {
+        const document = documentsById.get(record.id);
+        if (!document || !(0, hosted_cache_sync_1.mailSearchCacheDocumentMatchesRecord)(document, record, true)) {
+            mismatched += 1;
+            continue;
+        }
+        if (!document.decryptionKeyId || !store.privateKeyIds.has(document.decryptionKeyId)) {
+            invalidKeyProvenance += 1;
+        }
+    }
+    const coverage = (0, search_cache_1.readMailSearchCoverageRecord)({
+        agentId: agentName,
+        storeKind: "azure-blob",
+    }, { cacheDirForAgent: () => cacheDir });
+    const expectedCachedCount = documentsById.size;
+    const coverageMatches = coverage !== null
+        && coverage.textProjectionVersion === search_cache_1.MAIL_SEARCH_TEXT_PROJECTION_VERSION
+        && coverage.messageIndexFingerprint === observation.snapshot.messageIndexFingerprint
+        && coverage.visibleMessageCount === observation.snapshot.visibleMessageCount
+        && coverage.cachedMessageCount === expectedCachedCount
+        && coverage.decryptableMessageCount === expectedCachedCount
+        && coverage.skippedMessageCount === observation.snapshot.visibleMessageCount - expectedCachedCount;
+    if (malformedOrNoncanonical > 0 || mismatched > 0 || invalidKeyProvenance > 0 || !coverageMatches) {
+        return {
+            ...base,
+            status: "warn",
+            detail: `hosted authority is sound but cache diverges: ${mismatched} missing/stale canonical document(s), ${malformedOrNoncanonical} malformed/orphan/noncanonical/duplicate file(s), ${invalidKeyProvenance} invalid key provenance document(s), all-scope coverage ${coverageMatches ? "matches" : "missing/malformed/stale"}; run \`ouro mail sync-cache --agent ${agentName}\``,
+        };
+    }
+    const count = observation.records.length;
+    return {
+        ...base,
+        status: "pass",
+        detail: `${count} authoritative hosted message${count === 1 ? "" : "s"}; local search cache converged with current metadata, projection, and key provenance`,
+    };
 }
 /**
  * Local-file Mailroom liveness signal.
@@ -1039,7 +1235,11 @@ function hostedMailMirrorProbe(deps, agentDir, storeLabel) {
             provenance: `attempted directory listing of ${mirrorDir}`,
         };
     }
-    return (0, freshness_1.observeMirroredStore)(mirrorDir, deps, { hasEntries: listing.count > 0, remote: storeLabel });
+    return (0, freshness_1.observeMirroredStore)(mirrorDir, deps, {
+        hasEntries: listing.count > 0,
+        remote: storeLabel,
+        authorityReadNote: "which the separate hosted cache authority check reads without mutation; this liveness check does not use remote data for recency",
+    });
 }
 /**
  * Mail-ingest liveness — "is mail still arriving?", as opposed to the check
@@ -1053,8 +1253,24 @@ function hostedMailMirrorProbe(deps, agentDir, storeLabel) {
  * activity wording and the remediation are all chosen per store kind. Reusing
  * the local path in hosted mode measures a directory nothing writes to.
  */
-function mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing, store) {
+function mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing, store, authorityCheck) {
     const hosted = store.hosted ? store : null;
+    if (hosted && authorityCheck) {
+        if (authorityCheck.status === "pass") {
+            return {
+                id: "mail.ingest_liveness",
+                label: `${agentDir} mail ingest liveness`,
+                status: "pass",
+                detail: `hosted authority and local search cache are converged; this is healthy quiet even when the local mirror mtime is old or unchanged (${hosted.label}); mirror age is not treated as hosted-ingest authority`,
+            };
+        }
+        return {
+            id: "mail.ingest_liveness",
+            label: `${agentDir} mail ingest liveness`,
+            status: authorityCheck.status,
+            detail: `hosted ingest liveness follows the available authority result rather than local mirror age: ${authorityCheck.detail}`,
+        };
+    }
     const probe = hosted
         ? hostedMailMirrorProbe(deps, agentDir, hosted.label)
         : localMailStoreProbe(deps, messagesDir, listing);
@@ -1066,7 +1282,7 @@ function mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, list
         probe,
         thresholds: (0, freshness_1.resolveFreshnessThresholds)(exports.DEFAULT_MAIL_INGEST_THRESHOLDS, senseFreshnessOverride(deps, agentDir, "mail")),
         remediation: hosted
-            ? `doctor measures hosted mail only through this machine's local mirror and makes no network calls — confirm the container itself by listing \`messages/\` blobs in ${hosted.label} by Last-Modified, or read the mailbox directly (\`ouro mailbox\`, or the agent's \`mail_recent\` tool); if the mirror is empty or stale while the container is current, the hosted reader on this machine is not running`
+            ? `this liveness check measures recency only through this machine's local mirror; the separate hosted cache authority check reads index names without mutation — if the mirror is empty or stale while authority is current, run \`ouro mail sync-cache --agent ${agentDir.replace(/\.ouro$/, "")}\` and verify the hosted reader on this machine`
             : "mail is configured but nothing is arriving — re-check the mailbox grant and keyIds against the vault (a server-side key rotation silently orphans ingestion), run `ouro connect mail --agent <agent>`, and inspect the mailroom ingress logs",
         configuredSinceMs: pathMtimeMs(deps, `${mailroomRoot}/registry.json`),
         context: hosted ? `mailbox configured; ${hosted.label}` : "mailbox configured",
@@ -1160,7 +1376,7 @@ function checkDisk(deps) {
             return !/\.\d+\.log$/.test(name);
         return false;
     };
-    const addLogSizeCheck = (labelPrefix, logsDir) => {
+    const addLogSizeCheck = (labelPrefix, logsDir, pruneCommand) => {
         let totalSize = 0;
         let activeSize = 0;
         const oversizedActive = [];
@@ -1187,14 +1403,15 @@ function checkDisk(deps) {
         }
         const sizeMB = totalSize / (1024 * 1024);
         const activeSizeMB = activeSize / (1024 * 1024);
+        const repair = pruneCommand ? ` — run \`${pruneCommand}\`` : "";
         if (activeSizeMB > 500) {
-            checks.push({ label: `${labelPrefix} daemon log size`, status: "fail", detail: `${activeSizeMB.toFixed(1)}MB active / ${sizeMB.toFixed(1)}MB total — active logs exceed 500MB limit` });
+            checks.push({ label: `${labelPrefix} daemon log size`, status: "fail", detail: `${activeSizeMB.toFixed(1)}MB active / ${sizeMB.toFixed(1)}MB total — active logs exceed 500MB limit${repair}` });
         }
         else if (oversizedActive.length > 0) {
             checks.push({
                 label: `${labelPrefix} daemon log size`,
                 status: "warn",
-                detail: `${activeSizeMB.toFixed(1)}MB active / ${sizeMB.toFixed(1)}MB total; active stream(s) over ${Math.round(nerves_1.DEFAULT_MAX_LOG_SIZE_BYTES / (1024 * 1024))}MB: ${oversizedActive.join(", ")} — run \`ouro logs prune\``,
+                detail: `${activeSizeMB.toFixed(1)}MB active / ${sizeMB.toFixed(1)}MB total; active stream(s) over ${Math.round(nerves_1.DEFAULT_MAX_LOG_SIZE_BYTES / (1024 * 1024))}MB: ${oversizedActive.join(", ")}${repair}`,
             });
         }
         else {
@@ -1207,11 +1424,43 @@ function checkDisk(deps) {
     }
     for (const agentDir of agents) {
         const logsDir = `${deps.bundlesRoot}/${agentDir}/state/daemon/logs`;
+        let pruneCommand;
+        if (deps.lstatSync && deps.realpathSync) {
+            const io = {
+                existsSync: deps.existsSync,
+                lstatSync: deps.lstatSync,
+                readdirSync: deps.readdirSync,
+                realpathSync: deps.realpathSync,
+            };
+            try {
+                const agentName = agentDir.slice(0, -".ouro".length);
+                const target = (0, prunable_bundle_1.resolvePrunableAgentBundle)({ bundlesRoot: deps.bundlesRoot, agentName, fs: io });
+                if (!deps.existsSync(target.logsDir))
+                    throw new Error("logs directory does not exist");
+                const logsIo = {
+                    lstatSync: (filePath) => {
+                        const stat = deps.lstatSync(filePath);
+                        return {
+                            isDirectory: stat.isDirectory,
+                            isFile: stat.isFile ?? (() => false),
+                            isSymbolicLink: stat.isSymbolicLink,
+                        };
+                    },
+                    readdirSync: deps.readdirSync,
+                    realpathSync: deps.realpathSync,
+                };
+                (0, prunable_bundle_1.validatePrunableLogsTarget)(target, logsIo);
+                pruneCommand = `ouro logs prune --agent ${agentName}`;
+            }
+            catch {
+                // Doctor reports size but only offers repair for an exactly validated target.
+            }
+        }
         if (!deps.existsSync(logsDir)) {
             checks.push({ label: `${agentDir} daemon logs dir`, status: "warn", detail: `${logsDir} not found` });
         }
         else {
-            addLogSizeCheck(agentDir, logsDir);
+            addLogSizeCheck(agentDir, logsDir, pruneCommand);
         }
     }
     // Check AgentBundles root

package/dist/heart/daemon/freshness.js

@@ -235,13 +235,15 @@ function observeCreatePerEventStore(dir, deps, options) {
  * a local directory that nothing writes to any more.
  */
 function observeMirroredStore(dir, deps, options) {
-    const provenance = `derived from the local mirror at ${dir} (directory mtime, O(1), no per-entry scan); the authoritative store is ${options.remote}, which doctor does not read`;
+    const provenanceReadNote = options.authorityReadNote ?? "which doctor does not read";
+    const unknownReadNote = options.authorityReadNote ?? "is not read by doctor (no network calls, no credentials)";
+    const provenance = `derived from the local mirror at ${dir} (directory mtime, O(1), no per-entry scan); the authoritative store is ${options.remote}, ${provenanceReadNote}`;
     const exists = deps.existsSync(dir);
     if (!exists || !options.hasEntries) {
         return {
             observation: {
                 kind: "unknown",
-                reason: `the local mirror at ${dir} is ${exists ? "empty" : "absent"}, and ${options.remote} is not read by doctor (no network calls, no credentials), so recency cannot be measured on this machine`,
+                reason: `the local mirror at ${dir} is ${exists ? "empty" : "absent"}, and ${options.remote} ${unknownReadNote}, so recency cannot be measured on this machine`,
             },
             provenance,
         };

package/dist/heart/daemon/logs-prune.js

@@ -7,6 +7,17 @@ const crypto_1 = require("crypto");
 const nerves_1 = require("../../nerves");
 const runtime_1 = require("../../nerves/runtime");
 const identity_1 = require("../identity");
+const prunable_bundle_1 = require("./prunable-bundle");
+function resolveLogsTarget(options) {
+    if (options.logsDir)
+        return { logsDir: options.logsDir };
+    if (!options.agentName) {
+        throw new Error("daemon logs prune requires an explicit agent or an internal logs directory");
+    }
+    const bundlesRoot = options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+    const target = (0, prunable_bundle_1.resolvePrunableAgentBundle)({ bundlesRoot, agentName: options.agentName });
+    return { logsDir: target.logsDir, target };
+}
 function isActiveLogStream(name) {
     if (name.endsWith(".ndjson")) {
         return !/\.\d+\.ndjson$/.test(name);
@@ -17,20 +28,26 @@ function isActiveLogStream(name) {
     return false;
 }
 function pruneDaemonLogs(options = {}) {
-    /* v8 ignore next -- defensive: tests always pass logsDir to avoid prod paths @preserve */
-    const logsDir = options.logsDir ?? (0, identity_1.getAgentDaemonLogsDir)(options.agentName);
     const maxSizeBytes = options.maxSizeBytes ?? nerves_1.DEFAULT_MAX_LOG_SIZE_BYTES;
     const maxGenerations = options.maxGenerations ?? nerves_1.DEFAULT_MAX_GENERATIONS;
     const traceId = (0, crypto_1.randomUUID)();
+    let logsDir = options.logsDir ?? "unresolved";
     (0, runtime_1.emitNervesEvent)({
         component: "nerves",
         event: "nerves.logs_prune_start",
         trace_id: traceId,
         message: "pruning daemon logs",
-        meta: { logsDir, maxSizeBytes, maxGenerations },
+        meta: {
+            logsDir: options.logsDir ?? null,
+            agentName: options.agentName ?? null,
+            maxSizeBytes,
+            maxGenerations,
+        },
     });
     let completed = false;
     try {
+        const resolved = resolveLogsTarget(options);
+        logsDir = resolved.logsDir;
         if (!(0, fs_1.existsSync)(logsDir)) {
             completed = true;
             (0, runtime_1.emitNervesEvent)({
@@ -42,6 +59,10 @@ function pruneDaemonLogs(options = {}) {
             });
             return { filesCompacted: 0, bytesFreed: 0 };
         }
+        const inspection = resolved.target
+            ? (0, prunable_bundle_1.validatePrunableLogsTarget)(resolved.target)
+            : (0, prunable_bundle_1.validatePrunableLogsDirectory)(logsDir);
+        const { entries, logsReal } = inspection;
         let filesCompacted = 0;
         let bytesFreed = 0;
         // Enumerate and rotate each active structured stream plus legacy launchd
@@ -49,10 +70,11 @@ function pruneDaemonLogs(options = {}) {
         // stream can be a rotation candidate. Legacy generation files are handled
         // inside rotateIfNeeded's generation-shift step, so we skip them here to
         // avoid double-rotating.
-        for (const name of (0, fs_1.readdirSync)(logsDir)) {
+        for (const name of entries) {
             if (!isActiveLogStream(name))
                 continue;
             const filePath = (0, path_1.join)(logsDir, name);
+            (0, prunable_bundle_1.validatePrunableLogEntry)(filePath, logsReal);
             let sizeBefore;
             try {
                 sizeBefore = (0, fs_1.statSync)(filePath).size;