@dotdrelle/wiki-manager 0.15.98 → 0.15.100

package/src/runtime/server.js

@@ -10,6 +10,21 @@ import { tasksAwaitingApproval } from '../orchestrator/dependencyResolver.js';
 import { isActive, isCancelled, isFailed, isSuccessful } from '../orchestrator/taskStatuses.js';
 import { approvalClassForTask } from '../orchestrator/approvalPolicy.js';
 import { RUNTIME_SHUTDOWN_ABORT_REASON } from '../orchestrator/dispatcher.js';
+import {
+  PROACTIVE_REVIEW_CAPABILITY,
+  buildProactiveReviewObjective,
+  createProactiveReviewScheduler,
+  normalizeProactiveConfig,
+} from '../orchestrator/proactiveReviewScheduler.js';
+import {
+  conflictFingerprint,
+  detectConceptConflicts,
+  detectStaleKnowledge,
+  readConceptLeaves,
+  readSourceRegistry,
+  readWikiPages,
+  staleFingerprint,
+} from '../orchestrator/knowledgeSignals.js';
 import { matchSkillInvocation } from '../core/skillInvocation.js';
 import { reconcileControlQueue } from './controlDrain.js';
 import { cancelControlChain, cancelQueuedControlItem } from './controlCancellation.js';
