@adhdev/daemon-core 0.9.82-rc.44 → 0.9.82-rc.440

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/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/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/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;

package/dist/git/git-commands.d.ts

@@ -23,8 +23,12 @@ export interface GitLogResult extends GitRepoIdentity {
     lastCheckedAt: number;
 }
 export interface GitCheckpointResult extends GitRepoIdentity {
-    commit: string;
+    commit?: string;
     message: string;
+    status?: 'created' | 'skipped';
+    skipped?: boolean;
+    noop?: boolean;
+    reason?: 'nothing_to_commit';
     lastCheckedAt: number;
 }
 export interface GitStashPushResult extends GitRepoIdentity {
@@ -43,15 +47,19 @@ export interface GitCommandServices {
     getStatus?: (params: {
         workspace: string;
         refreshUpstream?: boolean;
+        includeSubmodules?: boolean;
+        submoduleIgnorePaths?: string[];
     }) => Promise<GitRepoStatus> | GitRepoStatus;
     getDiffSummary?: (params: {
         workspace: string;
         staged?: boolean;
+        base?: string;
     }) => Promise<GitDiffSummary> | GitDiffSummary;
     getDiffFile?: (params: {
         workspace: string;
         path: string;
         staged?: boolean;
+        base?: string;
     }) => Promise<GitFileDiff> | GitFileDiff;
     createSnapshot?: (params: {
         workspace: string;
@@ -113,6 +121,8 @@ type GitCommandFailure = {
 type GitCommandSuccess = {
     success: true;
     status: GitRepoStatus;
+    reporterPlatform?: string;
+    reporterArch?: string;
 } | {
     success: true;
     diffSummary: GitDiffSummary;

package/dist/git/git-diff.d.ts

@@ -3,6 +3,12 @@ export interface GitDiffOptions {
     timeoutMs?: number;
     maxFiles?: number;
     maxBytes?: number;
+    /**
+     * When set, diff `<baseRef>...HEAD` (merge-base range — "what this branch
+     * adds on top of base") instead of the working tree. Staged/untracked
+     * sections do not apply in this mode.
+     */
+    baseRef?: string;
 }
 export interface GitFileDiffResult {
     workspace: string;

package/dist/git/git-executor.d.ts

@@ -1,4 +1,15 @@
 import type { GitFailureReason, GitRepoIdentity } from './git-types.js';
+/**
+ * Timeout for status-collection git commands (status/log/submodule/stash/fetch).
+ * The default 5s is fine for porcelain status, but on Windows the `git` subprocess
+ * spawn itself is pathologically slow (measured: `submodule status` ~3.5s, cold
+ * `log -1` ~4.2s) and overlaps with refreshUpstream fetches — a single command
+ * routinely exceeds 5s, which previously collapsed the whole status to all-null and
+ * dropped the node from the mesh graph. Give the collection path a much larger
+ * budget so a slow-but-healthy repo never reads as "not a git repo". Windows gets a
+ * larger budget than POSIX because the spawn cost is OS-specific, not repo-specific.
+ */
+export declare const GIT_STATUS_TIMEOUT_MS: number;
 export interface GitExecutorOptions {
     timeoutMs?: number;
     maxBuffer?: number;

package/dist/git/git-status.d.ts

@@ -1,4 +1,21 @@
 import type { GitRepoStatus } from './git-types.js';
+import { type DaemonBuildInfo } from '../build-info.js';
+import { type ChangeImpactConfig } from './change-impact-config.js';
+/**
+ * TTL for the happy-path result cache (C1). reconcile fires every 4s and mesh_status
+ * is polled; a single getGitRepoStatus on a 1-submodule repo spawns ~13-15 git
+ * processes (+ optional network fetch) which on Windows is ~10-15s. Within this short
+ * window, repeat callers that share the same option shape are served the already
+ * collected status instead of re-shelling. Kept well under the 4s reconcile cadence so
+ * a genuinely fresh probe still happens at least roughly once per reconcile tick.
+ */
+export declare const GIT_STATUS_CACHE_TTL_MS = 1500;
+/** Test seam: clear the last-known-good status cache between cases. */
+export declare function __resetGitStatusCacheForTests(): void;
+/** Alias matching the task's requested name. */
+export declare const __resetGitStatusCache: typeof __resetGitStatusCacheForTests;
+/** Test-only introspection: number of memoized Change Impact evaluations. */
+export declare function __changeImpactEvalCacheSizeForTests(): number;
 export interface GitStatusOptions {
     timeoutMs?: number;
     /** When true, include submodule status in the result. Defaults to true. */
@@ -10,10 +27,50 @@ export interface GitStatusOptions {
      * Callers should opt into this only for convergence-critical surfaces.
      */
     refreshUpstream?: boolean;
+    /**
+     * When true, bypass the C1 TTL result cache: always re-collect a fresh status
+     * (ignoring any cached entry younger than GIT_STATUS_CACHE_TTL_MS). The freshly
+     * collected result still UPDATES the cache so subsequent normal callers benefit.
+     *
+     * Mutating / decision callers (mesh_fast_forward preflight + post-merge re-read,
+     * refine submodule alignment pre/post status) MUST set this — acting on a stale
+     * ahead/behind or submodule sync verdict is the primary correctness hazard of the
+     * cache. Read-only/observe callers (mesh_status, git-monitor, reconcile) leave it
+     * unset and enjoy the dedup.
+     */
+    forceFresh?: boolean;
+    /**
+     * Test/override seam for the daemon build stamp used by the stale-build
+     * detector. Production callers omit this so the real baked-in build commit
+     * (getDaemonBuildInfo) is used.
+     */
+    daemonBuildInfo?: DaemonBuildInfo;
+    /**
+     * Change Impact policy override. When provided, the daemonBuildBehind
+     * classifier uses this declarative config instead of auto-loading the repo's
+     * `.adhdev/change-impact.*` file. When omitted, getGitRepoStatus auto-loads the
+     * repo config (cached); when neither is present the built-in ADHDev default
+     * policy applies, preserving the legacy behavior exactly.
+     *
+     * Pass `null` to force the built-in default policy and skip auto-loading (used
+     * to assert legacy parity in tests).
+     */
+    changeImpactConfig?: ChangeImpactConfig | null;
 }
+/**
+ * C2: minimum interval between actual `git fetch` network calls per workspace. A
+ * refreshUpstream caller within this window does NOT re-fetch; it serves ahead/behind
+ * from the locally-re-read porcelain (which is always fresh every call). So
+ * refreshUpstream becomes "fetch if the local remote-tracking ref is stale" rather than
+ * "always pay a network round trip". Only the upstream ahead/behind can age up to this
+ * throttle; local working-tree status never does.
+ */
+export declare const GIT_FETCH_THROTTLE_MS = 30000;
 export declare function getGitRepoStatus(workspace: string, options?: GitStatusOptions): Promise<GitRepoStatus>;
 interface ParsedPorcelainStatus {
     branch: string | null;
+    /** Full HEAD object id from `# branch.oid`, or null when detached/unborn. */
+    headOid: string | null;
     upstream: string | null;
     ahead: number;
     behind: number;