freeharness 0.4.1 → 0.4.3

package/dist/adapters/memory/doctor.d.ts

@@ -1,22 +1,59 @@
 import { spawnSync } from "node:child_process";
+import { type StageResult } from "./vendored.js";
+import { type MemoryPaths } from "./paths.js";
+import { type StopResult } from "./worker-control.js";
 export interface CacheVersion {
     version: string;
     dir: string;
     ours: boolean;
     skills: string[];
-    /** Found under the upstream (thedotmack/claude-mem) cache root: a previous FreeHarness
-     * build (pre-rename) or a genuine upstream install, never our current native path. */
+    /** Found under the upstream (thedotmack/claude-mem) cache root: a pre-rename FreeHarness
+     * build or an upstream install, never our native path. */
     legacy: boolean;
 }
+/** What the foreign responder said about itself, already filtered for printing. */
+export interface WorkerFacts {
+    pid?: number;
+    workerPath: string;
+    version: string;
+}
 export interface WorkerProbe {
     port: number;
     reachable: boolean;
     version?: string;
-    viewer?: boolean;
+    /** Set when reachable: the engine's rule applied to the /api/health answer and the free-mem PID file. */
+    identity?: "ours" | "ours-stale" | "foreign";
+    /** Set when reachable: `identity !== "foreign"`. */
     ours?: boolean;
+    foreign?: WorkerFacts;
+    /** Absent when the worker predates the parked field of /api/health. */
+    parked?: ParkedHealth;
+    /** Absent when the worker predates the embeddings field of /api/health. */
+    embeddings?: EmbeddingsHealth;
 }
-/** Marker in the FreeHarness viewer page served on GET / (plugin/ui/viewer.html). */
-export declare const VIEWER_MARKER = "FreeHarness memory";
+/** The `embeddings` field of /api/health: the vector stream of the configured model. */
+export interface EmbeddingsHealth {
+    state: "off" | "ready" | "backfilling" | "degraded" | "unreachable";
+    reason: "unset" | "refused" | null;
+    /** Null while off: none configured, so no model or floor is shown. */
+    model: string | null;
+    maxDistance: number;
+    embedded: number;
+    failed: number;
+    total: number;
+    lastErrorClass: string | null;
+    otherModels: {
+        model: string;
+        count: number;
+    }[];
+}
+/** The `parked` field of /api/health: quota-paused sessions whose buffer holds work, in worker memory only. */
+export interface ParkedHealth {
+    count: number;
+    oldestAgeMs: number | null;
+}
+/** The /api/health product marker of our worker; a test pins it to the engine's and the hooks' copies. */
+export declare const FREE_MEM_PRODUCT = "free-mem";
 /** Mirror of engine shared/observer-health.ts: warn only after this many consecutive failures. */
 export declare const OBSERVER_UNHEALTHY_FAILURE_THRESHOLD = 3;
 /** Mirror of engine shared/quota-cooldown.ts: how long requests are withheld after a quota refusal. */
