@wrongstack/core 0.296.4 → 0.298.0

package/dist/types/config/mcp-features.d.ts

@@ -215,13 +215,27 @@ export interface SageConfig {
          * Memories below it stay searchable but are never auto-injected.
          */
         minImportance?: number | undefined;
+        /**
+         * Minimum relation strength for automatic injection. Memories whose
+         * anchor's relation strength falls below this bar are rejected before
+         * the composite score is consulted. Default: 0.85.
+         */
+        relationFloor?: number | undefined;
         /**
          * Cooldown before an already-injected memory may be injected again.
          * Default: 0 — once per session. A positive value restores time-boxed
          * repeats.
          */
         repeatCooldownMs?: number | undefined;
-        triggers?: Partial<Record<'read' | 'tree' | 'grep' | 'glob' | 'codebase_search' | 'bash' | 'write' | 'edit' | 'patch', boolean>> | undefined;
+        /**
+         * Which tools trigger SAGE memory injection on their results.
+         * Supported triggers: read, tree, grep, glob, codebase_search,
+         * write, edit, patch. Bash/exec are intentionally excluded —
+         * command-execution tools do not produce file-path-anchored
+         * results that are useful for memory injection.
+         * Default: all supported triggers enabled.
+         */
+        triggers?: Partial<Record<'read' | 'tree' | 'grep' | 'glob' | 'codebase_search' | 'write' | 'edit' | 'patch', boolean>> | undefined;
     } | undefined;
     retrieval?: {
         /**

package/dist/types/config/root.d.ts

@@ -1,11 +1,11 @@
 import type { ConfiguredHook, HookEvent } from '../hooks.js';
+import type { AutonomyConfig, ChronicleConfig, IndexingConfig, LaunchConfig, SessionLoggingConfig, SyncConfig } from './autonomy.js';
 import type { AdaptiveConcurrencyConfig, CircuitBreakerRuntimeConfig, ContextConfig } from './context.js';
+import type { FeaturesConfig, LogConfig, MCPServerConfig, PluginConfig, PluginManagerConfig, SageConfig } from './mcp-features.js';
+import type { CustomModelDefinition, ModelMatrixEntry, ProviderConfig } from './providers.js';
 import type { HqClientConfig, ModelRuntimeConfig, SystemPromptConfig } from './runtime.js';
+import type { BrainConfig, FleetConfig, SkillsConfig } from './skills-fleet-brain.js';
 import type { ToolsConfig } from './tools.js';
-import type { ProviderConfig, CustomModelDefinition, ModelMatrixEntry } from './providers.js';
-import type { MCPServerConfig, LogConfig, FeaturesConfig, SageConfig, PluginConfig, PluginManagerConfig } from './mcp-features.js';
-import type { AutonomyConfig, ChronicleConfig, IndexingConfig, LaunchConfig, SessionLoggingConfig, SyncConfig } from './autonomy.js';
-import type { SkillsConfig, FleetConfig, BrainConfig } from './skills-fleet-brain.js';
 export interface GitBehaviorConfig {
     /**
      * Commit identity injected as `GIT_AUTHOR_NAME/EMAIL` +
@@ -94,6 +94,12 @@ export interface Config {
      * `createFallbackModelExtension`.
      */
     fallbackModels?: string[] | undefined;
+    /**
+     * A single emergency continuity route tried before the normal fallback
+     * chain. Must be a full `provider/model` reference so it can escape the
+     * active provider's failure domain.
+     */
+    fallbackBridge?: string | undefined;
     /**
      * Named fallback chains. A profile's first entry can be used as a primary
      * model by `/setmodel`, while the whole ordered list is used for failover.

package/dist/types/context-window.d.ts

@@ -2,6 +2,21 @@ export type ContextWindowModeId = 'balanced' | 'frugal' | 'deep';
 export type DeprecatedContextWindowModeId = 'archival';
 export type ContextWindowModeSelectionId = ContextWindowModeId | DeprecatedContextWindowModeId;
 export type ContextWindowAggressiveOn = 'hard' | 'soft' | 'warn';
+/**
+ * Context-window usage snapshot returned by the host's `onResumeSession`
+ * callback when a session is resumed. The TUI reducer seeds
+ * `state.leader.ctxTokens` / `state.leader.ctxMaxTokens` from this snapshot
+ * so the statusline chip and `/context` panel reflect the rebuilt context
+ * immediately, instead of staying at zero until the next ctx.pct event.
+ * Single source of truth — do not redeclare as an inline structural type at
+ * call sites; import this named type instead so the contract cannot drift.
+ */
+export interface ContextSnapshot {
+    /** Estimated total tokens currently in the context window. */
+    tokens: number;
+    /** Provider max context in tokens for the active model. */
+    maxContext: number;
+}
 export interface ContextWindowThresholds {
     warn: number;
     soft: number;

package/dist/types/index.d.ts

@@ -47,7 +47,7 @@ export type { ModelsDevModel, ModelsDevPayload, ModelsDevProvider, ModelsDevReas
 export { DEFAULT_MODES } from './mode.js';
 export type { Mode, ModeConfig, ModeManifest, ModeStore } from './mode.js';
 export { CONTEXT_WINDOW_MODES, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy } from './context-window.js';
-export type { ContextWindowAggressiveOn, ContextWindowConfigLike, ContextWindowMode, ContextWindowModeId, ContextWindowModeSelectionId, ContextWindowPolicy, ContextWindowThresholds, DeprecatedContextWindowModeId } from './context-window.js';
+export type { ContextSnapshot, ContextWindowAggressiveOn, ContextWindowConfigLike, ContextWindowMode, ContextWindowModeId, ContextWindowModeSelectionId, ContextWindowPolicy, ContextWindowThresholds, DeprecatedContextWindowModeId } from './context-window.js';
 export type { CompletedWorkEvidence, CompletedWorkSource, ContextEvidenceState, ContextFileEvidence, ContextIntentEvidence, ContextRepeatedReadEvidence, ToolEvidenceStatus, ToolOutputMetadata } from './context-evidence.js';
 export type { CouncilDistinctness, CouncilLLMCaller, CouncilModelTarget, CouncilOption, CouncilPersona, CouncilProfileConfig, CouncilQuestion, CouncilResolutionMethod, CouncilResult, CouncilSeatConfig, CouncilUsage, CouncilVoteResult, CouncilVoteStatus, ResolvedCouncilProfile, ResolvedCouncilSeat } from './council.js';
 export type { AwaitAnyResult, CoordinatorEvents, CoordinatorStatus, DoneCondition, MultiAgentConfig, MultiAgentCoordinator, SpawnResult, SubagentConfig, SubagentContext, SubagentError, SubagentErrorKind, SubagentPartialResult, SubagentRunContext, SubagentRunOutcome, SubagentRunner, SubagentSpawnLineage, SubagentStructuredReport, TaskDelegation, TaskResult, TaskSpec } from './multi-agent.js';

package/dist/types/observability.d.ts

@@ -14,6 +14,12 @@ export interface MetricsSink {
     gauge(name: string, value: number, labels?: MetricLabels): void | undefined;
     /** Point-in-time export — for /metrics scrape, debug dumps, tests. */
     snapshot(): MetricsSnapshot;
+    /**
+     * Cumulative count of observations dropped by the sink (e.g. a
+     * high-cardinality label guard that refused new series). Returns 0 for
+     * sinks without a cap.
+     */
+    droppedObservations(): number;
     /** Reset all metrics. Useful for tests; production code should rarely use. */
     reset(): void;
 }
@@ -25,8 +31,15 @@ export interface MetricSeries {
     values: Record<string, number>;
 }
 export interface MetricsSnapshot {
+    /** Snapshot time (epoch ms). */
     timestamp: number;
     series: MetricSeries[];
+    /**
+     * Per-metric observation drops since the sink was created (or last reset).
+     * Names mirror `MetricSeries.name`. `droppedObservations` is undefined on
+     * sinks without a cardinality cap.
+     */
+    droppedObservations?: Record<string, number> | undefined;
 }
 /** Safe host-level status surfaced by `/metrics`; contains no endpoint or credentials. */
 export interface MetricsRuntimeStatus {

package/dist/types/secret-vault.d.ts

@@ -22,6 +22,14 @@ export interface SecretVault {
     isEncrypted(value: string): boolean;
     /** Current key version. Starts at 1; incremented by `rotateKey()`. */
     readonly keyVersion: number;
+    /**
+     * Flush any pending asynchronous key-file hardening (e.g. Windows ACL
+     * restrictions via icacls). Callers in async contexts should await this
+     * before returning so a short-lived process does not exit before the
+     * hardening promise resolves. Sync-only callers may skip it — the
+     * hardening remains best-effort in that case.
+     */
+    flushHardening?(): Promise<void>;
 }
 /**
  * RotatableSecretVault extends SecretVault with key rotation support.

package/dist/types/session.d.ts

@@ -547,6 +547,8 @@ export interface SessionStore {
      * filesystem isolation is the caller's worktree/CAS responsibility.
      */
     fork?(id: string, opts?: SessionForkOptions): Promise<ForkedSession>;
+    /** Capture a content-addressed identity for the current project workspace. */
+    captureWorkspaceCheckpoint?(sessionId: string, promptIndex: number): Promise<WorkspaceCheckpointRef | undefined>;
     /** Apply a captured workspace manifest to an already-isolated checkout. */
     materializeWorkspaceCheckpoint?(checkpoint: WorkspaceCheckpointRef, targetRoot: string): Promise<WorkspaceMaterializationResult>;
     list(limit?: number): Promise<SessionSummary[]>;
@@ -619,6 +621,46 @@ export interface SessionWriter {
      * on the Context.
      */
     traceId?: string | undefined;
+    /**
+     * Optional callback invoked synchronously after each event is scrubbed
+     * and observed for summary, immediately before it enters the write
+     * buffer. The event has been scrubbed (PII removed) and observed
+     * (counters updated) but NOT yet written to disk.
+     *
+     * When the event originates from {@link appendBatch}, this callback is
+     * ALSO invoked for each individual event in the batch, in addition to
+     * the {@link onAppendBatch} callback (which fires once for the whole
+     * batch). Subscribing to both will therefore receive each batch event
+     * twice — design consumers to subscribe to either per-event or batch,
+     * not both, unless deduplication is handled.
+     *
+     * The callback must not throw — errors are silently swallowed to
+     * preserve the best-effort contract of session logging. If the
+     * callback needs async work, it should fire-and-forget rather than
+     * blocking the append.
+     *
+     * Used by the HQ telemetry bridge to stream events without reading
+     * them back from the JSONL file on disk.
+     */
+    onAppend?: ((event: SessionEvent) => void) | undefined;
+    /**
+     * Batch variant of {@link onAppend}. Called once per batch with
+     * the already-scrubbed event array, after all have been observed
+     * and after the per-event {@link onAppend} has already fired for
+     * each event in the batch. Subscribing to both callbacks will
+     * receive every batch event twice.
+     */
+    onAppendBatch?: ((events: SessionEvent[]) => void) | undefined;
+    /**
+     * Set or replace the {@link onAppend} callback after construction.
+     * The previous callback (if any) is discarded. Used by telemetry bridges
+     * that receive the writer as an already-created dependency.
+     */
+    setOnAppend?(cb: ((event: SessionEvent) => void) | undefined): void;
+    /**
+     * Set or replace the {@link onAppendBatch} callback after construction.
+     */
+    setOnAppendBatch?(cb: ((events: SessionEvent[]) => void) | undefined): void;
     /**
      * Absolute path to the JSONL file this writer appends to, when one
      * exists. In-memory writers (tests, ephemeral sessions) leave it

package/dist/types/skill.d.ts

@@ -1,11 +1,23 @@
 export interface SkillManifest {
     name: string;
     description: string;
+    /**
+     * Optional explicit "Use when…" trigger from frontmatter. When present it is
+     * used verbatim as the SkillEntry trigger; otherwise the trigger falls back
+     * to the first sentence of `description` (see parseDescriptionFromText).
+     */
+    trigger?: string | undefined;
     version?: string | undefined;
     /** agentskills.io optional frontmatter fields. */
     license?: string | undefined;
     compatibility?: string | undefined;
     metadata?: Record<string, string> | undefined;
+    /**
+     * agentskills.io `allowed-tools`. INFORMATIONAL ONLY — parsed from frontmatter
+     * and surfaced for display, but never enforced: the `skill` tool has fixed
+     * permissions/capabilities and does not consult this field, so it neither
+     * grants nor restricts any tool.
+     */
     allowedTools?: string[] | undefined;
     path: string;
     /**
@@ -29,6 +41,43 @@ export interface SkillEntry {
     originTool?: string | undefined;
     path: string;
 }
+/**
+ * A skill directory that was discovered but rejected during `list()`. Surfaced
+ * via {@link SkillLoader.diagnostics} so a skill that silently fails to load
+ * (missing name/description, malformed name) is diagnosable instead of simply
+ * vanishing from the available-skills list.
+ */
+export interface SkippedSkill {
+    /** Absolute directory that contained the rejected `SKILL.md`. */
+    dir: string;
+    /** Directory entry name (the folder name under a skills root). */
+    entry: string;
+    /** Why the skill was rejected. */
+    reason: 'missing-name' | 'missing-description' | 'invalid-name-format';
+    /** The parsed `name` when one was present (absent for `missing-name`). */
+    name?: string | undefined;
+}
+/**
+ * A skill that was excluded because a higher-priority discovery layer already
+ * claimed the same name. The canonical case is a project-local skill shadowing
+ * a maintained bundled skill. Surfaced via {@link SkillLoader.diagnostics}.
+ */
+export interface ShadowedSkill {
+    name: string;
+    /** Discovery layer of the shadowed (hidden) skill. */
+    source: SkillManifest['source'];
+    /** Path to the shadowed skill's `SKILL.md`. */
+    path: string;
+    /** Discovery layer that claimed the name first (won the shadow). */
+    shadowedBy: SkillManifest['source'] | 'unknown';
+    /** Path to the winning skill's `SKILL.md`, when known. */
+    shadowedByPath?: string | undefined;
+}
+/** Load-time diagnostics collected during {@link SkillLoader.list}. */
+export interface SkillLoaderDiagnostics {
+    skipped: SkippedSkill[];
+    shadowed: ShadowedSkill[];
+}
 export interface SkillLoader {
     list(): Promise<SkillManifest[]>;
     /** Structured entries with trigger/scope for system prompt rendering. */
@@ -44,5 +93,12 @@ export interface SkillLoader {
     readSaveBody(name: string): Promise<string>;
     /** Clear the internal cache so the next list/find re-reads from disk. */
     invalidateCache(): void;
+    /**
+     * Load-time diagnostics from the most recent full `list()` scan: skills that
+     * were skipped as malformed and skills shadowed by a higher-priority layer.
+     * Optional so lightweight/mock loaders need not implement it; callers must
+     * feature-detect (`loader.diagnostics?.()`).
+     */
+    diagnostics?(): SkillLoaderDiagnostics;
 }
 //# sourceMappingURL=skill.d.ts.map

package/dist/types/tool-executor.d.ts

@@ -68,6 +68,8 @@ export interface ToolExecutorOptions {
     iterationTimeoutMs?: number | undefined;
     /** Hard upper bound for a single tool call timeout. Defaults to 5 minutes. */
     maxToolTimeoutMs?: number | undefined;
+    /** Maximum tools started concurrently by parallel/smart batches. Defaults to 4. */
+    maxParallelTools?: number | undefined;
     perIterationOutputCapBytes?: number | undefined;
     /**
      * Optional lifecycle hook runner. When present, `PreToolUse` hooks run

package/dist/utils/continuous-memory-profiler.d.ts

@@ -0,0 +1,35 @@
+export interface MemoryAllocationStack {
+    bytes: number;
+    objects: number;
+    frames: string[];
+}
+export interface MemoryAllocationSummary {
+    sampledBytes: number;
+    sampledObjects: number;
+    sampleCount: number;
+    topStacks: MemoryAllocationStack[];
+}
+export interface MemoryProfileArtifact {
+    backend: 'datadog-pprof' | 'node-inspector';
+    data: Buffer | string;
+    extension: '.heapprofile' | '.pb.gz';
+    summary?: MemoryAllocationSummary | undefined;
+}
+export interface ContinuousMemoryProfiler {
+    readonly backend: MemoryProfileArtifact['backend'];
+    capture(): Promise<MemoryProfileArtifact>;
+    stop(): Promise<void>;
+}
+export interface ContinuousMemoryProfilerStart {
+    profiler: ContinuousMemoryProfiler;
+    fallbackReason?: string | undefined;
+}
+/**
+ * Start allocation sampling inside the current process.
+ *
+ * The native pprof backend samples continuously without opening an inspector
+ * port. The optional dependency may be missing on unsupported platforms, so
+ * Node's built-in Inspector sampling remains a functional fallback.
+ */
+export declare function startContinuousMemoryProfiler(): Promise<ContinuousMemoryProfilerStart>;
+//# sourceMappingURL=continuous-memory-profiler.d.ts.map

package/dist/utils/env-typed.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Typed environment-variable parsing helpers.
+ *
+ * Every `process.env[...]` read in the codebase should go through these
+ * helpers so that:
+ *
+ * 1. Invalid values get a typed fallback instead of `NaN` or an empty string.
+ * 2. The fallback is visible at the call site, not buried in a downstream check.
+ * 3. Range constraints are expressed at the read site, not scattered.
+ *
+ * Usage:
+ *   ```ts
+ *   const idleMs = envInt('WRONGSTACK_IDLE_MS', { default: 30_000, min: 100 });
+ *   const enabled = envBool('WRONGSTACK_FEATURE_ENABLED');
+ *   const url = envString('WRONGSTACK_BASE_URL');
+ *   ```
+ */
+/**
+ * Parse an environment variable as a boolean.
+ * Returns `false` for unset, empty, `0`, `false`, `no`, `off` (case-insensitive).
+ * Returns `true` for any other non-empty value.
+ */
+export declare function envBool(key: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Parse an environment variable as a boolean, returning `undefined` when unset.
+ * Unlike {@link envBool}, this distinguishes "not set" from "set to false".
+ */
+export declare function envBoolOptional(key: string, env?: NodeJS.ProcessEnv): boolean | undefined;
+/**
+ * Parse an environment variable as an integer with optional range constraints.
+ * Returns `options.default` when unset or unparseable.
+ *
+ * When `min` or `max` are provided and the parsed value falls outside the
+ * range, the default is returned instead of the clamped value — this makes
+ * misconfiguration visible (the feature silently runs at the default rather
+ * than at an unintended boundary).
+ */
+export declare function envInt(key: string, options?: {
+    default: number;
+    min?: number;
+    max?: number;
+}, env?: NodeJS.ProcessEnv): number;
+/**
+ * Parse an environment variable as a float with optional range constraints.
+ * Same semantics as {@link envInt} but for fractional values.
+ */
+export declare function envFloat(key: string, options?: {
+    default: number;
+    min?: number;
+    max?: number;
+}, env?: NodeJS.ProcessEnv): number;
+/**
+ * Read an environment variable as a trimmed string.
+ * Returns `undefined` when unset or empty after trimming.
+ */
+export declare function envString(key: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Read an environment variable and validate it against a set of allowed values.
+ * Returns `options.default` when unset or when the value is not in the allow-list.
+ */
+export declare function envEnum<T extends string>(key: string, allowed: readonly T[], options: {
+    default: T;
+}, env?: NodeJS.ProcessEnv): T;
+//# sourceMappingURL=env-typed.d.ts.map

package/dist/utils/glob-match.d.ts

@@ -1,4 +1,24 @@
-export declare function compileGlob(pattern: string): RegExp;
+/**
+ * @param commandSubject - When true, compile for matching a shell command line
+ *   rather than a path: a single `*` additionally stops at the shell
+ *   separators in {@link COMMAND_WILDCARD_STOP}, and `**` is NOT a
+ *   match-everything escape hatch (see below). Defaults to false, so every
+ *   existing caller — file search, grep, replace, gitignore, the indexer —
+ *   keeps its current semantics exactly.
+ */
+export declare function compileGlob(pattern: string, commandSubject?: boolean): RegExp;
 export declare function matchGlob(pattern: string, input: string): boolean;
 export declare function matchAny(patterns: string[], input: string): boolean;
+/**
+ * Match a shell command line against a trust pattern, with `*` and `**`
+ * stopping at shell separators (WS-047).
+ *
+ * A separate entry point rather than a flag on {@link matchGlob} because the
+ * two must never be confused at a call site: this is strictly NARROWER, so it
+ * is correct for deciding what a pattern ALLOWS and wrong for deciding what a
+ * pattern DENIES — narrowing a deny pattern un-blocks things. The caller has to
+ * pick deliberately.
+ */
+export declare function matchCommandGlob(pattern: string, input: string): boolean;
+export declare function matchAnyCommand(patterns: string[], input: string): boolean;
 //# sourceMappingURL=glob-match.d.ts.map

package/dist/utils/heap-watchdog-types.d.ts

@@ -0,0 +1,62 @@
+export interface HeapSample {
+    ts: string;
+    /** Resident set size, bytes. */
+    rss: number;
+    heapUsed: number;
+    heapTotal: number;
+    /** Off-heap (buffers, etc.), bytes. */
+    external: number;
+    /** ArrayBuffer/Buffer backing stores, included in `external`. */
+    arrayBuffers?: number | undefined;
+    /**
+     * RSS not explained by V8's committed heap or external allocations.
+     * This is a diagnostic heuristic, not an accounting identity: code pages,
+     * stacks, allocator fragmentation, Ink/Yoga and native addons live here.
+     */
+    nativeResidual?: number | undefined;
+    /** Selected V8 space usage, bytes. */
+    oldSpaceUsed?: number | undefined;
+    newSpaceUsed?: number | undefined;
+    largeObjectSpaceUsed?: number | undefined;
+    codeSpaceUsed?: number | undefined;
+    /** Native memory tracked by V8's allocator, bytes. */
+    mallocedMemory?: number | undefined;
+    peakMallocedMemory?: number | undefined;
+    nativeContexts?: number | undefined;
+    detachedContexts?: number | undefined;
+    /** Active libuv/Node resources (timers, pipes, sockets, etc.). */
+    activeResources?: number | undefined;
+    /**
+     * Bounded type histogram for active resources, e.g. "PipeWrap=4,Timeout=2".
+     * Carries no handles or payloads, so diagnostics cannot retain live work.
+     */
+    activeResourceTypes?: string | undefined;
+    /** V8 hard heap limit, bytes — the OOM ceiling. */
+    heapLimit: number;
+    /** heapUsed / heapLimit, 0–1. */
+    load: number;
+}
+export type HeapDiagnosticValue = string | number | boolean | null | undefined;
+export type HeapDiagnosticFields = Record<string, HeapDiagnosticValue>;
+export interface HeapWatchdogOptions {
+    /** Sampling cadence. Default 30s. */
+    sampleEveryMs?: number | undefined;
+    /** Diagnostic-file append cadence. Default 60s. */
+    logEveryMs?: number | undefined;
+    /** Diagnostics file. Default ~/.wrongstack/logs/heap.jsonl */
+    logPath?: string | undefined;
+    /** Fraction of the heap limit that triggers a 'warn' callback. Default 0.6. */
+    warnAt?: number | undefined;
+    /** Fraction of the heap limit that triggers a 'critical' callback. Default 0.85. */
+    criticalAt?: number | undefined;
+    /**
+     * Extra structure sizes merged into every diagnostic line — supply cheap
+     * counters (array lengths, approximate char totals). Must not throw.
+     */
+    collectStats?: (() => HeapDiagnosticFields) | undefined;
+    /** Override the JSONL writer, primarily for deterministic tests. */
+    writeDiagnosticLine?: ((logPath: string, line: string) => Promise<void>) | undefined;
+    /** Called on threshold crossings with a human-readable message. */
+    onWarn?: ((level: 'warn' | 'critical', message: string, sample: HeapSample) => void) | undefined;
+}
+//# sourceMappingURL=heap-watchdog-types.d.ts.map

package/dist/utils/heap-watchdog.d.ts

@@ -1,37 +1,5 @@
-export interface HeapSample {
-    ts: string;
-    /** Resident set size, bytes. */
-    rss: number;
-    heapUsed: number;
-    heapTotal: number;
-    /** Off-heap (buffers, etc.), bytes. */
-    external: number;
-    /** V8 hard heap limit, bytes — the OOM ceiling. */
-    heapLimit: number;
-    /** heapUsed / heapLimit, 0–1. */
-    load: number;
-}
-export interface HeapWatchdogOptions {
-    /** Sampling cadence. Default 60s. */
-    sampleEveryMs?: number | undefined;
-    /** Diagnostic-file append cadence. Default 5min. */
-    logEveryMs?: number | undefined;
-    /** Diagnostics file. Default ~/.wrongstack/logs/heap.jsonl */
-    logPath?: string | undefined;
-    /** Fraction of the heap limit that triggers a 'warn' callback. Default 0.6. */
-    warnAt?: number | undefined;
-    /** Fraction of the heap limit that triggers a 'critical' callback. Default 0.85. */
-    criticalAt?: number | undefined;
-    /**
-     * Extra structure sizes merged into every diagnostic line — supply cheap
-     * counters (array lengths, approximate char totals). Must not throw.
-     */
-    collectStats?: (() => Record<string, number>) | undefined;
-    /** Override the JSONL writer, primarily for deterministic tests. */
-    writeDiagnosticLine?: ((logPath: string, line: string) => Promise<void>) | undefined;
-    /** Called on threshold crossings with a human-readable message. */
-    onWarn?: ((level: 'warn' | 'critical', message: string, sample: HeapSample) => void) | undefined;
-}
+import type { HeapSample, HeapWatchdogOptions } from './heap-watchdog-types.js';
+export type { HeapDiagnosticFields, HeapDiagnosticValue, HeapSample, HeapWatchdogOptions, } from './heap-watchdog-types.js';
 export declare function defaultHeapLogPath(): string;
 export declare function takeHeapSample(): HeapSample;
 /**
@@ -40,4 +8,17 @@ export declare function takeHeapSample(): HeapSample;
  * serialized; a failed append never throws into the caller.
  */
 export declare function startHeapWatchdog(opts?: HeapWatchdogOptions): () => Promise<void>;
+/**
+ * Start or join the single process-wide watchdog.
+ *
+ * WrongStack's CLI mounts downstream surfaces (TUI/WebUI) inside the same Node
+ * process. Each surface used to start its own timer and append alternating
+ * partial records for the same PID. Contributors now share one sampler while
+ * still attaching surface-specific counters and warning handlers.
+ *
+ * The first contributor owns cadence/path/writer options. Later contributors
+ * only add `collectStats` and `onWarn`. The sampler stops after the final
+ * contributor unregisters.
+ */
+export declare function startSharedHeapWatchdog(opts?: HeapWatchdogOptions): () => Promise<void>;
 //# sourceMappingURL=heap-watchdog.d.ts.map