@adhdev/daemon-core 0.9.82-rc.48 → 0.9.82-rc.481

package/dist/config/mesh-json-config.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Repo-shared declarative mesh config — `.adhdev/mesh.json`
+ *
+ * A repo-committed, machine-independent file carrying ONLY the repo-shared
+ * coordinator-prompt config and operating notes:
+ *
+ *   - coordinator       — systemPromptOverride (local wins, else repo) and
+ *                         systemPromptAppend (repo append + local append BOTH
+ *                         stack, repo first).
+ *   - operatingNotes    — repo-declared baseline notes merged with the runtime
+ *                         ledger notes; on duplicate text the ledger note wins.
+ *   - limits            — advisory-only (`maxNoteChars`, `maxNotes`,
+ *                         `coordinator.maxPromptChars`); recorded, never enforced in v1.
+ *
+ * POLICY IS NOT HERE. RepoMeshPolicy (the 15 scheduling/approval fields) is
+ * MACHINE-LOCAL only — it lives in meshes.json and is never sourced from, merged
+ * with, or overlaid by a repo file. There is no `policy` zone and no
+ * `policy.scheduling` overlay in mesh.json; the scheduler reads the stored
+ * machine-local policy directly. The repo file shapes the coordinator prompt and
+ * operating notes, nothing else.
+ *
+ * The coordinator/operatingNotes merge is **in-memory only**: the on-disk
+ * machine-local `meshes.json` is never mutated by this module.
+ *
+ * FILE SEPARATION: refine / worktree-bootstrap / change-impact configs live in
+ * their OWN `.adhdev/*` files with their own loaders — they are NOT inlined into
+ * mesh.json. `loadRepoSettings` (config/repo-settings.ts) assembles all of them
+ * into one object for consumers.
+ *
+ * SECURITY: declarative only. JSON/YAML is parsed; arbitrary JS (.js) is NOT
+ * supported, so loading a config can never execute code.
+ */
+import type { RepoMeshCoordinatorConfig, LocalMeshEntry } from '../repo-mesh-types.js';
+import type { CoordinatorOperatingNote } from '../mesh/coordinator-prompt.js';
+export interface RepoMeshDeclarativeCoordinatorConfig {
+    /** Full mesh-level system prompt override. Same semantics as
+     *  RepoMeshCoordinatorConfig.systemPromptOverride; LOCAL-WINS. */
+    systemPromptOverride?: string;
+    /** Mesh-level append stacked after the base prompt. Both the repo append
+     *  and the machine-local append apply; the repo append comes first. */
+    systemPromptAppend?: string;
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxPromptChars?: number;
+}
+export interface RepoMeshDeclarativeLimits {
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxNoteChars?: number;
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxNotes?: number;
+}
+/**
+ * Parsed + normalized `.adhdev/mesh.json` shape. Every field is optional except
+ * version so a repo can declare only the zone(s) it cares about. Policy is NOT a
+ * zone here — it is machine-local (meshes.json) only.
+ */
+export interface RepoMeshDeclarativeConfig {
+    version: 1;
+    coordinator?: RepoMeshDeclarativeCoordinatorConfig;
+    operatingNotes?: CoordinatorOperatingNote[];
+    limits?: RepoMeshDeclarativeLimits;
+}
+export interface RepoMeshJsonConfigLoadResult {
+    config?: RepoMeshDeclarativeConfig;
+    /** Relative location matched, or 'unavailable'/'invalid' marker. */
+    source: string;
+    sourceType: 'repo_file' | 'unavailable' | 'invalid';
+    /** Absolute path of the matched file, when one was read. */
+    path?: string;
+    error?: string;
+}
+export declare const MESH_JSON_CONFIG_LOCATIONS: string[];
+export declare const MESH_JSON_CONFIG_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "ADHDev Repo Mesh Declarative Config";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version"];
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly coordinator: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly systemPromptOverride: {
+                    readonly type: "string";
+                };
+                readonly systemPromptAppend: {
+                    readonly type: "string";
+                };
+                readonly maxPromptChars: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+        readonly operatingNotes: {
+            readonly type: "array";
+            readonly maxItems: 200;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["text"];
+                readonly properties: {
+                    readonly text: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly category: {
+                        readonly enum: readonly ["provider_quirk", "pattern_to_avoid", "recovery_lesson"];
+                    };
+                    readonly createdAt: {
+                        readonly type: "string";
+                    };
+                    readonly sourceCoordinator: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly limits: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly maxNoteChars: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+                readonly maxNotes: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+    };
+};
+/**
+ * Validate + normalize a parsed `.adhdev/mesh.json` object into a typed
+ * RepoMeshDeclarativeConfig. Returns the config plus any non-fatal warnings;
+ * `valid` is false only when the document is structurally unusable (not an
+ * object / wrong version). Unknown top-level keys are tolerated (dropped) so a
+ * newer repo file authored against a future schema still loads its known zones.
+ */
+export declare function normalizeRepoMeshDeclarativeConfig(parsed: unknown): {
+    valid: boolean;
+    config?: RepoMeshDeclarativeConfig;
+    errors: string[];
+};
+/**
+ * Load the repo-shared declarative mesh config for a coordinator workspace.
+ *
+ * Resolution: the coordinator node workspace is checked first; if it carries no
+ * `.adhdev/mesh.json`, the calling process cwd is tried as a fallback (per the
+ * design: "workspace path = coordinator node workspace's .adhdev/mesh.json,
+ * else calling cwd"). The first existing file across both bases (and the
+ * json/yaml/yml variants) wins.
+ *
+ * Read/parse errors never throw — they resolve to a sourceType:'invalid'
+ * result so a broken repo file degrades to "no repo base" instead of blocking
+ * coordinator launch.
+ */
+export declare function loadRepoMeshJsonConfig(workspace?: string): RepoMeshJsonConfigLoadResult;
+/**
+ * Effective coordinator config. systemPromptOverride: local wins, else repo.
+ * systemPromptAppend: repo append + local append BOTH stack (repo first). Other
+ * coordinator fields (providerType, preferredNodeId, …) are carried from the
+ * machine-local config unchanged.
+ */
+export declare function mergeEffectiveCoordinatorConfig(repoCoord: RepoMeshDeclarativeCoordinatorConfig | undefined, localCoord: RepoMeshCoordinatorConfig | undefined): RepoMeshCoordinatorConfig;
+/**
+ * Effective operating notes = repo-declared baseline ⊕ runtime ledger notes.
+ * Dedup by trimmed text with the LEDGER note winning (repo duplicates dropped),
+ * so a runtime note's freshest wording/category survives. Order: repo baseline
+ * first, then ledger notes. Returns undefined when nothing usable remains so the
+ * prompt's "## Operating Notes" section is omitted exactly as before.
+ */
+export declare function mergeEffectiveOperatingNotes(repoNotes: CoordinatorOperatingNote[] | undefined, ledgerNotes: CoordinatorOperatingNote[] | undefined): CoordinatorOperatingNote[] | undefined;
+/**
+ * Produce an in-memory effective mesh by layering the repo declarative config
+ * UNDER the machine-local mesh entry — coordinator zone ONLY. Policy is
+ * machine-local and is left exactly as the stored mesh carries it (never sourced
+ * from the repo file). Returns a new object; the input mesh and on-disk
+ * meshes.json are never mutated. operatingNotes are merged separately at launch
+ * (they ride the prompt context, not the mesh).
+ */
+export declare function applyRepoMeshConfig<T extends Pick<LocalMeshEntry, 'coordinator'>>(mesh: T, repoConfig: RepoMeshDeclarativeConfig | null | undefined): T;
+/**
+ * Build a `.adhdev/mesh.json` DRAFT from a machine-local mesh entry. This is a
+ * scaffold for the operator to review and commit — NOT an automatic migration.
+ * It captures the coordinator prompt override/append so a repo can adopt the
+ * current machine's prompt customization as the shared base. Policy is NOT
+ * exported — it is machine-local only and has no place in mesh.json. Operating
+ * notes are intentionally NOT exported either: those are runtime ledger lessons,
+ * and a repo should declare baseline notes deliberately.
+ */
+export declare function buildMeshJsonConfigScaffold(mesh: Pick<LocalMeshEntry, 'coordinator'>): RepoMeshDeclarativeConfig;
+/** Serialize a scaffold to the canonical 2-space JSON draft text. */
+export declare function serializeMeshJsonConfigScaffold(config: RepoMeshDeclarativeConfig): string;