@@ -74,6 +89,17 @@ export function startRuntimeServer({
   exitOnShutdown = process.env.WIKI_MANAGER_RUNTIME_CHILD === '1',
 } = {}) {
   const clients = new Set();
+  // Deterministic dedup/cooldown/budget for proactive reviews; the run itself
+  // stays the normal control-lane path.
+  const proactiveScheduler = createProactiveReviewScheduler({
+    db: store?.db,
+    pendingReviews: store?.getProjection ? () => (store.getProjection().controlQueue ?? [])
+      .filter((item) => item.proactiveReview && ['queued', 'running'].includes(item.status))
+      .map((item) => item.proactiveReview) : null,
+  });
+  // runId -> the review record that started it, so the slot is released exactly
+  // once when the run reaches a terminal state (persisted or not).
+  const proactiveRuns = new Map();
   // Compiled objectives are private execution material. They deliberately do
   // not enter events, projections, SSE, audit output or the runs table.
   // When this runtime process started — used by ensureRuntime to detect that
@@ -860,6 +886,26 @@ export function startRuntimeServer({
   const loginAttemptPruneTimer = setInterval(() => pruneLoginAttempts(), 10 * 60 * 1000);
   loginAttemptPruneTimer.unref?.();
 
+  // The corpus clock. `aged` is caused by TIME, and a workspace that stops
+  // ingesting — precisely the one whose knowledge ages — would otherwise never
+  // re-run the detector; conflicts and vanished paths are edit-caused, so the
+  // ingest moment covers them. This tick therefore reads only the source
+  // registry (staleOnly), and the opt-in gating happens inside the scan.
+  const corpusScanMs = Number(process.env.WIKI_MANAGER_CORPUS_SCAN_INTERVAL_MS ?? 15 * 60 * 1000);
+  const corpusScanTimer = Number.isFinite(corpusScanMs) && corpusScanMs > 0
+    ? setInterval(() => {
+      void (async () => {
+        try {
+          const context = await resolvedGetContext(null);
+          if (!context?.session) return;
+          const workspace = context.workspace ?? context.session.workspace ?? null;
+          if (workspace) emitCorpusSignals(context, workspace, { staleOnly: true });
+        } catch { /* a clock tick never breaks the server */ }
+      })();
+    }, corpusScanMs)
+    : null;
+  corpusScanTimer?.unref?.();
+
   return new Promise((resolve, reject) => {
     server.once('error', reject);
     server.listen(port, host, () => {
@@ -872,6 +918,7 @@ export function startRuntimeServer({
         drainControl: (context) => drainControlQueue(context),
         close: () => new Promise((closeResolve, closeReject) => {
           clearInterval(loginAttemptPruneTimer);
+          if (corpusScanTimer) clearInterval(corpusScanTimer);
           for (const client of clients) client.response.end();
           clients.clear();
           server.close((err) => (err ? closeReject(err) : closeResolve()));
@@ -1029,6 +1076,14 @@ export function startRuntimeServer({
         announceControlLaunch(context.session, body.publicInput ?? body.input, runWorkspace);
       }
     }
+    // The trigger hook and the proactive marker belong to THIS run on the
+    // session; the review that opened it is remembered so its concurrency slot
+    // is released exactly once, whatever terminal state it reaches.
+    if (context.session) context.session._onKnowledgeTrigger = (payload) => handleKnowledgeTrigger(context, payload);
+    if (body.proactiveReview) {
+      if (context.session) context.session._proactiveReview = { ...body.proactiveReview, runId };
+      proactiveRuns.set(runId, body.proactiveReview);
+    }
     const runPromise = run(context, runBody, { signal: context.currentAbortController.signal, runId });
     runPromise
       .catch((err) => {
@@ -1039,6 +1094,12 @@ export function startRuntimeServer({
         context.session?._onRuntimeError?.(err, runId);
       })
       .finally(() => {
+        const proactive = proactiveRuns.get(runId);
+        if (proactive) {
+          proactiveRuns.delete(runId);
+          proactiveScheduler.release(proactive.workspace);
+        }
+        if (context.session?._proactiveReview?.runId === runId) context.session._proactiveReview = null;
         context.running = false;
         context.currentAbortController = null;
         context.currentRunId = null;
@@ -1073,6 +1134,7 @@ export function startRuntimeServer({
         // may still grant the pending run explicitly through --auto-approve.
         ...(item.chainId ? { requireApproval: true } : {}),
         ...(item.capabilityPlan !== undefined ? { capabilityPlan: item.capabilityPlan } : {}),
+        ...(item.proactiveReview ? { proactiveReview: item.proactiveReview } : {}),
         ...(item.chainId
           ? {
             skillChain: {
@@ -1093,6 +1155,179 @@ export function startRuntimeServer({
     });
   }
 
+  /*
+   A knowledge fact is not an order: it is an opportunity, and the workspace
+   says (opt-in) whether it wants one. The decision is deterministic — dedup,
+   cooldown, budget, concurrency — and a refusal is said out loud, never a
+   silent no. An accepted trigger queues a read-only `agent.review` through the
+   normal control lane; nothing here mutates, creates a worktree or sends
+   anything.
+  */
+  function handleKnowledgeTrigger(context, payload) {
+    const session = context?.session ?? null;
+    const workspace = String(payload?.workspace ?? context?.workspace ?? '');
+    const trigger = String(payload?.trigger ?? '');
+    // The corpus detectors are reads that only make sense when the corpus just
+    // changed. They feed this same scheduler — never a second one — and cannot
+    // recurse, since a conflict/stale fact does not re-run the detectors.
+    if (trigger === 'knowledge.ingested' || trigger === 'knowledge.rebuilt') {
+      emitCorpusSignals(context, workspace);
+    }
+    const config = session?.wikircConfig?.proactiveReviews ?? null;
+    let decision;
+    try {
+      decision = proactiveScheduler.decide({
+        workspace, trigger, sourceVersion: payload?.sourceVersion ?? null, config,
+      });
+    } catch (error) {
+      emitRuntimeLog(session, `proactive-review: skipped — budget state unavailable: ${error.message}`);
+      return;
+    }
+    if (decision.action !== 'review') {
+      const inFlight = proactiveScheduler.snapshot(workspace).inFlightTrigger;
+      // The conflict detector runs first, so it can take the only slot; saying
+      // so turns an effect of statement order into a stated precedence.
+      const precedence = decision.reason === 'concurrency' && inFlight
+        ? ` — a ${inFlight} review already holds the slot`
+        : '';
+      emitRuntimeLog(
+        session,
+        `proactive-review: skipped (${decision.reason}${precedence}) for ${workspace || 'workspace'} [${trigger}]`,
+      );
+      return;
+    }
+    const evidence = payload?.evidence ?? null;
+    const record = {
+      id: `review-${randomUUID()}`,
+      workspace,
+      trigger,
+      sourceVersion: decision.sourceVersion,
+      createdAt: new Date().toISOString(),
+      budget: proactiveScheduler.snapshot(workspace),
+      // The deterministic facts, so the filed note says WHAT the scan knew —
+      // not only that a review happened. Persisted with the item's marker.
+      ...(evidence ? { evidence } : {}),
+    };
+    const objective = buildProactiveReviewObjective({
+      trigger,
+      sourceVersion: decision.sourceVersion,
+      evidence,
+    });
+    let item;
+    try {
+      item = enqueueControlRequest(context, objective, {
+        publicInput: objective,
+        // Routing is EXPLICIT. The objective names evidence paths, which could
+        // contain another capability's alias (`report`, `plan`, `check`…), and
+        // the free-text resolver returns null on two hits. Naming the
+        // capability removes that risk entirely.
+        capabilityPlan: { capability: PROACTIVE_REVIEW_CAPABILITY, operation: 'run' },
+        proactiveReview: record,
+      });
+    } catch (error) {
+      // A reservation that never became a queued item must be UNDONE: burning a
+      // budget unit and marking the version seen would silently cancel an audit
+      // that was never enqueued.
+      proactiveScheduler.release(workspace, { undo: true, sourceVersion: decision.sourceVersion });
+      emitRuntimeLog(
+        session,
+        `proactive-review: could not queue the review — ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return;
+    }
+    emitRuntimeLog(
+      session,
+      `proactive-review: queued ${item.id} (${trigger}) for ${workspace || 'workspace'} — ${PROACTIVE_REVIEW_CAPABILITY}, read-only`,
+    );
+    void startNextControlRequest(context);
+  }
+
+  /*
+   The live-corpus read: two homonym leaves under one concept folder are a
+   conflict the ingest plan never sees (they are already written). Pure fs +
+   string work, no model. A conflict set is a stable fingerprint, so the same
+   conflict dedups instead of re-firing every time the corpus is touched.
+  */
+  function emitConflictSignal(context, workspace, session, workspacePath) {
+    const { conflicts, total, dropped } = detectConceptConflicts(readConceptLeaves(workspacePath));
+    if (total === 0) return;
+    if (dropped > 0) {
+      emitRuntimeLog(
+        session,
+        `knowledge-signals: ${total} conflict(s) found, ${dropped} beyond the ceiling are not listed (the fingerprint still counts them)`,
+      );
+    }
+    handleKnowledgeTrigger(context, {
+      workspace,
+      trigger: 'knowledge.conflict_detected',
+      // The fingerprint includes the full count, so a conflict beyond the cap
+      // still moves the version and is not deduped away.
+      sourceVersion: conflictFingerprint(conflicts, total),
+      // The exact facts travel to the agent and the filed note.
+      evidence: { kind: 'conflict', items: conflicts },
+    });
+  }
+
+  function emitStaleSignal(context, workspace, session, workspacePath, config) {
+    const { stale, total, dropped, counts } = detectStaleKnowledge(readSourceRegistry(workspacePath), {
+      rootDir: workspacePath,
+      staleAfterDays: config.staleAfterDays,
+      wikiPages: readWikiPages(workspacePath),
+    });
+    if (total === 0) return;
+    if (dropped > 0) {
+      // Counted PER NATURE: the ceiling hides evidence of several kinds, and a
+      // single "N source(s)" would be false for the others.
+      const breakdown = [
+        counts.aged ? `${counts.aged} aged` : null,
+        counts.orphan ? `${counts.orphan} orphan page(s)` : null,
+        counts.vanishedArchive ? `${counts.vanishedArchive} vanished archive(s)` : null,
+        counts.vanishedPage ? `${counts.vanishedPage} vanished page(s)` : null,
+      ].filter(Boolean).join(', ');
+      emitRuntimeLog(
+        session,
+        `knowledge-signals: stale knowledge — ${breakdown}; ${dropped} beyond the ceiling are not listed`,
+      );
+    }
+    handleKnowledgeTrigger(context, {
+      workspace,
+      trigger: 'knowledge.stale',
+      sourceVersion: staleFingerprint(stale, total),
+      evidence: { kind: 'stale', counts, items: stale },
+    });
+  }
+
+  /*
+   The live-corpus read, run when an ingest/rebuild completes AND on the
+   runtime's clock. The clock matters for `aged`: it is caused by TIME, and a
+   workspace that stops ingesting — precisely the one whose knowledge ages —
+   would otherwise never re-run the detector. Conflicts and vanished paths are
+   caused by edits, so the ingest moment is enough for them; `staleOnly` keeps
+   the periodic tick from re-walking every leaf it does not need.
+  */
+  function emitCorpusSignals(context, workspace, { staleOnly = false } = {}) {
+    const session = context?.session ?? null;
+    // Stay OFF the corpus until the workspace actually opted in: reading every
+    // leaf synchronously on the event loop that also serves both chats' SSE is
+    // a cost the default (disabled) must not pay.
+    const config = normalizeProactiveConfig(session?.wikircConfig?.proactiveReviews);
+    if (!config.enabled) return;
+    const wantsConflicts = !staleOnly && config.triggers.includes('knowledge.conflict_detected');
+    const wantsStale = config.triggers.includes('knowledge.stale');
+    if (!wantsConflicts && !wantsStale) return;
+    const workspacePath = session?.workspacePath;
+    if (!workspacePath) return;
+    try {
+      if (wantsConflicts) emitConflictSignal(context, workspace, session, workspacePath);
+      if (wantsStale) emitStaleSignal(context, workspace, session, workspacePath, config);
+    } catch (error) {
+      emitRuntimeLog(
+        session,
+        `knowledge-signals: a corpus scan failed — ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
   function takePrivateControlInput(session, item) {
     const privateControlInputs = privateControlInputsFor(session);
     const input = privateControlInputs.get(item.id) ?? item.input;
@@ -1592,7 +1827,7 @@ function announceControlLaunch(session, input, workspace) {
  Une file est un passage de témoin : ce qui doit survivre au parent voyage avec
  le message, pas dans l'état de celui qui l'a posté.
 */
-function enqueueControlRequest(context, input, { publicInput = null, capabilityPlan, chainId, chainSequence, skillName, skillExecution, skillStack, selectionKind, optional = false, continueOnFailure = false } = {}) {
+function enqueueControlRequest(context, input, { publicInput = null, capabilityPlan, chainId, chainSequence, skillName, skillExecution, skillStack, selectionKind, optional = false, continueOnFailure = false, proactiveReview = null } = {}) {
   const now = new Date().toISOString();
   const item = {
     id: `control-${randomUUID()}`,
@@ -1609,6 +1844,9 @@ function enqueueControlRequest(context, input, { publicInput = null, capabilityP
     ...(skillExecution ? { skillExecution } : {}),
     ...(Array.isArray(skillStack) && skillStack.length ? { skillStack: [...skillStack] } : {}),
     ...(selectionKind ? { selectionKind } : {}),
+    // The proactive marker rides on the ITEM, so it survives projection and a
+    // runtime restart, and the drain can hand it back to the run it starts.
+    ...(proactiveReview ? { proactiveReview } : {}),
     optional: optional === true,
     continueOnFailure: continueOnFailure === true,
   };

package/src/runtime/store.js

@@ -25,7 +25,7 @@ export { defaultRuntimeStateDir };
 // turn's LLM context. A persisted progress note would be re-read by the model
 // on every later turn as if it were something the user said or Donna answered,
 // growing the context with commentary about work already finished.
-const NON_PERSISTED_EVENT_TYPES = new Set(['runtime_log', 'assistant_progress']);
+const NON_PERSISTED_EVENT_TYPES = new Set(['runtime_log', 'assistant_progress', 'runtime_heartbeat']);
 export const RUNTIME_STORE_SCHEMA_VERSION = 1;
 const RUNTIME_RETENTION_DAYS = 30;
 const TERMINAL_RUN_STATUSES = ['done', 'error', 'cancelled', 'interrupted'];

package/src/runtime/store.test.js

@@ -770,13 +770,17 @@ test('runtime store backfills sequence for legacy event rows', () => {
   store.close();
 });
 
-test('runtime store does not persist runtime logs', () => {
+test('runtime store does not persist runtime logs or liveness beats', () => {
   const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-runtime-'));
   const store = openRuntimeStore({ stateDir });
   store.persistEvent(createAgentEvent('runtime_log', {
     origin: 'runtime',
     payload: { message: 'agentic-loop: turn 1/20' },
   }));
+  store.persistEvent(createAgentEvent('runtime_heartbeat', {
+    origin: 'runtime_provider',
+    payload: { elapsedMs: 30_000 },
+  }));
 
   assert.equal(store.listEvents().length, 0);
   store.close();

package/wiki-workspace

@@ -138,7 +138,6 @@ wiki CLI commands reachable through `wiki <workspace> run`:
   index                             Create or update the local vector index
   refresh                           Regenerate only the stale deliverables
   lint                              Static checks: dead links, orphans, stale deliverables
-  add-skill <source>                Install a workspace method (directory, .zip, HTTPS .zip)
   config                            Show the effective .wikirc.yaml
   doctor, ingest, build, export     Also available directly: wiki <workspace> <command>