@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/git/change-impact-config.ts

@@ -0,0 +1,354 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import * as yaml from 'js-yaml';
+
+/**
+ * "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 const CHANGE_IMPACT_CONFIG_LOCATIONS = [
+    '.adhdev/change-impact.json',
+    '.adhdev/change-impact.yaml',
+    '.adhdev/change-impact.yml',
+    '.adhdev/repo-mesh-change-impact.json',
+    '.adhdev/repo-mesh-change-impact.yaml',
+    '.adhdev/repo-mesh-change-impact.yml',
+];
+
+export const CHANGE_IMPACT_CONFIG_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'ADHDev Change Impact Config',
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        daemonRuntimePackages: { type: 'array', items: { type: 'string', minLength: 1 } },
+        webOnlyPackages: { type: 'array', items: { type: 'string', minLength: 1 } },
+        nonRuntimeRootFilePatterns: { type: 'array', items: { type: 'string', minLength: 1 } },
+        impactTargets: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                daemon: { $ref: '#/$defs/target' },
+                web: { $ref: '#/$defs/target' },
+                none: { $ref: '#/$defs/target' },
+            },
+        },
+    },
+    $defs: {
+        target: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['recommendedCommand'],
+            properties: {
+                recommendedCommand: { type: 'string', minLength: 1 },
+            },
+        },
+    },
+} as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+    return Array.isArray(value) && value.every(v => typeof v === 'string' && v.length > 0);
+}
+
+function validateTarget(value: unknown, key: string, errors: string[]): ChangeImpactTarget | undefined {
+    if (!isRecord(value)) {
+        errors.push(`impactTargets.${key} must be an object`);
+        return undefined;
+    }
+    const { recommendedCommand } = value;
+    if (typeof recommendedCommand !== 'string' || !recommendedCommand.length) {
+        errors.push(`impactTargets.${key}.recommendedCommand must be a non-empty string`);
+        return undefined;
+    }
+    // recommendedAction is the fixed classification key; config supplies only the command.
+    for (const k of Object.keys(value)) {
+        if (k !== 'recommendedCommand') errors.push(`impactTargets.${key}.${k} is not a recognized field (only recommendedCommand)`);
+    }
+    return { recommendedCommand };
+}
+
+export function validateChangeImpactConfig(raw: unknown, source = 'inline'): { valid: boolean; errors: string[]; config?: ChangeImpactConfig } {
+    const errors: string[] = [];
+    if (!isRecord(raw)) {
+        return { valid: false, errors: [`${source}: config must be an object`] };
+    }
+    const config: ChangeImpactConfig = {};
+
+    if (raw.daemonRuntimePackages !== undefined) {
+        if (isStringArray(raw.daemonRuntimePackages)) config.daemonRuntimePackages = [...raw.daemonRuntimePackages];
+        else errors.push('daemonRuntimePackages must be an array of non-empty strings');
+    }
+    if (raw.webOnlyPackages !== undefined) {
+        if (isStringArray(raw.webOnlyPackages)) config.webOnlyPackages = [...raw.webOnlyPackages];
+        else errors.push('webOnlyPackages must be an array of non-empty strings');
+    }
+    if (raw.nonRuntimeRootFilePatterns !== undefined) {
+        if (isStringArray(raw.nonRuntimeRootFilePatterns)) config.nonRuntimeRootFilePatterns = [...raw.nonRuntimeRootFilePatterns];
+        else errors.push('nonRuntimeRootFilePatterns must be an array of non-empty strings');
+    }
+    if (raw.impactTargets !== undefined) {
+        if (!isRecord(raw.impactTargets)) {
+            errors.push('impactTargets must be an object');
+        } else {
+            const targets: Partial<Record<ChangeImpactKind, ChangeImpactTarget>> = {};
+            for (const key of Object.keys(raw.impactTargets)) {
+                if (key !== 'daemon' && key !== 'web' && key !== 'none') {
+                    errors.push(`impactTargets.${key} is not a recognized impact kind (daemon|web|none)`);
+                    continue;
+                }
+                const target = validateTarget(raw.impactTargets[key], key, errors);
+                if (target) targets[key as ChangeImpactKind] = target;
+            }
+            if (Object.keys(targets).length) config.impactTargets = targets;
+        }
+    }
+    // Reject unknown top-level keys to catch typos early (mirrors additionalProperties:false).
+    for (const key of Object.keys(raw)) {
+        if (!['daemonRuntimePackages', 'webOnlyPackages', 'nonRuntimeRootFilePatterns', 'impactTargets'].includes(key)) {
+            errors.push(`unknown config key '${key}'`);
+        }
+    }
+
+    return { valid: errors.length === 0, errors, config: errors.length === 0 ? config : undefined };
+}
+
+function parseConfigText(path: string, text: string): unknown {
+    if (/\.json$/i.test(path)) return JSON.parse(text);
+    return yaml.load(text);
+}
+
+/**
+ * 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 function loadChangeImpactConfig(repoRoot: string): ChangeImpactConfigLoadResult {
+    for (const relative of CHANGE_IMPACT_CONFIG_LOCATIONS) {
+        const configPath = join(repoRoot, relative);
+        if (!existsSync(configPath)) continue;
+        try {
+            const text = readFileSync(configPath, 'utf-8');
+            let mtimeMs = 0;
+            try {
+                mtimeMs = statSync(configPath).mtimeMs;
+            } catch {
+                // Best-effort; fall back to content length so edits still perturb the key.
+                mtimeMs = text.length;
+            }
+            const parsed = parseConfigText(configPath, text);
+            const validation = validateChangeImpactConfig(parsed, relative);
+            if (!validation.valid) {
+                return {
+                    source: relative,
+                    sourceType: 'invalid',
+                    path: configPath,
+                    error: validation.errors.join('; '),
+                    sourceKey: `invalid:${configPath}:${mtimeMs}`,
+                };
+            }
+            return {
+                config: validation.config,
+                source: relative,
+                sourceType: 'repo_file',
+                path: configPath,
+                sourceKey: `file:${configPath}:${mtimeMs}`,
+            };
+        } catch (error: any) {
+            return {
+                source: relative,
+                sourceType: 'invalid',
+                path: configPath,
+                error: error?.message || String(error),
+                sourceKey: `error:${configPath}`,
+            };
+        }
+    }
+    return {
+        source: 'unavailable',
+        sourceType: 'unavailable',
+        error: `No change-impact config found. Checked: ${CHANGE_IMPACT_CONFIG_LOCATIONS.join(', ')}`,
+        sourceKey: 'unavailable',
+    };
+}
+
+/**
+ * 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 function globToRegExp(pattern: string): RegExp {
+    let out = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                // `**` → any sequence of characters including path separators.
+                out += '.*';
+                i++;
+                // Swallow a trailing slash after `**/` so `**/x` also matches `x`.
+                if (pattern[i + 1] === '/') i++;
+            } else {
+                out += '[^/]*';
+            }
+        } else if (ch === '?') {
+            out += '[^/]';
+        } else if ('.+^${}()|[]\\'.includes(ch)) {
+            out += '\\' + ch;
+        } else {
+            out += ch;
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+
+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[] };
+}
+
+function listPackageDirs(packagesRoot: string): string[] {
+    try {
+        return readdirSync(packagesRoot, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map(entry => entry.name);
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * 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 function suggestChangeImpactConfig(repoRoot: string): ChangeImpactConfigSuggestion {
+    const notes: string[] = [];
+    const daemon = new Set<string>();
+    const web = new Set<string>();
+    const unclassified: string[] = [];
+
+    const roots = ['packages', join('oss', 'packages')];
+    for (const rel of roots) {
+        const packagesRoot = join(repoRoot, rel);
+        if (!existsSync(packagesRoot)) continue;
+        for (const name of listPackageDirs(packagesRoot)) {
+            if (/(^web[-.]|[-.]web$)/i.test(name) || /dashboard|frontend|ui$/i.test(name)) {
+                web.add(name);
+            } else {
+                daemon.add(name);
+            }
+        }
+    }
+
+    const daemonRuntimePackages = [...daemon].sort();
+    const webOnlyPackages = [...web].sort();
+
+    if (!daemonRuntimePackages.length && !webOnlyPackages.length) {
+        notes.push('No packages/ or oss/packages/ directories found — defaulting to an empty draft you should fill in by hand.');
+    } else {
+        if (daemonRuntimePackages.length) notes.push(`Classified ${daemonRuntimePackages.length} package(s) as daemon-runtime (change → rebuild/redeploy + restart).`);
+        if (webOnlyPackages.length) notes.push(`Classified ${webOnlyPackages.length} web-* package(s) as web-only (change → web redeploy, no daemon restart).`);
+        notes.push('Heuristic only: confirm each package actually matches its bucket before saving.');
+    }
+
+    const nonRuntimeRootFilePatterns = [
+        '*.md',
+        'docs/**',
+        'LICENSE',
+        'LICENSE.*',
+        '.gitignore',
+    ];
+    notes.push('nonRuntimeRootFilePatterns lists root files that demonstrably cannot change daemon runtime behavior; extend with your repo markers.');
+
+    const suggestedConfig: ChangeImpactConfig = {
+        ...(daemonRuntimePackages.length ? { daemonRuntimePackages } : {}),
+        ...(webOnlyPackages.length ? { webOnlyPackages } : {}),
+        nonRuntimeRootFilePatterns,
+        impactTargets: {
+            daemon: { recommendedCommand: 'rebuild + redeploy the daemon, then restart it' },
+            web: { recommendedCommand: 'redeploy the web app (no daemon restart required)' },
+            none: { recommendedCommand: 'no action required' },
+        },
+    };
+
+    return {
+        suggestedConfig,
+        notes,
+        discoveredPackages: { daemon: daemonRuntimePackages, web: webOnlyPackages, unclassified },
+    };
+}

package/src/git/git-commands.ts

@@ -4,6 +4,7 @@ import { getGitDiffSummary, getGitFileDiff } from './git-diff.js';
 import { GitCommandError, isPathInside, resolveGitRepository, runGit } from './git-executor.js';
 import { createGitSnapshotStore } from './git-snapshot-store.js';
 import { getGitRepoStatus } from './git-status.js';
+import { loadConfig } from '../config/config.js';
 import type {
   GitCommandName,
   GitDiffSummary,
@@ -42,8 +43,12 @@ export interface GitLogResult extends GitRepoIdentity {
 }
 
 export interface GitCheckpointResult extends GitRepoIdentity {
-  commit: string;
+  commit?: string;
   message: string;
+  status?: 'created' | 'skipped';
+  skipped?: boolean;
+  noop?: boolean;
+  reason?: 'nothing_to_commit';
   lastCheckedAt: number;
 }
 
@@ -62,9 +67,9 @@ export interface GitPushResult extends GitRepoIdentity {
 }
 
 export interface GitCommandServices {
-  getStatus?: (params: { workspace: string; refreshUpstream?: boolean }) => Promise<GitRepoStatus> | GitRepoStatus;
-  getDiffSummary?: (params: { workspace: string; staged?: boolean }) => Promise<GitDiffSummary> | GitDiffSummary;
-  getDiffFile?: (params: { workspace: string; path: string; staged?: boolean }) => Promise<GitFileDiff> | GitFileDiff;
+  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;
     reason: GitSnapshotReason;
@@ -97,6 +102,14 @@ export interface GitCommandServices {
   checkoutFiles?: (params: { workspace: string; paths: string[] }) => Promise<{ checkedOut: string[] }>;
   getRemoteUrl?: (params: { workspace: string; remote?: string }) => Promise<{ remoteUrl: string; remote: string }>;
   push?: (params: { workspace: string; remote?: string; 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 = {
@@ -106,7 +119,12 @@ type GitCommandFailure = {
 };
 
 type GitCommandSuccess =
-  | { success: true; status: GitRepoStatus }
+  // reporterPlatform/reporterArch carry the responding daemon's process.platform/
+  // process.arch so a mesh coordinator probing this node over P2P can self-heal the
+  // node's userOverrides.platform/arch (the fields capability-tag routing reads).
+  // reporterMachineNickname carries the responding daemon's config.machineNickname
+  // so the coordinator can populate node.machineNickname → the friendly display label.
+  | { success: true; status: GitRepoStatus; reporterPlatform?: string; reporterArch?: string; reporterMachineNickname?: string; reporterProviderVersions?: Record<string, string>; reporterDaemonBuildVersion?: string }
   | { success: true; diffSummary: GitDiffSummary }
   | { success: true; diff: GitFileDiff }
   | { success: true; snapshot: GitSnapshot }
@@ -169,11 +187,13 @@ const defaultSnapshotStore = createGitSnapshotStore({
   getDiffSummary: (workspace) => getGitDiffSummary(workspace),
 });
 
-export function createDefaultGitCommandServices(): GitCommandServices {
+export function createDefaultGitCommandServices(
+  overrides?: Pick<GitCommandServices, 'getReporterProviderVersions'>,
+): GitCommandServices {
   return {
     getStatus: ({ workspace, refreshUpstream }) => getGitRepoStatus(workspace, { refreshUpstream }),
-    getDiffSummary: ({ workspace }) => getGitDiffSummary(workspace),
-    getDiffFile: ({ workspace, path: filePath }) => getGitFileDiff(workspace, filePath),
+    getDiffSummary: ({ workspace, base }) => getGitDiffSummary(workspace, base ? { baseRef: base } : {}),
+    getDiffFile: ({ workspace, path: filePath, base }) => getGitFileDiff(workspace, filePath, base ? { baseRef: base } : {}),
     createSnapshot: ({ workspace, reason, sessionId, turnId }) => defaultSnapshotStore.create({
       workspace,
       reason,
@@ -189,6 +209,9 @@ export function createDefaultGitCommandServices(): GitCommandServices {
     getRemoteUrl: async ({ workspace, remote = 'origin' }) => gitGetRemoteUrl(workspace, remote),
     push: async ({ workspace, remote = 'origin', branch, setUpstream = false }) =>
       gitPush(workspace, remote, branch, setUpstream),
+    ...(overrides?.getReporterProviderVersions
+      ? { getReporterProviderVersions: overrides.getReporterProviderVersions }
+      : {}),
   };
 }
 
@@ -290,13 +313,66 @@ export async function handleGitCommand(
   switch (command) {
     case 'git_status': {
       if (!services.getStatus) return serviceNotImplemented(command);
-      const status = await runService(() => services.getStatus!({ workspace, refreshUpstream: optionalBoolean(args?.refreshUpstream) }));
-      return 'success' in status ? status : { success: true, status };
+      const submoduleIgnorePaths = Array.isArray(args?.submoduleIgnorePaths)
+        ? args.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string' && value.trim().length > 0)
+        : undefined;
+      const statusParams: { workspace: string; refreshUpstream?: boolean; includeSubmodules?: boolean; submoduleIgnorePaths?: string[] } = { workspace };
+      const refreshUpstream = optionalBoolean(args?.refreshUpstream);
+      const includeSubmodules = optionalBoolean(args?.includeSubmodules);
+      if (refreshUpstream !== undefined) statusParams.refreshUpstream = refreshUpstream;
+      if (includeSubmodules !== undefined) statusParams.includeSubmodules = includeSubmodules;
+      if (submoduleIgnorePaths && submoduleIgnorePaths.length > 0) statusParams.submoduleIgnorePaths = submoduleIgnorePaths;
+      const status = await runService(() => services.getStatus!(statusParams));
+      if ('success' in status) return status;
+      // Carry the responding daemon's real platform/arch alongside the git
+      // status. A mesh coordinator dispatches `git_status` to each member over
+      // P2P on every explicit graph refresh, so this is the recurring live
+      // channel that lets a member self-report its OS to the coordinator — which
+      // stamps it onto the node's userOverrides.platform/arch (the fields
+      // buildMeshNodeCapabilityTags reads). These are siblings of `status`, not
+      // part of GitRepoStatus, so the git payload shape is untouched.
+      // The machine nickname rides the same channel so the coordinator can render
+      // this node's friendly label instead of a raw daemonId/nodeId.
+      const reporterMachineNickname = (() => {
+        try {
+          const nick = loadConfig().machineNickname;
+          return typeof nick === 'string' && nick.trim() ? nick.trim() : undefined;
+        } catch {
+          return undefined;
+        }
+      })();
+      // Provider versions + build version ride the same self-report channel (T7
+      // visibility). Best-effort and non-blocking: the service reads a cached
+      // snapshot, so a cold cache simply omits the fields on this probe.
+      const reporterVersions = (() => {
+        try {
+          return services.getReporterProviderVersions?.() ?? {};
+        } catch {
+          return {};
+        }
+      })();
+      const reporterProviderVersions =
+        reporterVersions.providerVersions && Object.keys(reporterVersions.providerVersions).length > 0
+          ? reporterVersions.providerVersions
+          : undefined;
+      const reporterDaemonBuildVersion =
+        typeof reporterVersions.daemonBuildVersion === 'string' && reporterVersions.daemonBuildVersion.trim()
+          ? reporterVersions.daemonBuildVersion.trim()
+          : undefined;
+      return {
+        success: true,
+        status,
+        reporterPlatform: process.platform,
+        reporterArch: process.arch,
+        ...(reporterMachineNickname ? { reporterMachineNickname } : {}),
+        ...(reporterProviderVersions ? { reporterProviderVersions } : {}),
+        ...(reporterDaemonBuildVersion ? { reporterDaemonBuildVersion } : {}),
+      };
     }
 
     case 'git_diff_summary': {
       if (!services.getDiffSummary) return serviceNotImplemented(command);
-      const diffSummary = await runService(() => services.getDiffSummary!({ workspace, staged: optionalBoolean(args?.staged) }));
+      const diffSummary = await runService(() => services.getDiffSummary!({ workspace, staged: optionalBoolean(args?.staged), base: optionalString(args?.base) }));
       return 'success' in diffSummary ? diffSummary : { success: true, diffSummary };
     }
 
@@ -438,10 +514,22 @@ async function gitCheckpoint(
   const repo = await resolveGitRepository(workspace);
   const repoRoot = repo.repoRoot!;
 
-  const statusResult = await getGitRepoStatus(workspace);
+  // Decision-then-mutate path: this conflict / dirty-submodule precheck gates a real
+  // `git add` + `git commit`. Bypass the C1 TTL cache so the checkpoint never proceeds
+  // on a stale "clean" verdict.
+  const statusResult = await getGitRepoStatus(workspace, { forceFresh: true });
   if (statusResult.hasConflicts) {
     throw new GitCommandError('conflict', 'Repository has conflicts — resolve before checkpointing');
   }
+  const dirtySubmodules = (statusResult.submodules || []).filter(submodule => submodule.dirty);
+  if (dirtySubmodules.length > 0) {
+    const paths = dirtySubmodules.map(submodule => submodule.path).join(', ');
+    throw new GitCommandError(
+      'dirty_index_required',
+      `Repository has dirty submodules that must be checkpointed first: ${paths}. ` +
+      'Checkpoint or commit each dirty submodule, then checkpoint this repository to record gitlink changes.',
+    );
+  }
 
   const addArgs = includeUntracked ? ['-A'] : ['-u'];
   await runGit(repo, ['add', ...addArgs], { cwd: repoRoot });
@@ -455,10 +543,17 @@ async function gitCheckpoint(
   } catch (err: any) {
     const output = (err?.stdout || '') + (err?.stderr || '');
     if (/nothing to commit/i.test(output)) {
-      throw new GitCommandError('nothing_to_commit', 'Nothing to commit — working tree is clean.', {
-        stdout: err?.stdout,
-        stderr: err?.stderr,
-      });
+      return {
+        workspace: repo.workspace,
+        repoRoot,
+        isGitRepo: true,
+        message: fullMsg,
+        status: 'skipped',
+        skipped: true,
+        noop: true,
+        reason: 'nothing_to_commit',
+        lastCheckedAt: Date.now(),
+      };
     }
     throw err;
   }
@@ -469,6 +564,7 @@ async function gitCheckpoint(
     isGitRepo: true,
     commit: commitSha,
     message: fullMsg,
+    status: 'created',
     lastCheckedAt: Date.now(),
   };
 }