@@ -111,6 +148,17 @@ export declare function isObserverVerdictStale(ledger: ObserverHealth | null, no
 export declare function observerLines(s: ObserverStatus, now?: number): string[];
 /** Highest schema_versions row our vendored SessionStore applies (13.24.0 port; the upstream v50 observed_model/observed_billing migration is telemetry-only and not ported). */
 export declare const OUR_SCHEMA_VERSION = 49;
+/**
+ * Build the schema status line. Upstream and FreeHarness versions are split at 9000 so a
+ * FreeHarness migration is never reported as a newer upstream engine. A store that records
+ * some FreeHarness versions but not all of them has not finished migrating (a migration
+ * rolled back, or the worker predates the update), so the line warns and names each missing
+ * version; a store with none was never opened by a FreeHarness worker and keeps the upstream verdict.
+ *
+ * Returns:
+ *   The line, or null when the db/sqlite3 is unavailable.
+ */
+export declare function schemaVersionLine(dbPath: string, dbName: string): string | null;
 /** One (window, model) group from the `observations` table. */
 export interface SpendRow {
     window: "today" | "seven_day";
@@ -133,18 +181,29 @@ export interface SpendUnavailable {
 /**
  * Reads observer spend (observation count and summed `discovery_tokens`) grouped by day
  * window and `generated_by_model`, through `sqlite3 -readonly` (same invocation shape as
- * `dbSchemaVersion`). The seven-day window includes today, matching the running total an
+ * `dbSchemaVersions`), plus each model's `consolidation_calls` tokens: consolidation
+ * observations carry `discovery_tokens` 0, and the cost-tracker hook's `observerSink` counts
+ * the same rows. The seven-day window includes today, matching the running total an
  * owner reads off `memory status` (not "the other six days").
  *
  * Args:
  *   dbPath: Path of claude-mem.db.
- *   spawn: Injectable spawnSync, so the missing-binary path is deterministic in tests
- *     regardless of whether sqlite3 happens to be on the test machine's PATH.
+ *   spawn: Injectable spawnSync, so a test of the missing-binary path does not depend on sqlite3 being on PATH.
  *
  * Returns:
  *   One row per (window, model) with a row, or the reason spend could not be read.
  */
 export declare function observerSpend(dbPath: string, spawn?: SpawnSyncFn): SpendRow[] | SpendUnavailable;
+/**
+ * The capture pipeline and retrieval health as INFO lines: spool backlog and drops,
+ * consolidation jobs by status, the rules tier's share of the last 7 days' observations, the
+ * search streams, the last gc run, the feedback counts and the parked batches the worker
+ * reports. Anything unreadable prints `n/a` rather than failing the report.
+ *
+ * Args:
+ *   worker: The /api/health probe; omitted, the worker counts as not answering.
+ */
+export declare function pipelineLines(dataDir: string, dbPath: string, spawn?: SpawnSyncFn, worker?: Pick<WorkerProbe, "reachable" | "parked" | "embeddings">): string[];
 /**
  * Model ids that name metered Claude spend: the `claude-*` families, a bare tier alias
  * (`haiku`, `sonnet`, `opus`, alone or with a `-` suffix) and the `$TIER:` placeholder the
@@ -194,6 +253,10 @@ export interface LocalProviderLogSummary {
     skippedLines: number;
     /** True when the file exceeded the read cap and only its tail was scanned (see `readLocalProviderLog`'s `maxBytes`). */
     truncated: boolean;
+    /** Batches marked `degraded: true` today, keyed by `tier`; empty when Claude never paused today. */
+    degraded: Record<string, number>;
+    /** `paused_window` values seen on today's degraded batches, keyed by window name. */
+    pausedWindows: Record<string, number>;
 }
 /** A present but unreadable batch log (permissions, I/O), distinct from one that does not exist. */
 export interface LocalProviderLogUnavailable {
@@ -215,7 +278,7 @@ export interface LocalProviderLogUnavailable {
  *
  * Returns:
  *   The day's batch/fallback counts and whether the read was truncated; null when the log file
- *   does not exist yet (a fresh `CLAUDE_MEM_PROVIDER=claude` machine has never written one);
+ *   does not exist yet (a fresh `FREE_MEM_PROVIDER=claude` machine has never written one);
  *   the reason when the file is there but could not be read, which is a different state from
  *   an absent log and gets its own printed line.
  */
@@ -252,10 +315,12 @@ export interface DuplicateStats {
 export declare function observerDuplicateRate(dbPath: string, spawn?: SpawnSyncFn): DuplicateStats | SpendUnavailable;
 /**
  * Renders the local-provider log summary and near-duplicate rate as printable INFO lines: the
- * batch/fallback line, then the near-duplicate-rate line (omitted when the rate could not be
- * read). Nothing at all when `summary` is null (no `local-provider.jsonl` yet); a single WARN
- * naming the reason when the log is present but unreadable, so a permission or I/O failure
- * never reads like a machine that has not run the local provider.
+ * batch/fallback line, the degraded-day line (present only when today has at least one
+ * `degraded: true` batch, naming the tier breakdown and the most frequent `paused_window`),
+ * then the near-duplicate-rate line (omitted when the rate could not be read). Nothing at all
+ * when `summary` is null (no `local-provider.jsonl` yet); a single WARN naming the reason when
+ * the log is present but unreadable, so a permission or I/O failure never reads like a machine
+ * that has not run the local provider.
  *
  * Args:
  *   summary: `readLocalProviderLog`'s return value.
@@ -288,14 +353,14 @@ export declare function effectiveObserverModels(settingsPath: string): Effective
 /** Which provider the observer actually runs on, and its model when that provider is local. */
 export interface ObserverProvider {
     provider: "claude" | "local";
-    /** `CLAUDE_MEM_LOCAL_MODEL` (or the engine's `local-model` default) when `provider` is
+    /** `FREE_MEM_LOCAL_MODEL` (or the engine's `local-model` default) when `provider` is
      * `local`; null when `provider` is `claude` (no local model is in play). */
     model: string | null;
 }
 /**
- * Effective observer provider: `CLAUDE_MEM_PROVIDER` from settings.json (default `claude`; any
+ * Effective observer provider: `FREE_MEM_PROVIDER` from settings.json (default `claude`; any
  * value other than the literal `local` is treated as `claude`, mirroring the engine's own
- * `SettingsDefaultsManager` fallback), and when local, the configured `CLAUDE_MEM_LOCAL_MODEL`
+ * `SettingsDefaultsManager` fallback), and when local, the configured `FREE_MEM_LOCAL_MODEL`
  * or the engine's `local-model` default.
  *
  * Args:
@@ -306,16 +371,17 @@ export interface ObserverProvider {
  */
 export declare function effectiveObserverProvider(settingsPath: string): ObserverProvider;
 /**
- * The FreeHarness-recommended observer settings: a haiku base and simple tier (the daily-spend
- * gate), a sonnet summary tier (session summaries read by every future session, worth the
- * larger model), the upstream skip list extended with the tools whose decisions matter for
- * recall (Read, Glob, Grep and the multi-agent tools), and a concurrency cap of 2. Shared by
- * `memory status`'s WARN check and the `memory settings` command.
+ * The FreeHarness-recommended observer settings: Haiku on every tier, because the summary tier
+ * alone spent 25.4M Sonnet tokens in a week, and the claude provider, because a local provider
+ * running beside it doubled the observer work. The skip list extends the upstream one with
+ * the read-only and multi-agent tools, which carry no decision worth recording, and
+ * concurrency is capped at 2. Shared by `memory status`'s WARN checks and the `memory
+ * settings` command.
  */
 export declare const RECOMMENDED_OBSERVER_SETTINGS: Record<string, string>;
 /**
  * `memory settings --no-local`: the two keys that return the observer to the Claude provider —
- * `CLAUDE_MEM_PROVIDER` and `CLAUDE_MEM_SKIP_TOOLS` restored to the recommended default, so the
+ * `FREE_MEM_PROVIDER` and `FREE_MEM_SKIP_TOOLS` restored to the recommended default, so the
  * skip list follows the provider back.
  */
 export declare const NO_LOCAL_OBSERVER_SETTINGS: Record<string, string>;
@@ -342,8 +408,8 @@ export interface ObserverSettingsPreview {
 /**
  * Previews `memory settings`: the selected key set against the current file, same or
  * would-change, writing nothing. Plain (no options): the five recommended keys. `--local`:
- * `CLAUDE_MEM_PROVIDER` plus the four `CLAUDE_MEM_LOCAL_*` keys plus the narrowed
- * `CLAUDE_MEM_SKIP_TOOLS`. `--no-local`: `CLAUDE_MEM_PROVIDER` and `CLAUDE_MEM_SKIP_TOOLS`
+ * `FREE_MEM_PROVIDER` plus the four `FREE_MEM_LOCAL_*` keys plus the narrowed
+ * `FREE_MEM_SKIP_TOOLS`. `--no-local`: `FREE_MEM_PROVIDER` and `FREE_MEM_SKIP_TOOLS`
  * restored to the recommended default.
  *
  * Args:
@@ -366,7 +432,8 @@ export interface ApplyObserverSettingsResult {
 }
 /**
  * Applies `memory settings`: adds or updates the selected key set (see `previewObserverSettings`
- * for which set), preserving every other key, after backing up an existing file first. Refuses
+ * for which set) and drops each written key's `CLAUDE_MEM_` twin, preserving every other key,
+ * after backing up an existing file first. Refuses
  * (throws) without writing anything when `opts` fails validation or the existing file is not
  * valid JSON.
  *
@@ -399,8 +466,8 @@ export interface MemoryProviderProbe {
  * Down is a one-line reason, never a throw.
  *
  * Args:
- *   baseUrl: `CLAUDE_MEM_LOCAL_BASE_URL`.
- *   model: `CLAUDE_MEM_LOCAL_MODEL`.
+ *   baseUrl: `FREE_MEM_LOCAL_BASE_URL`.
+ *   model: `FREE_MEM_LOCAL_MODEL`.
  *   timeoutMs: The whole probe's deadline (both requests together).
  *
  * Returns:
@@ -409,7 +476,7 @@ export interface MemoryProviderProbe {
 export declare function probeMemoryProvider(baseUrl: string, model: string, timeoutMs?: number): Promise<MemoryProviderProbe>;
 /**
  * The `memory provider` doctor line: only when the data dir's settings.json sets
- * `CLAUDE_MEM_PROVIDER=local`, a probe of the configured base URL and model, OK or WARN with
+ * `FREE_MEM_PROVIDER=local`, a probe of the configured base URL and model, OK or WARN with
  * the reason; absent or `claude` prints nothing.
  *
  * Args:
@@ -422,13 +489,26 @@ export declare function probeMemoryProvider(baseUrl: string, model: string, time
 export declare function memoryProviderLines(settingsPath: string, probe?: (baseUrl: string, model: string, timeoutMs?: number) => Promise<MemoryProviderProbe>): Promise<string[]>;
 /** Resolve $CLAUDE_CONFIG_DIR or ~/.claude. */
 export declare function configDir(): string;
-/** Mirror engine shared/paths.ts resolveDataDir (env, then settings.json, then default). */
+/** The engine's data directory and database for this process. */
+export declare function memoryPaths(): MemoryPaths;
 export declare function dataDir(): string;
+/** One WARN per ignored `CLAUDE_MEM_*` variable in `env` and key in the settings file, naming its replacement. */
+export declare function deprecatedNameLines(env: Record<string, string | undefined>, settingsPath: string): string[];
+/** A WARN while a legacy database sits beside a free-mem store with no observation: the worker creates
+ *  an empty store at its first start, so existence cannot silence it; an unreadable store stays silent. */
+export declare function legacyHomeLines(env: Record<string, string | undefined>, home: string, spawn?: SpawnSyncFn): string[];
+/** Engine worker port: env, then settings.json, then 37700 + uid % 100. */
+export declare function workerPort(dir: string): number;
+/** One WARN while the upstream plugin is still registered: both workers bind the same port. */
+export declare function upstreamLines(cfg: string, port: number): string[];
+/** Steps that clear a reachable foreign worker, else null; no-pid fallback as in foreignWorkerLine. */
+export declare function foreignWorkerStep(worker: WorkerProbe): string | null;
 /**
  * Diagnose which claude-mem is active.
  *
  * Returns:
- *   A MemoryDiagnosis with a verdict and printable lines (OK/WARN prefixed).
+ *   A MemoryDiagnosis with a verdict and printable lines (OK/WARN/INFO prefixed; FAIL for a
+ *   foreign worker on the memory port).
  */
 export declare function diagnoseMemory(): Promise<MemoryDiagnosis>;
 /**
@@ -461,20 +541,79 @@ export interface RestartResult {
  *   What was (or would be) done.
  */
 export declare function restartWorker(dryRun: boolean, diagnosis?: MemoryDiagnosis): Promise<RestartResult>;
+/**
+ * Stops the worker without starting another, then waits until its pid file names no live process
+ * and its port is closed.
+ * @param mode Only `shutdown`.
+ * @param opts Data dir and port (the resolved ones by default) and the wait bound in ms.
+ * @returns Whether it stopped, whether one was running, and the reason on timeout.
+ */
+export declare function stopWorker(mode: "shutdown", opts?: {
+    dir?: string;
+    port?: number;
+    timeoutMs?: number;
+}): Promise<StopResult>;
+/** Whether a worker answers on the data dir's worker port right now. */
+export declare function workerRunning(): Promise<boolean>;
+/** The engine's log file for a day, where a failed worker start leaves its reason. */
+export declare function workerLogPath(now?: Date): string;
+/** Restart decision after a plugin-cache stage; `error` and `log` never fail the command. */
+export interface StageRestart {
+    planned: boolean;
+    reason: string;
+    result?: RestartResult;
+    error?: string;
+    log?: string;
+}
+/**
+ * Restart a worker that was running before the command when the command staged a different build
+ * or stopped that worker itself; a worker that was not running stays stopped. A failed
+ * restart, including a launched worker that never answers health or an old worker that never
+ * gives way to a new one, is reported, never thrown.
+ *
+ * Args:
+ *   wasRunning: Whether a worker answered before the command changed anything.
+ *   cause: Whether the command staged a build or stopped the worker.
+ *   dryRun: Report only.
+ *   healthMs: How long a launched worker has to answer `/api/health`.
+ *
+ * Returns:
+ *   The decision and, on apply, its outcome.
+ */
+export declare function restartAfterStage(wasRunning: boolean, cause: {
+    staged: boolean;
+    stopped?: boolean;
+}, dryRun: boolean, healthMs?: number): Promise<StageRestart>;
 export interface ActivateResult {
     stoppedWorker: boolean;
     disabled: string[];
     registered: boolean;
+    stage?: StageResult & {
+        cacheDir: string;
+        version: string;
+    };
+    /** The staging notes, or why the cached build is registered as is. */
+    stageNotes: string[];
+    restart: StageRestart;
 }
 /**
- * Make the FreeHarness build the only active claude-mem: stop a running worker, move
- * foreign cache versions aside (never deleted), point installed_plugins at ours.
+ * Make the FreeHarness build the only active claude-mem: stage the vendored build when it is
+ * built and differs from the cache, stop a running worker, move foreign cache versions aside
+ * (never deleted), point installed_plugins at ours, and restart the worker it stopped.
+ * Staging runs first, so a staging failure leaves a running worker up.
  *
  * Args:
  *   dryRun: Report only.
+ *   opts: The vendored plugin dir; without it the newest cached build is registered as is.
  *
  * Returns:
  *   What was (or would be) done.
+ *
+ * Raises:
+ *   Error: When the cache holds no FreeHarness build, the plugin version is not semver, staging
+ *     fails, or deps need a missing Bun (refused before any cache write).
  */
-export declare function activateOurs(dryRun: boolean): Promise<ActivateResult>;
+export declare function activateOurs(dryRun: boolean, opts?: {
+    pluginDir?: string;
+}): Promise<ActivateResult>;
 export {};