package/dist/config/registry-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Registry / provider-distribution URL resolver.
+ *
+ * Single source of truth for the ADHDev provider *registry* base URL and the
+ * provider *tarball* (GitHub) URL. Self-hosters can repoint both away from the
+ * vendor defaults so the daemon never phones home to `api.adhf.dev` /
+ * `github.com/vilmire/adhdev-providers`.
+ *
+ * Resolution priority (highest first):
+ *   1. Explicit config field    — `config.registryUrl` / `config.providerTarballUrl`
+ *   2. Environment variable      — `ADHDEV_REGISTRY_URL` / `ADHDEV_PROVIDER_TARBALL_URL`
+ *   3. Vendor default            — existing URLs (unchanged for default users)
+ *
+ * Default users get byte-identical behavior: the vendor defaults equal the
+ * literals these functions replaced.
+ */
+/** Vendor default registry base URL (no trailing slash). */
+export declare const DEFAULT_REGISTRY_BASE_URL = "https://api.adhf.dev/api/v1/registry";
+/** Vendor default provider tarball URL (GitHub main branch archive). */
+export declare const DEFAULT_PROVIDER_TARBALL_URL = "https://github.com/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz";
+/** Env var that overrides the registry base URL. */
+export declare const REGISTRY_URL_ENV_VAR = "ADHDEV_REGISTRY_URL";
+/** Env var that overrides the provider tarball URL. */
+export declare const PROVIDER_TARBALL_URL_ENV_VAR = "ADHDEV_PROVIDER_TARBALL_URL";
+/**
+ * Resolve the provider registry base URL.
+ *
+ * @param configuredUrl explicit config value (config.registryUrl); highest priority.
+ * @param env process env source (defaults to process.env; injectable for tests).
+ * @returns the resolved base URL with any trailing slash stripped, so callers
+ *   can safely append `/providers`, `/providers/<type>`, etc.
+ */
+export declare function resolveRegistryBaseUrl(configuredUrl?: string | null, env?: NodeJS.ProcessEnv): string;
+/**
+ * Resolve the provider tarball (archive) URL.
+ *
+ * @param configuredUrl explicit config value (config.providerTarballUrl); highest priority.
+ * @param env process env source (defaults to process.env; injectable for tests).
+ */
+export declare function resolveProviderTarballUrl(configuredUrl?: string | null, env?: NodeJS.ProcessEnv): string;
+/** Parsed tarball request target for callers that issue raw hostname/path requests. */
+export interface TarballRequestTarget {
+    /** Full resolved tarball URL. */
+    url: string;
+    /** Hostname component (e.g. `github.com`). */
+    hostname: string;
+    /** Path component including any query string (e.g. `/vilmire/...tar.gz`). */
+    path: string;
+}
+/**
+ * Resolve the provider tarball URL and split it into `{ url, hostname, path }`
+ * for callers that build raw `https.request` options (e.g. HEAD ETag probes).
+ */
+export declare function resolveProviderTarballTarget(configuredUrl?: string | null, env?: NodeJS.ProcessEnv): TarballRequestTarget;

