@openclawbrain/cli 0.4.22 → 0.4.24

package/dist/src/cli.js

@@ -818,10 +818,14 @@ function summarizeStatusHookFilesState(installHook) {
     return "unverified";
 }
 function summarizeStatusAttachmentWatcher(status) {
-    if (status.passiveLearning.watchState === "watching") {
+    const watchState = status.passiveLearning.watch?.state ?? status.passiveLearning.watchState;
+    if (watchState === "watching") {
         return "alive";
     }
-    if (status.passiveLearning.watchState === "stale_snapshot") {
+    if (watchState === "lagging") {
+        return "lagging";
+    }
+    if (watchState === "stale_snapshot") {
         return "stale";
     }
     return "not_visible";
@@ -1150,13 +1154,14 @@ function summarizeStatusTeacher(report, providerConfig, localLlm) {
             detail: `${providerConfig.teacher.model} is enabled on Ollama, but no watch teacher snapshot is visible yet`
         };
     }
-    const stale = report.teacherLoop.watchState === "stale_snapshot" || (report.teacherLoop.latestFreshness === "stale" && report.teacherLoop.lastNoOpReason !== "no_teacher_artifacts");
+    const watchState = report.teacherLoop.watch?.state ?? report.teacherLoop.watchState ?? "not_visible";
+    const stale = watchState === "stale_snapshot" || (report.teacherLoop.latestFreshness === "stale" && report.teacherLoop.lastNoOpReason !== "no_teacher_artifacts");
     const idle = report.teacherLoop.running === false &&
         (report.teacherLoop.queueDepth ?? 0) === 0 &&
         report.teacherLoop.failureMode === "none";
     const healthy = report.teacherLoop.failureMode === "none" &&
         stale === false &&
-        report.teacherLoop.watchState !== "not_visible";
+        watchState === "watching";
     const cycleDetail = report.teacherLoop.lastNoOpReason === "no_teacher_artifacts"
         ? summarizeTeacherNoArtifactCycle(report.teacherLoop.notes).detail
         : TEACHER_NO_OP_MESSAGES[report.teacherLoop.lastNoOpReason] ?? "the latest teacher cycle detail is unavailable";
@@ -1180,7 +1185,9 @@ function summarizeStatusTeacher(report, providerConfig, localLlm) {
         stale,
         idle,
         latestCycle,
-        detail: `${providerConfig.teacher.model} is enabled on Ollama; ${cycleDetail}`
+        detail: watchState === "lagging"
+            ? `${providerConfig.teacher.model} is enabled on Ollama, but the watch heartbeat is lagging; ${cycleDetail}`
+            : `${providerConfig.teacher.model} is enabled on Ollama; ${cycleDetail}`
     };
 }
 function summarizeStatusEmbedder(embeddings) {
@@ -1334,7 +1341,7 @@ function summarizeStatusAlerts(report, providerConfig, embeddings, localLlm) {
     return buckets;
 }
 function summarizeStatusWatchState(status) {
-    return status.passiveLearning.watchState;
+    return status.passiveLearning.watch?.state ?? status.passiveLearning.watchState;
 }
 function summarizeStatusServeReality(status) {
     if (status.brainStatus.serveState === "serving_active_pack") {
@@ -1483,7 +1490,7 @@ function formatCurrentProfileStatusSummary(status, report, targetInspection, opt
         `budget      requested=${report.servePath.requestedBudgetStrategy ?? "none"} resolved=${report.servePath.resolvedBudgetStrategy ?? "none"} maxBlocks=${report.servePath.resolvedMaxContextBlocks ?? "none"} source=${report.servePath.structuralBudgetSource ?? "none"} origin=${status.brainStatus.structuralDecision.origin} basis=${status.brainStatus.structuralDecision.basis}`,
         `decision    ${status.brainStatus.structuralDecision.detail}`,
         `principal   latest=${formatPrincipalLatest(report)} pending=${report.principal.pendingCount ?? report.learning.pendingPrincipalCount ?? "none"} checkpoint=${formatPrincipalCheckpointFrontier(report)} downstream=${yesNo(report.principal.servingDownstreamOfLatestCorrection)} lag=${report.learning.principalLagToPromotion.sequenceLag ?? "none"}`,
-        `passive     learner=${yesNo(status.passiveLearning.learnerRunning)} firstExport=${yesNo(status.passiveLearning.firstExportOccurred)} watch=${status.passiveLearning.watchState} export=${status.passiveLearning.exportState} backlog=${status.passiveLearning.backlogState} pending=${formatStatusNullableNumber(status.passiveLearning.pendingLive)}/${formatStatusNullableNumber(status.passiveLearning.pendingBackfill)} detail=${status.passiveLearning.detail}`,
+        `passive     learner=${yesNo(status.passiveLearning.learnerRunning)} firstExport=${yesNo(status.passiveLearning.firstExportOccurred)} watch=${summarizeStatusWatchState(status)} export=${status.passiveLearning.exportState} backlog=${status.passiveLearning.backlogState} pending=${formatStatusNullableNumber(status.passiveLearning.pendingLive)}/${formatStatusNullableNumber(status.passiveLearning.pendingBackfill)} detail=${status.passiveLearning.detail}`,
         `delta       observed=${status.passiveLearning.lastObservedDelta.observedAt ?? "none"} exported=${formatStatusNullableYesNo(status.passiveLearning.lastObservedDelta.exported)} labeled=${formatStatusNullableYesNo(status.passiveLearning.lastObservedDelta.labeled)} promoted=${formatStatusNullableYesNo(status.passiveLearning.lastObservedDelta.promoted)} served=${formatStatusNullableYesNo(status.passiveLearning.lastObservedDelta.served)} transition=${formatStatusObservedDeltaTransition(status.passiveLearning.lastObservedDelta)} detail=${status.passiveLearning.lastObservedDelta.explanation}`,
         `scanner     flowing=${yesNo(report.supervision.flowing)} scan=${report.supervision.scanPolicy ?? "none"} surfaces=${formatScannerSurfaces(report)} labels=${report.supervision.humanLabelCount ?? "none"}/${report.supervision.selfLabelCount ?? "none"} attributable=${report.supervision.attributedEventCount ?? "none"}/${report.supervision.totalEventCount ?? "none"} digests=${report.supervision.selectionDigestCount ?? "none"}`,
         `labels      ${formatLabelFlowSummary(report.labelFlow)}`,

package/dist/src/index.d.ts

@@ -6,6 +6,16 @@ import { type ActivationInspection, type ActivationObservabilityReport, type Gra
 export { clearOpenClawProfileRuntimeLoadProof, listOpenClawProfileRuntimeLoadProofs, recordOpenClawProfileRuntimeLoadProof, resolveAttachmentRuntimeLoadProofsPath, type OpenClawProfileRuntimeLoadProofRecordV1, type OpenClawProfileRuntimeLoadProofSetV1, type OpenClawProfileRuntimeLoadProofsV1 } from "./attachment-truth.js";
 import { type AsyncTeacherLabelerConfigV1 } from "./teacher-labeler.js";
 export { createHttpOllamaTeacherLabelerClient, createOllamaTeacherLabeler, createTeacherLabeler, summarizeTeacherLabelerOpportunity, type AsyncTeacherLabelerConfigV1, type AsyncTeacherNoopLabelerConfigV1, type AsyncTeacherOllamaLabelerConfigV1, type OllamaTeacherLabelerClient, type TeacherLabeler, type TeacherLabelerOpportunityInputV1, type TeacherLabelerOpportunityV1, type TeacherLabelerResultV1, type TeacherLabelerRunInputV1 } from "./teacher-labeler.js";
+export type OperatorPassiveLearningWatchState = CurrentProfilePassiveLearningWatchStateV1 | "lagging";
+export interface OperatorPassiveLearningWatchSummary {
+    state: OperatorPassiveLearningWatchState;
+    detail: string;
+    lastHeartbeatAt: string | null;
+    lagSeconds: number | null;
+    intervalSeconds: number | null;
+    healthyWithinSeconds: number | null;
+    staleAfterSeconds: number | null;
+}
 export declare const DEFAULT_ASYNC_TEACHER_QUEUE_CAPACITY = 8;
 declare const RECORDED_SESSION_TRACE_CONTRACT: "recorded_session_trace.v1";
 declare const RECORDED_SESSION_FIXTURE_CONTRACT: "recorded_session_replay_fixture.v1";
@@ -1687,7 +1697,8 @@ export interface OperatorTeacherLoopSummary {
     lastHeartbeatAt: string | null;
     lastScanAt: string | null;
     pollIntervalSeconds: number | null;
-    watchState: CurrentProfilePassiveLearningWatchStateV1;
+    watchState: OperatorPassiveLearningWatchState;
+    watch: OperatorPassiveLearningWatchSummary;
     lastProcessedAt: string | null;
     artifactCount: number | null;
     queueDepth: number | null;

package/dist/src/index.js

@@ -6646,11 +6646,18 @@ function loadTeacherSurfaceFromInput(input) {
 }
 function summarizeTeacherLoopWatchState(input) {
     if (input.sourceKind !== "watch_snapshot" || input.watchSnapshot === null) {
+        const watchState = input.sourceKind === "async_snapshot" ? "snapshot_only" : "not_visible";
         return {
             snapshotUpdatedAt: null,
             lastWatchHeartbeatAt: null,
             pollIntervalSeconds: null,
-            watchState: input.sourceKind === "async_snapshot" ? "snapshot_only" : "not_visible"
+            watchState,
+            watch: buildTeacherLoopWatchSummary({
+                state: watchState,
+                detail: watchState === "snapshot_only"
+                    ? "only a saved watcher snapshot is visible; no live heartbeat is available"
+                    : "no watcher snapshot is visible from the current activation root"
+            })
         };
     }
     const lastWatchHeartbeatAt = input.watchSnapshot.snapshot.runtime?.lastHeartbeatAt ?? input.watchSnapshot.lastRunAt;
@@ -6660,16 +6667,55 @@ function summarizeTeacherLoopWatchState(input) {
             snapshotUpdatedAt: input.watchSnapshot.updatedAt,
             lastWatchHeartbeatAt: null,
             pollIntervalSeconds,
-            watchState: "snapshot_only"
+            watchState: "snapshot_only",
+            watch: buildTeacherLoopWatchSummary({
+                state: "snapshot_only",
+                detail: "only a saved watcher snapshot is visible; no live heartbeat is available",
+                intervalSeconds: pollIntervalSeconds
+            })
         };
     }
-    const lagMs = Date.parse(input.observedAt) - Date.parse(lastWatchHeartbeatAt);
-    const staleAfterMs = pollIntervalSeconds * 2000 + 15_000;
+    const rawLagMs = Date.parse(input.observedAt) - Date.parse(lastWatchHeartbeatAt);
+    const lagMs = Number.isFinite(rawLagMs) ? Math.max(0, rawLagMs) : null;
+    const healthyWithinMs = pollIntervalSeconds * 2000 + 15_000;
+    const staleAfterMs = healthyWithinMs + Math.max(15_000, pollIntervalSeconds * 1000);
+    const watchState = lagMs !== null && lagMs <= healthyWithinMs
+        ? "watching"
+        : lagMs !== null && lagMs <= staleAfterMs
+            ? "lagging"
+            : "stale_snapshot";
     return {
         snapshotUpdatedAt: input.watchSnapshot.updatedAt,
         lastWatchHeartbeatAt,
         pollIntervalSeconds,
-            watchState: Number.isFinite(lagMs) && lagMs >= 0 && lagMs <= staleAfterMs ? "watching" : "stale_snapshot"
+        watchState,
+        watch: buildTeacherLoopWatchSummary({
+            state: watchState,
+            detail: watchState === "watching"
+                ? "watch heartbeat is inside the healthy window"
+                : watchState === "lagging"
+                    ? "watch heartbeat missed the healthy window but has not crossed the stale snapshot threshold"
+                    : "watch heartbeat is older than the stale snapshot threshold",
+            lastHeartbeatAt: lastWatchHeartbeatAt,
+            lagMs,
+            intervalSeconds: pollIntervalSeconds,
+            healthyWithinMs,
+            staleAfterMs
+        })
+    };
+}
+function buildTeacherLoopWatchSummary(input) {
+    const lagSeconds = Number.isFinite(input.lagMs) ? Math.round((input.lagMs / 1000) * 100) / 100 : null;
+    const healthyWithinSeconds = Number.isFinite(input.healthyWithinMs) ? Math.round((input.healthyWithinMs / 1000) * 100) / 100 : null;
+    const staleAfterSeconds = Number.isFinite(input.staleAfterMs) ? Math.round((input.staleAfterMs / 1000) * 100) / 100 : null;
+    return {
+        state: input.state,
+        detail: input.detail,
+        lastHeartbeatAt: input.lastHeartbeatAt ?? null,
+        lagSeconds,
+        intervalSeconds: input.intervalSeconds ?? null,
+        healthyWithinSeconds,
+        staleAfterSeconds
     };
 }
 function emptyOperatorLearningAttribution(source, snapshotKind, detail) {
@@ -6798,6 +6844,10 @@ function summarizeTeacherLoop(input) {
     const teacherSnapshotPath = resolveOperatorTeacherSnapshotPath(input.activationRoot, normalizeOptionalString(input.teacherSnapshotPath) ?? null);
     const unavailableFromMissing = buildUnavailableLastObservedDelta("no watch teacher snapshot is visible for the latest observed cycle");
     const unavailableFromAsync = buildUnavailableLastObservedDelta("raw async teacher snapshots do not record the last observed export/label/promotion delta");
+    const notVisibleWatch = buildTeacherLoopWatchSummary({
+        state: "not_visible",
+        detail: "no watcher snapshot is visible from the current activation root"
+    });
     if (loaded === null && teacherSnapshotPath === null) {
         return {
             available: false,
@@ -6812,6 +6862,7 @@ function summarizeTeacherLoop(input) {
             lastScanAt: null,
             pollIntervalSeconds: null,
             watchState: "not_visible",
+            watch: notVisibleWatch,
             lastProcessedAt: null,
             artifactCount: null,
             queueDepth: null,
@@ -6852,6 +6903,7 @@ function summarizeTeacherLoop(input) {
             lastScanAt: null,
             pollIntervalSeconds: null,
             watchState: "not_visible",
+            watch: notVisibleWatch,
             lastProcessedAt: null,
             artifactCount: null,
             queueDepth: null,
@@ -6898,6 +6950,7 @@ function summarizeTeacherLoop(input) {
         lastScanAt: snapshot.runtime?.lastScanAt ?? null,
         pollIntervalSeconds: watchState.pollIntervalSeconds,
         watchState: watchState.watchState,
+        watch: watchState.watch,
         lastProcessedAt: snapshot.diagnostics.lastProcessedAt,
         artifactCount: watchSnapshot?.teacher.artifactCount ?? snapshot.teacher.artifactCount,
         queueDepth: snapshot.queue.depth,
@@ -7486,6 +7539,13 @@ function didCurrentProfileFirstExportOccur(report) {
 }
 function summarizeCurrentProfilePassiveLearning(report, activePackId) {
     const firstExportOccurred = didCurrentProfileFirstExportOccur(report);
+    const watch = report.teacherLoop.watch ?? buildTeacherLoopWatchSummary({
+        state: report.teacherLoop.watchState,
+        detail: "watch state came from the legacy passive-learning surface",
+        lastHeartbeatAt: report.teacherLoop.lastHeartbeatAt,
+        intervalSeconds: report.teacherLoop.pollIntervalSeconds
+    });
+    const watchState = watch.state ?? report.teacherLoop.watchState;
     const exportState = !firstExportOccurred
         ? "awaiting_first_export"
         : report.supervision.exportedAt !== null
@@ -7495,28 +7555,33 @@ function summarizeCurrentProfilePassiveLearning(report, activePackId) {
         ? report.learning.backlogState
         : "unknown";
     const detail = !firstExportOccurred
-        ? report.teacherLoop.watchState === "watching"
+        ? watchState === "watching"
             ? "watch heartbeat is fresh, but this activation root has not observed its first export yet"
+            : watchState === "lagging"
+                ? "watch heartbeat is lagging, and this activation root is still waiting for the first export before passive learning can advance"
             : "this activation root is still waiting for the first export before passive learning can advance"
         : backlogState === "unknown"
             ? "first export is proven, but passive backlog state is not visible from the current local artifacts"
-            : report.teacherLoop.watchState === "watching"
+            : watchState === "watching"
                 ? `watch heartbeat is fresh; passive backlog is ${backlogState} with live=${report.learning.pendingLive ?? 0} and backfill=${report.learning.pendingBackfill ?? 0}`
-                : report.teacherLoop.watchState === "stale_snapshot"
+                : watchState === "lagging"
+                    ? `watch heartbeat is lagging; latest known passive backlog is ${backlogState} with live=${report.learning.pendingLive ?? 0} and backfill=${report.learning.pendingBackfill ?? 0}`
+                    : watchState === "stale_snapshot"
                     ? `last saved watch snapshot is stale; latest known passive backlog is ${backlogState}`
-                    : report.teacherLoop.watchState === "snapshot_only"
+                    : watchState === "snapshot_only"
                         ? `passive backlog is visible from the last saved snapshot: ${backlogState}`
                         : `passive backlog is visible from the last known learner state: ${backlogState}`;
     return {
-        learnerRunning: report.teacherLoop.watchState === "watching",
+        learnerRunning: watchState === "watching",
         firstExportOccurred,
-        watchState: report.teacherLoop.watchState,
+        watchState,
+        watch,
         exportState,
         backlogState,
         pendingLive: report.learning.available ? report.learning.pendingLive : null,
         pendingBackfill: report.learning.available ? report.learning.pendingBackfill : null,
-        lastWatchHeartbeatAt: report.teacherLoop.lastHeartbeatAt,
-        watchIntervalSeconds: report.teacherLoop.pollIntervalSeconds,
+        lastWatchHeartbeatAt: watch.lastHeartbeatAt ?? report.teacherLoop.lastHeartbeatAt,
+        watchIntervalSeconds: watch.intervalSeconds ?? report.teacherLoop.pollIntervalSeconds,
         lastExportAt: report.supervision.exportedAt,
         lastPromotionAt: report.promotion.lastPromotion.at,
         currentServingPackId: activePackId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclawbrain/cli",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "OpenClawBrain operator CLI package with install/status helpers, daemon controls, and import/export tooling.",
   "type": "module",
   "main": "./dist/src/index.js",