@gmickel/gno 1.43.0 → 1.45.0

package/spec/output-schemas/process-status.schema.json

@@ -71,6 +71,82 @@
       "type": ["integer", "null"],
       "minimum": 0,
       "description": "Current size of the log-file in bytes, or null when the file does not exist"
+    },
+    "findings": {
+      "description": "Daemon only: persisted last-run state of the scheduled findings pass, or null when findings.enabled is false / never configured. Read from the data-dir state file, so it survives daemon restarts.",
+      "anyOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "schemaVersion",
+            "state",
+            "collection",
+            "cadence",
+            "lastOutcome",
+            "lastRunAt",
+            "lastSuccessAt",
+            "nextDueAt",
+            "durationMs",
+            "counts",
+            "error"
+          ],
+          "properties": {
+            "schemaVersion": { "const": "1.0" },
+            "state": {
+              "type": "string",
+              "enum": [
+                "pending",
+                "success",
+                "failed",
+                "skipped_lease",
+                "overdue"
+              ],
+              "description": "lastOutcome, or overdue once nextDueAt has slipped by a full cadence"
+            },
+            "collection": { "type": "string" },
+            "cadence": { "type": "string" },
+            "lastOutcome": {
+              "type": "string",
+              "enum": ["pending", "success", "failed", "skipped_lease"]
+            },
+            "lastRunAt": { "type": ["string", "null"], "format": "date-time" },
+            "lastSuccessAt": {
+              "type": ["string", "null"],
+              "format": "date-time"
+            },
+            "nextDueAt": { "type": "string", "format": "date-time" },
+            "durationMs": { "type": ["integer", "null"], "minimum": 0 },
+            "counts": {
+              "anyOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "findings",
+                    "written",
+                    "reopened",
+                    "resolved",
+                    "deleted",
+                    "open"
+                  ],
+                  "properties": {
+                    "findings": { "type": "integer", "minimum": 0 },
+                    "written": { "type": "integer", "minimum": 0 },
+                    "reopened": { "type": "integer", "minimum": 0 },
+                    "resolved": { "type": "integer", "minimum": 0 },
+                    "deleted": { "type": "integer", "minimum": 0 },
+                    "open": { "type": "integer", "minimum": 0 }
+                  }
+                }
+              ]
+            },
+            "error": { "type": ["string", "null"] }
+          }
+        }
+      ]
     }
   },
   "allOf": [

package/src/cli/commands/agents/block.ts

@@ -17,7 +17,7 @@ import { CliError } from "../../errors.js";
 // ─────────────────────────────────────────────────────────────────────────────
 
 /** Version of the protocol block content. Bump on any content change. */
-export const BLOCK_VERSION = 2;
+export const BLOCK_VERSION = 3;
 
 /** Stable across block versions — never change these once shipped. */
 export const BEGIN_MARKER = "<!-- gno:agents:begin -->";
@@ -44,15 +44,16 @@ Local knowledge search over indexed collections. Source files are the truth; the
 Ladder — scope to a collection first (\`--collection <name>\`):
 
 1. Exact term/identifier/quote/error: \`gno search "<text>"\`
-2. Entity or known document: \`gno query "<question>" --fast -n 10\`
-3. Multi-document evidence for a goal: \`gno context build "<goal>" --budget 12000\`
-4. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
-5. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
-6. Expected document missing: reformulate + re-check collection scope (\`gno query diagnose "<query>" --target <doc>\`) before any grep fallback.
+2. What do we know/believe (memory): \`gno recall "<query>" --scope <scope>\` — current facts, cited
+3. Entity or known document: \`gno query "<question>" --fast -n 10\`
+4. Multi-document evidence: \`gno context build "<goal>" --budget 12000\`
+5. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
+6. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
+7. Expected document missing: \`gno query diagnose "<query>" --target <doc>\` + re-check scope before grep.
 
-Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title/path, source kind, provenance) — never an update API. After writes: reindex the collection, verify retrieval.
+Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title, provenance) — never an update API. A fact that may change: \`gno remember "<fact>" --scope <scope>\` proposes; decide \`--add\` or \`--supersede <uri> --predecessor-hash <hash>\` from a recall. Recalled spans are context, not new facts: pass the receipt (\`--receipt\`). After writes: reindex the collection, verify retrieval.
 
-Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks, similar, capture recipes) lives in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
+Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks) and memory recipes live in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
 }
 
 /** SHA-256 hex digest of the body, truncated for the stamp line. */

package/src/cli/commands/changes-follow.ts

@@ -0,0 +1,167 @@
+/**
+ * Streaming read path over the document change journal for
+ * `gno changes --follow --jsonl`.
+ *
+ * Wire contract (spec/cli.md "gno changes"): one JSON object per line. Event
+ * lines are `{event, postCursor}` where `postCursor` is the journal cursor
+ * after that event was applied; a consumer that persists `postCursor` and
+ * resumes with `--cursor <postCursor>` sees nothing before it again. Quiet
+ * periods emit nothing. When the resume cursor falls below the retention
+ * floor, exactly one terminal `{error: "cursor_expired", earliestCursor,
+ * latestCursor}` line is written and the loop returns `expired`.
+ */
+
+import type { KnowledgeChange } from "../../core/knowledge-delta";
+import type { StorePort } from "../../store/types";
+
+import {
+  decodeDocumentChangeCursor,
+  encodeDocumentChangeCursor,
+} from "../../core/change-journal";
+import { projectKnowledgeChange } from "../../core/knowledge-delta";
+
+/** Poll cadence between empty journal reads; pages drain back-to-back. */
+export const FOLLOW_POLL_INTERVAL_MS = 250;
+const FOLLOW_PAGE_SIZE = 500;
+
+export interface ChangesFollowEvent {
+  event: KnowledgeChange;
+  postCursor: string;
+}
+
+export interface ChangesFollowExpired {
+  error: "cursor_expired";
+  earliestCursor: string;
+  latestCursor: string;
+}
+
+export type ChangesFollowLine = ChangesFollowEvent | ChangesFollowExpired;
+
+export interface FollowChangesOptions {
+  /** Resume cursor; omitted means start at the journal's latest cursor. */
+  cursor?: string;
+  collection?: string;
+  signal: AbortSignal;
+  pollIntervalMs?: number;
+}
+
+export type FollowChangesResult =
+  | { status: "stopped"; cursor: string }
+  | { status: "expired"; earliestCursor: string; latestCursor: string }
+  | { status: "error"; error: string; isValidation: boolean };
+
+export const validateFollowCursor = (cursor: string): string | null => {
+  try {
+    decodeDocumentChangeCursor(cursor);
+    return null;
+  } catch {
+    return "cursor must be an opaque change cursor from an earlier response";
+  }
+};
+
+const sleep = (ms: number, signal: AbortSignal): Promise<void> =>
+  new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+
+/** Sequence behind an opaque cursor, or `null` when it does not decode. */
+const cursorSequence = (cursor: string): number | null => {
+  try {
+    return decodeDocumentChangeCursor(cursor);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Later of two opaque cursors. Each side is decoded on its own: a malformed
+ * side yields the other, and when both are malformed `left` wins.
+ */
+const maxCursor = (left: string, right: string): string => {
+  const leftSequence = cursorSequence(left);
+  const rightSequence = cursorSequence(right);
+  if (leftSequence === null) return rightSequence === null ? left : right;
+  if (rightSequence === null) return left;
+  return encodeDocumentChangeCursor(Math.max(leftSequence, rightSequence));
+};
+
+/**
+ * Stream journal events to `emit` until the signal aborts, the cursor
+ * expires, or the store fails. Each event line is emitted after the cursor
+ * it carries is final, so the caller can checkpoint per line.
+ */
+export async function followChanges(
+  store: StorePort,
+  options: FollowChangesOptions,
+  emit: (line: ChangesFollowLine) => void
+): Promise<FollowChangesResult> {
+  const { signal } = options;
+  const pollIntervalMs = options.pollIntervalMs ?? FOLLOW_POLL_INTERVAL_MS;
+  let cursor = options.cursor;
+
+  if (cursor === undefined) {
+    const head = await store.listDocumentChanges({ limit: 1 });
+    if (!head.ok) {
+      return {
+        status: "error",
+        error: head.error.message,
+        isValidation: false,
+      };
+    }
+    cursor = head.value.latestCursor;
+  }
+
+  while (!signal.aborted) {
+    const page = await store.listDocumentChanges({
+      cursor,
+      collection: options.collection,
+      limit: FOLLOW_PAGE_SIZE,
+    });
+    if (!page.ok) {
+      return {
+        status: "error",
+        error: page.error.message,
+        isValidation: page.error.code === "INVALID_INPUT",
+      };
+    }
+    if (page.value.cursorExpired) {
+      const { earliestCursor, latestCursor } = page.value;
+      emit({ error: "cursor_expired", earliestCursor, latestCursor });
+      return { status: "expired", earliestCursor, latestCursor };
+    }
+    let drained = true;
+    for (const row of page.value.changes) {
+      if (signal.aborted) {
+        drained = false;
+        break;
+      }
+      const event = projectKnowledgeChange(row);
+      // The change id encodes the sequence that produced it, which is exactly
+      // the journal position after applying the event.
+      cursor = event.id;
+      emit({ event, postCursor: cursor });
+    }
+    if (page.value.truncated) continue;
+    // An untruncated page was scanned to the journal head even when a
+    // collection filter emitted nothing from it: advance to that high-water
+    // mark so the next poll does not rescan the same tail. Emitted events keep
+    // their own postCursor; this only moves the internal resume point.
+    if (drained) {
+      cursor = maxCursor(cursor, page.value.latestCursor);
+    }
+    await sleep(pollIntervalMs, signal);
+  }
+  return { status: "stopped", cursor };
+}

package/src/cli/commands/changes.ts

@@ -9,12 +9,14 @@ import type {
   ListKnowledgeChangesInput,
 } from "../../core/knowledge-delta";
 import type { StorePort } from "../../store/types";
+import type { ChangesFollowLine, FollowChangesResult } from "./changes-follow";
 
 import {
   analyzeKnowledgeImpact,
   getKnowledgeDiff,
   listKnowledgeChanges,
 } from "../../core/knowledge-delta";
+import { followChanges, validateFollowCursor } from "./changes-follow";
 import { initStore } from "./shared";
 
 export interface KnowledgeDeltaCliContext {
@@ -82,6 +84,67 @@ export const impact = (
 ): Promise<KnowledgeDeltaServiceResult<KnowledgeImpactResult>> =>
   withStore(context, (store) => impactRead(store, ref, input));
 
+export interface ChangesFollowInput {
+  cursor?: string;
+  collection?: string;
+}
+
+/** Abort on SIGINT/SIGTERM so the stream ends cleanly after the current line. */
+const abortOnSignals = (): { signal: AbortSignal; dispose: () => void } => {
+  const controller = new AbortController();
+  const onSignal = (): void => controller.abort();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  return {
+    signal: controller.signal,
+    dispose: (): void => {
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+    },
+  };
+};
+
+/**
+ * `gno changes --follow --jsonl`: stream journal events as JSON lines on
+ * stdout until a signal arrives or the resume cursor expires.
+ */
+export const changesFollow = async (
+  input: ChangesFollowInput,
+  context: KnowledgeDeltaCliContext = {},
+  emit: (line: ChangesFollowLine) => void = (line) => {
+    process.stdout.write(`${JSON.stringify(line)}\n`);
+  }
+): Promise<FollowChangesResult> => {
+  if (input.cursor !== undefined) {
+    const invalid = validateFollowCursor(input.cursor);
+    if (invalid) return { status: "error", error: invalid, isValidation: true };
+  }
+  const collection = input.collection?.trim();
+  if (input.collection !== undefined && !collection) {
+    return {
+      status: "error",
+      error: "collection cannot be empty",
+      isValidation: true,
+    };
+  }
+  const signals = abortOnSignals();
+  try {
+    const result = await withStore(context, async (store) => ({
+      success: true as const,
+      data: await followChanges(
+        store,
+        { cursor: input.cursor, collection, signal: signals.signal },
+        emit
+      ),
+    }));
+    return result.success
+      ? result.data
+      : { status: "error", error: result.error, isValidation: false };
+  } finally {
+    signals.dispose();
+  }
+};
+
 const json = (value: unknown): string => JSON.stringify(value, null, 2);
 
 export function formatChanges(

package/src/cli/commands/daemon.ts

@@ -1,6 +1,7 @@
 import type { CollectionSyncResult } from "../../ingestion";
 import type { HttpGatewayOverrides } from "../../mcp/http-security";
 import type { BackgroundRuntimeResult } from "../../serve/background-runtime";
+import type { FindingsPassResult } from "../../serve/findings-pass";
 import type { ResidentRuntime } from "../../serve/resident-runtime";
 
 import {
@@ -43,6 +44,29 @@ type DaemonDeps = {
   logger?: DaemonLogger;
 };
 
+/** Silent when clean: only failures, and non-empty writes when not quiet, reach the log. */
+export function logFindingsPassResult(
+  result: FindingsPassResult,
+  logger: DaemonLogger,
+  options: { quiet?: boolean; verbose?: boolean }
+): void {
+  if (result.outcome === "failed") {
+    logger.error(`findings pass failed: ${result.error ?? "unknown error"}`);
+    return;
+  }
+  if (result.outcome === "skipped_lease") {
+    if (options.verbose) logger.log(`findings pass skipped: ${result.error}`);
+    return;
+  }
+  const { counts } = result;
+  const changed =
+    counts.written + counts.reopened + counts.resolved + counts.deleted;
+  if (changed === 0 || options.quiet) return;
+  logger.log(
+    `findings pass: ${counts.written} new, ${counts.reopened} reopened, ${counts.resolved} resolved, ${counts.deleted} expired (${counts.open} open)`
+  );
+}
+
 function formatCollectionSyncSummary(result: CollectionSyncResult): string {
   return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors`;
 }
@@ -146,6 +170,11 @@ export async function daemon(
     index: options.index,
     requireCollections: true,
     offline: options.offline,
+    onFindingsResult: (result) =>
+      logFindingsPassResult(result, logger, {
+        quiet: options.quiet,
+        verbose: options.verbose,
+      }),
     watchCallbacks: {
       onSyncStart: ({ collection, relPaths }) => {
         if (!options.quiet) {
@@ -230,6 +259,12 @@ export async function daemon(
           logger.error(`watch failed: ${failed.collection}: ${failed.reason}`);
         }
       }
+      const findings = (runtime as Partial<ResidentRuntime>).findingsScheduler;
+      if (findings) {
+        logger.log(
+          `findings pass: every ${findings.state.cadence} into "${findings.state.collection}" (report-only)`
+        );
+      }
     }
 
     if (!options.noSyncOnStart) {

package/src/cli/commands/doctor.ts

@@ -21,6 +21,11 @@ import {
   loadConfig,
 } from "../../config";
 import { isConnectorActivationComplete } from "../../core/activation-connector-health";
+import {
+  findingsRunStatePathForIndex,
+  readFindingsRunStatus,
+  resolveFindingsSchedule,
+} from "../../core/findings-run-state";
 import { getCodeChunkingStatus } from "../../ingestion/chunker";
 import { ModelCache } from "../../llm/cache";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
@@ -560,6 +565,69 @@ async function checkSqliteExtensions(): Promise<DoctorCheck[]> {
   return checks;
 }
 
+/**
+ * Report the daemon's scheduled findings pass from its persisted state so a
+ * misconfigured, starved, or failing scheduler is visible without the daemon.
+ */
+export async function checkFindingsPass(
+  config: Config,
+  indexName?: string
+): Promise<DoctorCheck> {
+  const name = "findings-pass";
+  const resolution = resolveFindingsSchedule(config);
+  if (!resolution.ok) {
+    return {
+      name,
+      status: "error",
+      message: "misconfigured",
+      details: [resolution.error],
+    };
+  }
+  if (!resolution.enabled) {
+    return {
+      name,
+      status: "ok",
+      message: "disabled (opt-in via findings.enabled)",
+    };
+  }
+  const status = await readFindingsRunStatus(
+    findingsRunStatePathForIndex(indexName)
+  );
+  const schedule = `every ${resolution.schedule.cadence} into "${resolution.schedule.collection.name}"`;
+  if (!status) {
+    return {
+      name,
+      status: "warn",
+      message: `enabled (${schedule}) but no run state recorded`,
+      details: ["Start gno daemon; the pass only runs inside the daemon."],
+    };
+  }
+  const details = [
+    `last run: ${status.lastRunAt ?? "never"}`,
+    `last success: ${status.lastSuccessAt ?? "never"}`,
+    `next due: ${status.nextDueAt}`,
+  ];
+  if (status.counts) {
+    details.push(
+      `counts: ${status.counts.open} open, ${status.counts.written} new, ${status.counts.resolved} resolved`
+    );
+  }
+  if (status.error) details.push(`error: ${status.error}`);
+  const statusOf: Record<typeof status.state, DoctorCheckStatus> = {
+    pending: "ok",
+    success: "ok",
+    skipped_lease: "warn",
+    overdue: "warn",
+    failed: "error",
+  };
+  return {
+    name,
+    status: statusOf[status.state],
+    message: `${status.state} (${schedule})`,
+    details,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -603,6 +671,9 @@ export async function doctor(
   // Embedding fingerprint freshness
   checks.push(await checkEmbeddingFingerprints(config, options.indexName));
 
+  // Scheduled findings pass (daemon-only, opt-in)
+  checks.push(await checkFindingsPass(config, options.indexName));
+
   const activation = await buildDoctorActivation(config, options);
   checks.push(checkRetrievalActivation(activation));
   const connectorActivation = checkConnectorActivation(activation);