package/dist/config/repo-settings.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Repo Settings — one unified loader over the repo-committed `.adhdev/*` config
+ * files (the "single source" assembly point).
+ *
+ * DESIGN (option B — file separation preserved): the repo keeps its declarative
+ * config in SEPARATE files, each with its own dedicated loader:
+ *
+ *   .adhdev/mesh.json               → loadRepoMeshJsonConfig  (coordinator + operatingNotes)
+ *   .adhdev/refine.json             → loadMeshRefineConfig     (Refinery validation)
+ *   .adhdev/worktree_bootstrap.json → loadMeshWorktreeBootstrapConfig
+ *   .adhdev/change-impact.json      → loadChangeImpactConfig
+ *
+ * Nothing is inlined into mesh.json. `loadRepoSettings` simply CALLS each
+ * dedicated loader and assembles the results into one `RepoSettings` object so a
+ * consumer can read every repo-shared setting through a single call instead of
+ * threading four loaders. The per-file loaders remain the source of truth (and
+ * stay independently usable); this is a convenience aggregator, not a new schema.
+ *
+ * IMPORTANT — policy is NOT here. RepoMeshPolicy (the 15 scheduling/approval
+ * fields) is MACHINE-LOCAL only: it lives in meshes.json and is never sourced
+ * from or merged with a repo file. mesh.json carries only coordinator prompt
+ * config + operating notes (+ advisory limits).
+ *
+ * The refine/worktree-bootstrap loaders also honor a machine-local INLINE seam
+ * (mesh.refineConfig / mesh.policy.worktreeBootstrap, etc.) — that seam is for
+ * machine-local config and is unchanged here; mesh.json gains no such zone.
+ */
+import { type RepoMeshDeclarativeCoordinatorConfig, type RepoMeshDeclarativeLimits, type RepoMeshJsonConfigLoadResult } from './mesh-json-config.js';
+import { type MeshRefineConfigLoadResult } from '../mesh/refine-config.js';
+import { type WorktreeBootstrapConfigLoadResult } from '../mesh/worktree-bootstrap-config.js';
+import { type ChangeImpactConfigLoadResult } from '../git/change-impact-config.js';
+import type { CoordinatorOperatingNote } from '../mesh/coordinator-prompt.js';
+export interface LoadRepoSettingsOptions {
+    /** Workspace path whose `.adhdev/*` files are resolved (mesh.json / refine / bootstrap). */
+    workspace: string;
+    /**
+     * Machine-local mesh entry, consulted ONLY for the INLINE seam of the
+     * refine / worktree-bootstrap loaders (mesh.refineConfig etc.). Optional —
+     * omit it and only the repo files are considered. NEVER used to source policy.
+     */
+    mesh?: any;
+    /**
+     * Repo root for change-impact resolution. Defaults to `workspace` when omitted
+     * (change-impact compares the daemon build commit against the workspace HEAD).
+     */
+    repoRoot?: string;
+}
+/**
+ * The assembled repo-shared settings. Each sub-config carries its own load
+ * result (source / sourceType / error) so a consumer can tell "absent" from
+ * "invalid" per file. `coordinator` / `operatingNotes` / `limits` are lifted out
+ * of the mesh.json load result for convenience; `meshJson` keeps the full result
+ * (e.g. for the `sourceType === 'invalid'` warning on coordinator launch).
+ */
+export interface RepoSettings {
+    /** Repo-shared coordinator prompt config (override/append) from `.adhdev/mesh.json`. */
+    coordinator?: RepoMeshDeclarativeCoordinatorConfig;
+    /** Repo-declared baseline operating notes from `.adhdev/mesh.json`. */
+    operatingNotes?: CoordinatorOperatingNote[];
+    /** Advisory-only limits from `.adhdev/mesh.json` (recorded, not enforced in v1). */
+    limits?: RepoMeshDeclarativeLimits;
+    /** Full `.adhdev/mesh.json` declarative load result (coordinator/operatingNotes source). */
+    meshJson: RepoMeshJsonConfigLoadResult;
+    /** `.adhdev/refine.json` Refinery validation config load result. */
+    refine: MeshRefineConfigLoadResult;
+    /** `.adhdev/worktree_bootstrap.json` bootstrap config load result. */
+    worktreeBootstrap: WorktreeBootstrapConfigLoadResult;
+    /** `.adhdev/change-impact.json` change-impact config load result. */
+    changeImpact: ChangeImpactConfigLoadResult;
+}
+/**
+ * Load every repo-committed `.adhdev/*` setting for a workspace and assemble them
+ * into one object. Each dedicated loader degrades to an `unavailable`/`invalid`
+ * load result rather than throwing, so this never throws on a missing or broken
+ * file — a consumer inspects the per-sub-config `sourceType`.
+ */
+export declare function loadRepoSettings(opts: LoadRepoSettingsOptions): RepoSettings;

