@adhdev/daemon-core 0.9.82-rc.47 → 0.9.82-rc.471

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;
@@ -104,6 +112,17 @@ export interface GitCommandServices {
         branch?: string;
         setUpstream?: boolean;
     }) => Promise<GitPushResult>;
+    /**
+     * Best-effort, non-blocking source of this daemon's detected provider CLI/ACP
+     * versions (keyed by provider id) + its build version, folded onto the git_status
+     * envelope so a mesh coordinator can self-heal each node's providerVersions the
+     * same way it does platform/arch. Wired at daemon boot from the cached CLI
+     * detection snapshot; omitted (⇒ versions not reported) when unavailable.
+     */
+    getReporterProviderVersions?: () => {
+        providerVersions?: Record<string, string>;
+        daemonBuildVersion?: string;
+    };
 }
 type GitCommandFailure = {
     success: false;
@@ -113,6 +132,11 @@ type GitCommandFailure = {
 type GitCommandSuccess = {
     success: true;
     status: GitRepoStatus;
+    reporterPlatform?: string;
+    reporterArch?: string;
+    reporterMachineNickname?: string;
+    reporterProviderVersions?: Record<string, string>;
+    reporterDaemonBuildVersion?: string;
 } | {
     success: true;
     diffSummary: GitDiffSummary;
@@ -149,7 +173,7 @@ type GitCommandSuccess = {
     push: GitPushResult;
 };
 export type GitCommandResult = GitCommandSuccess | GitCommandFailure;
-export declare function createDefaultGitCommandServices(): GitCommandServices;
+export declare function createDefaultGitCommandServices(overrides?: Pick<GitCommandServices, 'getReporterProviderVersions'>): GitCommandServices;
 export declare function isGitCommandName(command: string): command is GitCommandName;
 export declare function handleGitCommand(command: GitCommandName, args: any, services?: GitCommandServices): Promise<GitCommandResult>;
 export declare function handleGitCommand(command: string, args: any, services?: GitCommandServices): Promise<GitCommandResult>;

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;

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

@@ -5,56 +5,8 @@
  * transports, and web-core. Git state is daemon-owned product truth; do not
  * infer these values from agent transcripts in frontend code.
  */
-export type GitFailureReason = 'not_git_repo' | 'git_not_installed' | 'timeout' | 'path_outside_repo' | 'dirty_index_required' | 'conflict' | 'invalid_args' | 'nothing_to_commit' | 'git_command_failed';
-export interface GitRepoIdentity {
-    workspace: string;
-    repoRoot: string | null;
-    isGitRepo: boolean;
-}
-export interface GitSubmoduleStatus {
-    /** Submodule path relative to repo root */
-    path: string;
-    /** Current commit SHA the submodule is at */
-    commit: string;
-    /** Path to the submodule repo (absolute) */
-    repoPath: string;
-    /** Whether the submodule has uncommitted changes */
-    dirty: boolean;
-    /** Whether the submodule commit differs from what the parent repo expects */
-    outOfSync: boolean;
-    /** Last checked timestamp */
-    lastCheckedAt: number;
-    /** Error message if submodule status could not be read */
-    error?: string;
-}
-export type GitUpstreamFreshness = 'fresh' | 'unchecked' | 'stale' | 'no_upstream' | 'unavailable';
-export interface GitRepoStatus extends GitRepoIdentity {
-    branch: string | null;
-    headCommit: string | null;
-    headMessage: string | null;
-    upstream: string | null;
-    /** Whether ahead/behind was verified against a freshly fetched upstream ref. */
-    upstreamStatus: GitUpstreamFreshness;
-    /** Timestamp for the fetch that refreshed upstream refs when upstreamStatus === 'fresh'. */
-    upstreamFetchedAt?: number;
-    /** Error from the last refresh attempt when upstreamStatus === 'stale'. */
-    upstreamFetchError?: string;
-    ahead: number;
-    behind: number;
-    staged: number;
-    modified: number;
-    untracked: number;
-    deleted: number;
-    renamed: number;
-    hasConflicts: boolean;
-    conflictFiles: string[];
-    stashCount: number;
-    lastCheckedAt: number;
-    /** Submodule statuses when auto-discover is enabled */
-    submodules?: GitSubmoduleStatus[];
-    error?: string;
-    reason?: GitFailureReason;
-}
+export type { GitFailureReason, GitRepoIdentity, GitSubmoduleStatus, GitUpstreamFreshness, GitRepoStatus, DaemonBuildBehind, } from '@adhdev/mesh-shared';
+import type { GitRepoIdentity, GitRepoStatus, GitFailureReason, GitUpstreamFreshness } from '@adhdev/mesh-shared';
 export type GitFileChangeStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'untracked' | 'conflict';
 export interface GitFileChange {
     path: string;

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

@@ -19,11 +19,54 @@ export interface WorktreeCreateOptions {
     meshName: string;
     /** Override the auto-resolved target directory */
     targetDir?: string;
+    /**
+     * Remote to fetch+compare the base branch against before branching.
+     * Default: 'origin'.
+     */
+    remote?: string;
+    /**
+     * When true (default) and `baseBranch` is given, fetch the base branch from
+     * `remote` and, if the local base branch is strictly behind the remote
+     * (no divergence), branch the worktree from the remote-tracking ref instead
+     * of the stale local ref. The decision is always surfaced via `baseSync`.
+     * Set false to preserve the legacy "branch from local ref, never fetch"
+     * behavior.
+     */
+    syncBaseFromRemote?: boolean;
+}
+/**
+ * How the worktree's start point was resolved relative to the remote base.
+ * Surfaced so the coordinator can detect a stale base node before dispatching
+ * work onto a worktree built on a behind/diverged base.
+ */
+export interface WorktreeBaseSync {
+    /** The base branch name requested (e.g. 'main'). */
+    branch: string;
+    /** The remote compared against (e.g. 'origin'). */
+    remote: string;
+    /** The actual ref/commit-ish used as the worktree branch start point. */
+    startRef: string;
+    /** Whether `git fetch <remote> <branch>` succeeded. */
+    fetched: boolean;
+    /** Local base-branch SHA before clone, if the local ref exists. */
+    localSha?: string;
+    /** Remote-tracking base-branch SHA after fetch, if it exists. */
+    remoteSha?: string;
+    /** Commits the local base ref is behind the remote (0 when up-to-date/ahead). */
+    behindBy: number;
+    /** Commits the local base ref is ahead of the remote. */
+    aheadBy: number;
+    /** What was done with the base ref. */
+    action: 'up_to_date' | 'local_behind_used_remote' | 'local_ahead_used_local' | 'diverged_used_local' | 'no_remote_ref_used_local' | 'no_local_ref_used_remote';
+    /** Human-readable warning when the base was stale/diverged. */
+    warning?: string;
 }
 export interface WorktreeCreateResult {
     success: true;
     worktreePath: string;
     branch: string;
+    /** Present when `baseBranch` was given and base sync resolution ran. */
+    baseSync?: WorktreeBaseSync;
 }
 export interface WorktreeEntry {
     path: string;
@@ -56,7 +99,12 @@ export declare function resolveWorktreePath(repoRoot: string, meshName: string,
 /**
  * Create a new git worktree with a fresh branch.
  *
- * Runs: git worktree add <targetDir> -b <branch> [baseBranch]
+ * Runs: git worktree add <targetDir> -b <branch> [startRef]
+ *
+ * When `baseBranch` is given and `syncBaseFromRemote` is not disabled, the
+ * start point is resolved against the remote first (see
+ * resolveWorktreeBaseStartPoint) so a stale local base does not produce a stale
+ * worktree. The resolution is returned as `baseSync`.
  */
 export declare function createWorktree(opts: WorktreeCreateOptions): Promise<WorktreeCreateResult>;
 /**
@@ -75,3 +123,25 @@ export declare function listWorktrees(repoRoot: string): Promise<WorktreeEntry[]
  * Parse `git worktree list --porcelain` output into structured entries.
  */
 export declare function parseWorktreeListOutput(output: string): WorktreeEntry[];
+export interface BranchRefDeleteResult {
+    /** True if the branch ref no longer exists after this call. */
+    deleted: boolean;
+    /** Why it was (not) deleted, for surfacing in the cleanup result. */
+    reason: string;
+    /** True when a forced delete (`-D`) was needed (e.g. squash/patch-equivalent merge). */
+    forced?: boolean;
+}
+/**
+ * Delete a local branch ref after its worktree was removed.
+ *
+ * SAFETY: this is only meant to be called once the caller has independently
+ * verified that the branch is fully merged / its content is contained in the
+ * default ref (no work loss). It first tries the safe `git branch -d`, which
+ * refuses to delete a branch git itself does not consider merged. If
+ * `safeDeleteOnly` is false (the caller proved containment by patch-equivalence,
+ * which `-d` cannot see), it falls back to `git branch -D`. When the branch is
+ * already gone, this reports `deleted: true` idempotently.
+ */
+export declare function deleteBranchRef(repoRoot: string, branch: string, opts?: {
+    safeDeleteOnly?: boolean;
+}): Promise<BranchRefDeleteResult>;

package/dist/git/index.d.ts

@@ -3,6 +3,8 @@ export { GitCommandError, isPathInside, normalizeGitOutput, resolveGitRepository
 export type { GitCommandResult as GitExecutorCommandResult, GitExecutorOptions, RunGitOptions } from './git-executor.js';
 export { getGitRepoStatus, parsePorcelainV2Status } from './git-status.js';
 export type { GitStatusOptions } from './git-status.js';
+export { CHANGE_IMPACT_CONFIG_LOCATIONS, CHANGE_IMPACT_CONFIG_SCHEMA, globToRegExp, loadChangeImpactConfig, suggestChangeImpactConfig, validateChangeImpactConfig, } from './change-impact-config.js';
+export type { ChangeImpactConfig, ChangeImpactConfigLoadResult, ChangeImpactConfigSuggestion, ChangeImpactKind, ChangeImpactTarget, } from './change-impact-config.js';
 export { getGitDiffSummary, getGitFileDiff } from './git-diff.js';
 export type { GitDiffOptions, GitFileDiffResult } from './git-diff.js';
 export { createGitCompactSummary, summarizeGitStatus } from './git-summary.js';
@@ -15,4 +17,4 @@ export type { GitCommandResult, GitCommandServices, GitFileDiff, GitLogEntry, Gi
 export { TurnSnapshotTracker } from './turn-snapshot-tracker.js';
 export type { TurnCompletedCallback } from './turn-snapshot-tracker.js';
 export { createWorktree, listWorktrees, parseWorktreeListOutput, removeWorktree, resolveWorktreePath, } from './git-worktree.js';
-export type { WorktreeCreateOptions, WorktreeCreateResult, WorktreeEntry, WorktreeRemoveResult, } from './git-worktree.js';
+export type { WorktreeBaseSync, WorktreeCreateOptions, WorktreeCreateResult, WorktreeEntry, WorktreeRemoveResult, } from './git-worktree.js';