package/dist/config/state-store.d.ts

@@ -21,6 +21,17 @@ export interface DaemonState {
     sessionNotificationDismissals: Record<string, string>;
     /** Current notification unread override ids keyed by stable session target */
     sessionNotificationUnreadOverrides: Record<string, string>;
+    /**
+     * Resolved provider-native conversation id for a live session, keyed by the
+     * ADHDev/mesh session id. Persisted so it survives a daemon restart: a
+     * provider whose on-disk store is keyed by an internally-generated id it
+     * never exposes on the CLI (antigravity — no --session-id) can then exact-bind
+     * its conversation .db after restart instead of re-running the mtime/recency
+     * heuristic, which drops the store once idle and collapses read_chat to the
+     * PTY parse (user echo only, assistant tail lost). Mirrors the in-memory read
+     * pin (chat-commands-read lastBoundProviderSessionIdByMeshSession).
+     */
+    sessionProviderSessionPins: Record<string, string>;
 }
 /**
  * Load runtime state from disk
@@ -34,3 +45,22 @@ export declare function saveState(state: DaemonState): void;
  * Reset runtime state
  */
 export declare function resetState(): void;
+/**
+ * Load the full persisted session→provider-conversation pin map (sessionId →
+ * provider-native conversation id). Survives daemon restart. Empty object when
+ * none recorded or the state file is unreadable.
+ */
+export declare function loadPersistedProviderSessionPins(): Record<string, string>;
+/**
+ * Persist one session→provider-conversation pin. Load-mutate-save against the
+ * on-disk state so it survives a daemon restart; a no-op when the value already
+ * matches (avoids rewriting state.json on every read). Never clears a pin with an
+ * empty value.
+ */
+export declare function recordPersistedProviderSessionPin(sessionId: string, providerSessionId: string): void;
+/**
+ * Test-only: drop all persisted session→provider-conversation pins from disk.
+ * Used by tests that assert a clean "no pin" state so a sibling test's write to
+ * the shared per-process ADHDEV_CONFIG_DIR does not leak in.
+ */
+export declare function clearPersistedProviderSessionPins(): void;

package/dist/daemon/dev-server.d.ts

@@ -103,8 +103,6 @@ export declare class DevServer implements DevServerContext {
     getLatestScriptVersionDir(scriptsDir: string): string | null;
     private resolveAutoImplWritableProviderDir;
     private handleAutoImplement;
-    private buildAutoImplPrompt;
-    private buildCliAutoImplPrompt;
     private handleAutoImplSSE;
     private handleAutoImplCancel;
     sendAutoImplSSE(msg: {

package/dist/detection/cli-detector.d.ts

@@ -29,3 +29,20 @@ export declare function detectCLIs(providerLoader?: ProviderLoader, options?: {
 export declare function detectCLI(cliId: string, providerLoader?: ProviderLoader, options?: {
     includeVersion?: boolean;
 }): Promise<CLIInfo | null>;
+/**
+ * Fold a detected CLIInfo[] into the `{ providerId: version }` map surfaced as a
+ * node's providerVersions (see RepoMeshNodeCapabilities.providerVersions). Only
+ * installed providers that produced a parseable version string are included, so a
+ * missing entry means "not installed or version unknown" — never a fabricated value.
+ * Pure/deterministic: the same detection input always yields the same map, which is
+ * what the git_status envelope carries and the mesh_status skew check compares.
+ */
+export declare function buildProviderVersions(detected: CLIInfo[]): Record<string, string>;
+/**
+ * Return the current cached provider-versions map for this daemon, triggering a
+ * lazy background refresh when the snapshot is stale/cold. Never blocks: returns
+ * whatever is currently cached (an empty object before the first refresh lands).
+ * This is the source the git_status envelope reads to self-report a node's
+ * provider versions to the mesh coordinator.
+ */
+export declare function getCachedProviderVersions(providerLoader?: ProviderLoader): Record<string, string>;

package/dist/detection/ide-detector.d.ts

@@ -32,4 +32,17 @@ export interface IDEDefinition {
     };
 }
 export declare function registerIDEDefinition(def: IDEDefinition): void;
+/**
+ * Resolve an IDE version on demand (NOT at boot).
+ *
+ * Order of preference, all spawn-free where possible:
+ *  1. win32: read the bundled product.json/package.json next to the exe.
+ *  2. Otherwise spawn `<cli> --version` — but ONLY when the binary is not a
+ *     known GUI executable (the #4 guard), so we never boot an IDE window.
+ *
+ * `win32ProcessNames` is provider.json `processNames.win32` (type → exe names),
+ * used to recognise GUI executables. Callers that have a ProviderLoader can
+ * pass `providerLoader.getWinProcessNames()`.
+ */
+export declare function getIdeVersion(cliCommand: string, win32ProcessNames?: Record<string, string[]>): Promise<string | null>;
 export declare function detectIDEs(providerLoader?: ProviderLoader): Promise<IDEInfo[]>;

package/dist/detection/win32-ide-version.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ADHDev — Windows IDE version detection (execution-free)
+ *
+ * On Windows the resolved "CLI" for a VS Code fork (Cursor, Antigravity, …)
+ * frequently resolves to the GUI Electron executable itself, because the
+ * case-insensitive filesystem matches `...\cursor\cursor.exe` against the
+ * real `Cursor.exe`. Running `<that exe> --version` boots the GUI instead of
+ * printing a version (Electron ignores the unknown flag and opens a window).
+ *
+ * To learn the version WITHOUT spawning anything, we read the bundled
+ * `product.json` / `package.json` that ship next to the executable. VS Code
+ * forks embed their version there. This is a pure filesystem read.
+ *
+ * It also exposes a guard so any remaining `--version` exec path can refuse to
+ * spawn a binary that is a known GUI executable for an IDE provider.
+ */
+/**
+ * Read an IDE version from disk (no process spawn).
+ *
+ * @param exePath Absolute path to the GUI executable (or any path inside the
+ *   IDE install dir — we read the manifest relative to its directory).
+ * @returns The version string, or null if it could not be determined.
+ */
+export declare function readWin32IdeVersionFromDisk(exePath: string): string | null;
+/**
+ * True when `binPath` resolves to a known GUI executable for some IDE.
+ *
+ * Used as a safety net: any code path about to run `<bin> --version` must skip
+ * the spawn when the binary is actually the GUI Electron exe, since that would
+ * launch the IDE window. Comparison is case-insensitive on the basename
+ * (Windows filesystem semantics) against every provider's `processNames.win32`.
+ *
+ * @param binPath Resolved binary path that would be exec'd.
+ * @param win32ProcessNames Map of provider type → list of GUI exe names
+ *   (from provider.json `processNames.win32`, e.g. `["Cursor.exe"]`).
+ */
+export declare function isKnownWin32GuiExe(binPath: string | null | undefined, win32ProcessNames: Record<string, string[]>): boolean;

package/dist/git/change-impact-config.d.ts

@@ -0,0 +1,159 @@
+/**
+ * "Change Impact" — config-driven classification of which git changes between the
+ * live daemon's build commit and the workspace HEAD actually require a daemon
+ * rebuild/restart (vs. a web-only redeploy, vs. nothing).
+ *
+ * The daemon-core git surface only knows the FACTS (which files / packages changed
+ * between buildCommit..HEAD). The POLICY — which packages are daemon-runtime, which
+ * are web-only, which root files are non-runtime, and what command to recommend —
+ * is declarative config injected from outside. This keeps git-status.ts repo-agnostic
+ * while preserving ADHDev's exact built-in behavior when no config is present.
+ *
+ * SECURITY: config is declarative only. JSON/YAML are parsed; arbitrary JS config
+ * (.js) is intentionally NOT supported, so loading a config can never execute code.
+ */
+/** A change-impact classification bucket. */
+export type ChangeImpactKind = 'daemon' | 'web' | 'none';
+/**
+ * Recommended action for a given impact classification. `recommendedAction` is the
+ * stable classification key (always one of daemon|web|none, NOT config-overridable);
+ * config customizes only the human-facing `recommendedCommand` recipe.
+ */
+export interface ChangeImpactTarget {
+    /** Human-facing command/recipe to act on the impact (e.g. deploy + restart). */
+    recommendedCommand: string;
+}
+export interface ChangeImpactConfig {
+    /**
+     * Package names (the `<name>` in `packages/<name>/`) whose change means the
+     * daemon runtime is stale and must be rebuilt/redeployed + restarted. When
+     * provided, this REPLACES the built-in daemon-runtime set.
+     */
+    daemonRuntimePackages?: string[];
+    /**
+     * Package names that are web-only — a change to one does not require a daemon
+     * restart, only a web redeploy. When provided, this REPLACES the built-in
+     * web-only set.
+     */
+    webOnlyPackages?: string[];
+    /**
+     * Glob patterns for root-level (non-package) files that demonstrably cannot
+     * change what the daemon runtime executes (markers, docs, license text). These
+     * are added on top of the built-in non-runtime root-file detection.
+     */
+    nonRuntimeRootFilePatterns?: string[];
+    /** Recommended action/command per impact classification. Missing keys fall back to built-in defaults. */
+    impactTargets?: Partial<Record<ChangeImpactKind, ChangeImpactTarget>>;
+}
+export interface ChangeImpactConfigLoadResult {
+    config?: ChangeImpactConfig;
+    source: string;
+    sourceType: 'repo_file' | 'unavailable' | 'invalid';
+    path?: string;
+    error?: string;
+    /**
+     * Stable identity of the config SOURCE, used as part of a cache key so a config
+     * edit invalidates any cached impact evaluation. Combines the resolved path and
+     * its mtime (or the path for the unavailable/invalid case).
+     */
+    sourceKey: string;
+}
+export declare const CHANGE_IMPACT_CONFIG_LOCATIONS: string[];
+export declare const CHANGE_IMPACT_CONFIG_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "ADHDev Change Impact Config";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly daemonRuntimePackages: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly webOnlyPackages: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly nonRuntimeRootFilePatterns: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly impactTargets: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly daemon: {
+                    readonly $ref: "#/$defs/target";
+                };
+                readonly web: {
+                    readonly $ref: "#/$defs/target";
+                };
+                readonly none: {
+                    readonly $ref: "#/$defs/target";
+                };
+            };
+        };
+    };
+    readonly $defs: {
+        readonly target: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["recommendedCommand"];
+            readonly properties: {
+                readonly recommendedCommand: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+    };
+};
+export declare function validateChangeImpactConfig(raw: unknown, source?: string): {
+    valid: boolean;
+    errors: string[];
+    config?: ChangeImpactConfig;
+};
+/**
+ * Locate and load the Change Impact config for a repo root. Declarative only —
+ * never executes config. Returns a sourceKey suitable for cache invalidation:
+ * config path + mtime, or the sentinel for the missing/invalid case.
+ */
+export declare function loadChangeImpactConfig(repoRoot: string): ChangeImpactConfigLoadResult;
+/**
+ * Translate a config glob pattern into a RegExp matched against a forward-slash
+ * file path. Supports `**` (any path segments), `*` (any chars except `/`), and
+ * `?` (single non-slash char). No brace/character-class expansion — declarative,
+ * minimal, predictable. All other characters are matched literally.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+export interface ChangeImpactConfigSuggestion {
+    /** A non-executable, declarative config draft a human can save verbatim. */
+    suggestedConfig: ChangeImpactConfig;
+    /** Per-field human-facing rationale for the proposed classification. */
+    notes: string[];
+    /** Package directories discovered under `packages/` (and `oss/packages/`). */
+    discoveredPackages: {
+        daemon: string[];
+        web: string[];
+        unclassified: string[];
+    };
+}
+/**
+ * Inspect a repo's package layout and propose a reasonable, declarative Change
+ * Impact config draft. This is heuristic scaffold ONLY — it never executes
+ * anything and the draft must be reviewed/saved by a human before it takes
+ * effect. The heuristic mirrors ADHDev's own conventions:
+ *   - `web-*` / `*-web` packages → web-only (web redeploy, no daemon restart)
+ *   - everything else under packages/ → daemon-runtime (rebuild + restart)
+ *   - docs/license/marker root files → non-runtime
+ * Callers are expected to prune the draft to their actual runtime topology.
+ */
+export declare function suggestChangeImpactConfig(repoRoot: string): ChangeImpactConfigSuggestion;