@adhdev/daemon-core 0.9.82-rc.407 → 0.9.82-rc.409

package/dist/mesh/mesh-queue-assignment.d.ts

@@ -6,7 +6,7 @@ export declare function tryAssignQueueTask(components: DaemonComponents, meshId:
 /** Active assignments that hold the one-active-per-node / global-parallel invariant
  *  (everything except read-only diagnoses, which run unbounded by the write cap). */
 export declare function activeWriteAssignedCount(meshId: string): number;
-/** Active read-only (live_debug_readonly) assignments, for the read-only safety cap. */
+/** Active read-only assignments, for the read-only safety cap. */
 export declare function activeReadonlyAssignedCount(meshId: string): number;
 /**
  * Order eligible nodes for assignment per the mesh scheduling pipeline:

package/dist/mesh/mesh-work-queue.d.ts

@@ -7,6 +7,28 @@ export type MeshTaskMode = 'code_change' | 'validation' | 'live_debug_readonly'
 export declare const ACTIVE_MESH_QUEUE_STATUSES: MeshActiveTaskStatus[];
 export declare const HISTORICAL_MESH_QUEUE_STATUSES: MeshHistoricalTaskStatus[];
 export declare const MESH_TASK_MODES: MeshTaskMode[];
+/**
+ * QUEUE-NODE-SERIALIZATION: single source of truth for "is this task read-only?".
+ *
+ * Read-only classification used to be inlined as `task.taskMode === 'live_debug_readonly'`
+ * at every enforcement site (node-conflict claim gate, auto-launch isolation, the
+ * write/readonly cap counters, the write guardrail). That spread-out comparison is the
+ * exact recurring-defect class — one site drifting from the others silently makes the same
+ * task read-only at some gates and write at others, i.e. partial serialization. All sites
+ * MUST call this predicate so the classification is decided in exactly one place.
+ *
+ * Two orthogonal inputs feed the same boolean axis (kept backward-compatible):
+ *   • `readonly === true` — the explicit boolean axis (new API surface).
+ *   • `taskMode === 'live_debug_readonly'` — the original enum value, preserved as an
+ *     OR-fallback so existing live_debug_readonly tasks keep behaving identically.
+ *
+ * Accepts any task-like shape (full {@link MeshWorkQueueEntry} or a bare
+ * `{ readonly?, taskMode? }`) so the daemon-core and mcp-server boundaries can share it.
+ */
+export declare function isTaskReadonly(task: {
+    readonly?: boolean;
+    taskMode?: MeshTaskMode | string;
+} | null | undefined): boolean;
 export interface MeshTaskModeValidationResult {
     valid: boolean;
     taskMode?: MeshTaskMode;
@@ -14,13 +36,21 @@ export interface MeshTaskModeValidationResult {
     allowedOperations?: string[];
 }
 export declare function normalizeMeshTaskMode(value: unknown): MeshTaskMode | undefined;
-export declare function validateMeshTaskModeRequest(mode: unknown, message: string): MeshTaskModeValidationResult;
+export declare function validateMeshTaskModeRequest(mode: unknown, message: string, readonly?: boolean): MeshTaskModeValidationResult;
 export interface MeshWorkQueueEntry {
     id: string;
     meshId: string;
     message: string;
     status: MeshTaskStatus;
     taskMode?: MeshTaskMode;
+    /**
+     * QUEUE-NODE-SERIALIZATION: explicit read-only axis, orthogonal to taskMode. When
+     * true the task is treated as read-only by every scheduling gate (no node-busy
+     * isolation, counted under the read-only cap, write commands rejected) regardless of
+     * its taskMode. Decided exclusively through {@link isTaskReadonly}; `taskMode ===
+     * 'live_debug_readonly'` remains an OR-fallback so legacy rows behave unchanged.
+     */
+    readonly?: boolean;
     /** If specified, only this node can claim the task (used by legacy mesh_send_task) */
     targetNodeId?: string;
     /** If specified, only this runtime session can claim the task */
@@ -140,6 +170,8 @@ export declare function enqueueTask(meshId: string, message: string, opts?: {
     targetNodeId?: string;
     targetSessionId?: string;
     taskMode?: MeshTaskMode | string;
+    /** QUEUE-NODE-SERIALIZATION: explicit read-only axis (orthogonal to taskMode). */
+    readonly?: boolean;
     requiredTags?: string[];
     /** M1: tasks that must complete before this one is claimable. */
     dependsOn?: string[];
@@ -174,6 +206,8 @@ export declare function recordDirectDispatchTask(meshId: string, message: string
     assignedNodeId?: string;
     assignedSessionId?: string;
     taskMode?: MeshTaskMode | string;
+    /** QUEUE-NODE-SERIALIZATION: explicit read-only axis (orthogonal to taskMode). */
+    readonly?: boolean;
     dispatchedAt?: string;
 }): MeshWorkQueueEntry | null;
 /**

package/dist/providers/chat-message-normalization.d.ts

@@ -1,6 +1,24 @@
 import type { ChatMessage } from '../types.js';
 export declare const DEFAULT_FINAL_SUMMARY_MAX_CHARS = 16000;
 export declare function extractFinalSummaryFromMessages(messages: ChatMessage[] | null | undefined, maxChars?: number): string;
+/**
+ * Turn-scoped variant of extractFinalSummaryFromMessages. Selects the last
+ * user-facing assistant/model bubble whose own timestamp is at/after the
+ * producing turn's start (`minTimestampMs`). This is the NOTIF Defect-B fix:
+ * a completion event's finalSummary must describe the turn THAT completed, not
+ * the prior task's last bubble. For native-source providers (claude-cli) the
+ * external transcript holds the ENTIRE session history filtered only by session
+ * start, so a completion debounce that fires before the producing turn's final
+ * assistant bubble has landed would otherwise echo the previous task's tail.
+ * A message whose timestamp predates the turn start is skipped; if no in-turn
+ * assistant bubble exists yet, returns '' (weak/empty) — never the stale tail.
+ *
+ * Mirrors the reconcile path's transcriptAfterDispatch guard (mesh-events-stale):
+ * a bubble only counts if its timestamp proves it was produced after the turn began.
+ * When `minTimestampMs` is undefined the behaviour is identical to the unscoped
+ * extractor (no turn boundary known → no filtering).
+ */
+export declare function extractFinalSummaryFromMessagesAfter(messages: ChatMessage[] | null | undefined, minTimestampMs: number | undefined, maxChars?: number): string;
 /**
  * Like extractFinalSummaryFromMessages but also returns the ISO timestamp of the
  * selected final assistant/model message. Completion reconciliation needs the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.407",
+  "version": "0.9.82-rc.409",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.407",
+    "@adhdev/mesh-shared": "0.9.82-rc.409",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/cli-adapters/terminal-backends/ghostty-vt-backend.ts

@@ -29,6 +29,15 @@ function isModuleNotFoundError(error: unknown, ref: string): boolean {
     return code === 'MODULE_NOT_FOUND' && message.includes(ref);
 }
 
+// Identifies the host runtime so a binding-load failure names the exact ABI it
+// looked for. The underlying binding is N-API (ABI-stable), so a failure here is
+// almost always "no prebuilt directory addressed this triplet" rather than a
+// true ABI incompatibility — making the triplet the single most useful
+// diagnostic to surface in an env-blocker report.
+function runtimeTriplet(): string {
+    return `${process.platform}-${process.arch}-node${process.versions.modules}`;
+}
+
 function normalizeBinding(mod: any, ref: string): GhosttyVtBinding {
     const binding = mod?.default?.createTerminal
         ? mod.default
@@ -75,7 +84,8 @@ function loadGhosttyVtBinding(): GhosttyVtBinding {
 
     cachedBinding = null;
     cachedBindingError = new Error(
-        `ghostty-vt binding unavailable (${errors.join('; ') || 'no candidates tried'})`,
+        `ghostty-vt binding unavailable for runtime ${runtimeTriplet()} ` +
+            `(${errors.join('; ') || 'no candidates tried'})`,
     );
     throw cachedBindingError;
 }

package/src/commands/chat-commands-write.ts

@@ -752,6 +752,17 @@ export async function handleResolveAction(h: CommandHelpers, args: any): Promise
             : status?.status;
         LOG.info('Command', `[resolveAction] CLI PTY gate target=${String(args?.targetSessionId || '')} rawStatus=${String(status?.status || '')} effectiveStatus=${String(effectiveStatus || '')} statusModal=${statusModal ? 'yes' : 'no'} surfacedModal=${surfacedModal ? 'yes' : 'no'} parsedModal=${parsedModal ? 'yes' : 'no'} instance=${targetInstance ? 'yes' : 'no'}`);
         if (!effectiveModal) {
+            // APPROVAL Defect-B (live re-probe race): the modal is gone because the worker
+            // already resolved this very approval moments ago (delegated auto-approve fired,
+            // or a prior resolveAction landed) and the coordinator's approve raced in just
+            // after. That is NOT a caller error — return a SOFT already_resolved result so the
+            // coordinator does not hard-fail the task on a benign race. Mirrors the in-modal
+            // idempotency guard below (isApprovalRecentlyResolved → stalePrompt). Only a session
+            // that never had a recently-resolved approval reports the hard 'Not in approval state'.
+            if (typeof adapter.isApprovalRecentlyResolved === 'function' && adapter.isApprovalRecentlyResolved()) {
+                LOG.info('Command', `[resolveAction] CLI PTY → already_resolved (modal gone, resolved within cooldown)`);
+                return { success: true, alreadyResolved: true, status: 'already_resolved' };
+            }
             return { success: false, error: 'Not in approval state' };
         }
         const buttons: string[] = Array.isArray(effectiveModal.buttons) ? effectiveModal.buttons : [];

package/src/git/git-commands.ts

@@ -462,7 +462,10 @@ 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');
   }

package/src/git/git-status.ts

@@ -12,12 +12,45 @@ import {
 type ResolvedGitRepo = { workspace: string; repoRoot: string | null; isGitRepo: boolean };
 
 /**
- * Last successfully-collected status per workspace, used to survive a transient git
- * failure (timeout, slow Windows spawn under load, a momentary lock) WITHOUT dropping
- * the node out of the mesh graph. A genuine "not a git repository" answer is NOT a
- * transient failure — it never populates this cache and always reports isGitRepo:false.
+ * 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.
  */
-const lastKnownGoodStatus = new Map<string, GitRepoStatus>();
+export const GIT_STATUS_CACHE_TTL_MS = 1500;
+
+/**
+ * Last successfully-collected status per (workspace, option-shape), used for two things:
+ *   1. C1 TTL result cache — on the happy path, a cached entry younger than
+ *      GIT_STATUS_CACHE_TTL_MS is returned directly (gated by `cachedAt`).
+ *   2. Transient-failure fallback — survive a transient git failure (timeout, slow
+ *      Windows spawn under load, a momentary lock) WITHOUT dropping the node out of the
+ *      mesh graph by re-serving the last good status, re-stamped as stale.
+ * A genuine "not a git repository" answer is NOT a transient failure — it never
+ * populates this cache and always reports isGitRepo:false. Only a successful, fully
+ * populated status is ever cached; error/empty results never are.
+ *
+ * The key folds in the option fields that change the SHAPE of the collected result
+ * (includeSubmodules, refreshUpstream) so different callers don't read each other's
+ * partial results. Fields that only affect timing/policy (timeoutMs, daemonBuildInfo,
+ * changeImpactConfig, submoduleIgnorePaths) are NOT part of the key — they don't change
+ * what a fresh same-shape collection would currently return for the happy path, and the
+ * sub-caches (changeImpactEvalCache) already key on their own invalidators.
+ */
+interface CachedStatusEntry {
+  status: GitRepoStatus;
+  cachedAt: number;
+}
+const lastKnownGoodStatus = new Map<string, CachedStatusEntry>();
+
+/** Cache key folding in only the option fields that change the result shape. */
+function statusCacheKey(workspace: string, options: GitStatusOptions): string {
+  const includeSubmodules = options.includeSubmodules !== false;
+  const refreshUpstream = options.refreshUpstream === true;
+  return `${workspace}\0sub=${includeSubmodules ? 1 : 0}\0up=${refreshUpstream ? 1 : 0}`;
+}
 
 /**
  * Memoized Change Impact evaluation, keyed by the inputs that can change the
@@ -45,13 +78,31 @@ interface ChangeImpactConfigCacheEntry {
 }
 const changeImpactConfigCache = new Map<string, ChangeImpactConfigCacheEntry>();
 
+/**
+ * C3: memoized ancestry verdict for the daemon-build-behind probe, keyed by
+ * `${repoPath}::${buildCommit}::${headOid}`. For a fixed (build commit, HEAD oid) pair
+ * the ancestry relationship (is build an ancestor of HEAD? equal? unrelated?) is
+ * immutable, so the verdict can be cached indefinitely — it auto-invalidates the moment
+ * HEAD moves (new oid → new key). This removes the steady-state `cat-file` +
+ * `rev-parse` + `merge-base` spawns (2-3 per scope) when HEAD has not moved between
+ * probes. A value of `false` means "build is NOT a strict ancestor of HEAD" (current,
+ * ahead, or unrelated — no warning); `true` means a strict-ancestor relationship was
+ * proven for that pair.
+ */
+const buildBehindAncestryCache = new Map<string, boolean>();
+
 /** Test seam: clear the last-known-good status cache between cases. */
 export function __resetGitStatusCacheForTests(): void {
   lastKnownGoodStatus.clear();
   changeImpactEvalCache.clear();
   changeImpactConfigCache.clear();
+  upstreamFetchedAt.clear();
+  buildBehindAncestryCache.clear();
 }
 
+/** Alias matching the task's requested name. */
+export const __resetGitStatusCache = __resetGitStatusCacheForTests;
+
 /** Test-only introspection: number of memoized Change Impact evaluations. */
 export function __changeImpactEvalCacheSizeForTests(): number {
   return changeImpactEvalCache.size;
@@ -77,6 +128,18 @@ 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
@@ -96,10 +159,25 @@ export interface GitStatusOptions {
   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 const GIT_FETCH_THROTTLE_MS = 30_000;
+
+/** Wall-clock of the last successful `git fetch` per workspace (C2 throttle gate). */
+const upstreamFetchedAt = new Map<string, number>();
+
 interface GitUpstreamProbe {
   upstreamStatus: GitUpstreamFreshness;
   upstreamFetchedAt?: number;
   upstreamFetchError?: string;
+  /** True only when this probe performed an actual network fetch (porcelain re-read needed). */
+  didFetch?: boolean;
 }
 
 export async function getGitRepoStatus(
@@ -116,10 +194,26 @@ export async function getGitRepoStatus(
   const effectiveOptions: GitStatusOptions =
     options.timeoutMs === undefined ? { ...options, timeoutMs: GIT_STATUS_TIMEOUT_MS } : options;
 
+  const cacheKey = statusCacheKey(workspace, options);
+
+  // C1: happy-path TTL result cache. A non-forceFresh caller within the TTL window is
+  // served the last successfully-collected status for this exact option shape instead
+  // of re-shelling ~14 git processes. Only successful, fully-populated results are ever
+  // stored (see the .set below + the never-cache-error rule in the catch), so a cache
+  // hit can never serve an error/empty status.
+  if (!options.forceFresh) {
+    const cached = lastKnownGoodStatus.get(cacheKey);
+    if (cached && lastCheckedAt - cached.cachedAt < GIT_STATUS_CACHE_TTL_MS) {
+      return cached.status;
+    }
+  }
+
   try {
     const repo = await resolveGitRepository(workspace, effectiveOptions);
     const status = await collectGitRepoStatus(repo, includeSubmodules, lastCheckedAt, effectiveOptions);
-    lastKnownGoodStatus.set(workspace, status);
+    // Cache the fresh, fully-populated success. forceFresh callers still refresh the
+    // cache so the next normal caller benefits from their freshly-collected status.
+    lastKnownGoodStatus.set(cacheKey, { status, cachedAt: lastCheckedAt });
     return status;
   } catch (error) {
     const gitError = error instanceof GitCommandError
@@ -130,7 +224,7 @@ export async function getGitRepoStatus(
     // a healthy node lose its repo identity and drop out of the mesh graph. Prefer the
     // last status we successfully collected for this workspace, re-stamped as stale.
     if (isTransientGitFailure(gitError)) {
-      const cached = lastKnownGoodStatus.get(workspace);
+      const cached = lastKnownGoodStatus.get(cacheKey)?.status;
       if (cached) {
         return {
           ...cached,
@@ -157,7 +251,11 @@ async function collectGitRepoStatus(
 
     if (options.refreshUpstream) {
       upstreamProbe = await refreshTrackedUpstream(repo, parsed, options);
-      if (upstreamProbe.upstreamStatus === 'fresh') {
+      // Re-read the porcelain (to pick up the updated ahead/behind) ONLY when this probe
+      // actually fetched. When the fetch was throttled (C2), the remote-tracking ref is
+      // unchanged, so the ahead/behind already parsed is still correct — re-reading would
+      // be a wasted spawn.
+      if (upstreamProbe.upstreamStatus === 'fresh' && upstreamProbe.didFetch) {
         parsed = await readPorcelainStatus(repo, options);
       }
     }
@@ -166,8 +264,11 @@ async function collectGitRepoStatus(
     const stashCount = await readStashCount(repo, options);
 
     let submodules: GitSubmoduleStatus[] | undefined;
+    let submoduleHeadOids = new Map<string, string>();
     if (includeSubmodules) {
-      submodules = await getSubmoduleStatuses(repo, options);
+      const subResult = await getSubmoduleStatuses(repo, options);
+      submodules = subResult.submodules;
+      submoduleHeadOids = subResult.headOidByPath;
     }
     const submoduleDirty = (submodules || []).some(submodule => submodule.dirty || submodule.outOfSync || !!submodule.error);
     const dirty = parsed.staged + parsed.modified + parsed.untracked + parsed.deleted + parsed.renamed > 0
@@ -175,7 +276,10 @@ async function collectGitRepoStatus(
       || stashCount > 0
       || submoduleDirty;
 
-    const daemonBuildBehind = await detectDaemonBuildBehind(repo, submodules, options);
+    const daemonBuildBehind = await detectDaemonBuildBehind(repo, submodules, options, {
+      rootHeadOid: parsed.headOid,
+      submoduleHeadOids,
+    });
 
     return {
       workspace: repo.workspace,
@@ -426,10 +530,18 @@ function resolveChangeImpactConfigForRepo(
   return { config, sourceKey: loaded.sourceKey };
 }
 
+interface DaemonBuildBehindHeadOids {
+  /** Root repo HEAD oid from porcelain `# branch.oid` (avoids a rev-parse spawn). */
+  rootHeadOid: string | null;
+  /** Per-submodule-path actual HEAD oid (already read during submodule collection). */
+  submoduleHeadOids: Map<string, string>;
+}
+
 async function detectDaemonBuildBehind(
   repo: ResolvedGitRepo,
   submodules: GitSubmoduleStatus[] | undefined,
   options: GitStatusOptions,
+  headOids: DaemonBuildBehindHeadOids = { rootHeadOid: null, submoduleHeadOids: new Map() },
 ): Promise<DaemonBuildBehind | undefined> {
   const build = options.daemonBuildInfo ?? getDaemonBuildInfo();
   if (!build.commit || build.commit === 'unknown') return undefined;
@@ -440,23 +552,60 @@ async function detectDaemonBuildBehind(
   // Check the root repo first, then each submodule. The daemon build commit is
   // baked from the daemon-core (oss submodule) HEAD, so on an adhdev
   // superproject worktree the match is expected on the `oss` submodule, not the
-  // root — checking both keeps the helper repo-agnostic.
-  const scopes: Array<{ scope: string; repoPath: string }> = [
-    { scope: 'root', repoPath: repo.repoRoot || repo.workspace },
+  // root — checking both keeps the helper repo-agnostic. The known HEAD oid (from
+  // porcelain for root, from the submodule rev-parse already paid during collection)
+  // is threaded in so the C3 ancestry cache can short-circuit before any spawn.
+  const scopes: Array<{ scope: string; repoPath: string; knownHeadOid: string | null }> = [
+    { scope: 'root', repoPath: repo.repoRoot || repo.workspace, knownHeadOid: headOids.rootHeadOid },
   ];
   for (const sub of submodules || []) {
-    if (sub.repoPath && !sub.error) scopes.push({ scope: sub.path, repoPath: sub.repoPath });
+    if (sub.repoPath && !sub.error) {
+      scopes.push({ scope: sub.path, repoPath: sub.repoPath, knownHeadOid: headOids.submoduleHeadOids.get(sub.path) ?? null });
+    }
   }
 
-  for (const { scope, repoPath } of scopes) {
+  for (const { scope, repoPath, knownHeadOid } of scopes) {
     try {
-      // Build commit must be a real object in THIS repo, else it's a different repo.
-      await runGit(repoPath, ['cat-file', '-e', `${build.commit}^{commit}`], options);
-      const headResult = await runGit(repoPath, ['rev-parse', 'HEAD'], options);
-      const head = headResult.stdout.trim();
-      if (!head || head === build.commit) continue;
-      // Strict ancestor: build commit is reachable from HEAD but is not HEAD.
-      await runGit(repoPath, ['merge-base', '--is-ancestor', build.commit, 'HEAD'], options);
+      // C3 fast path: if we already know this scope's HEAD oid and have a cached
+      // ancestry verdict for (repoPath, buildCommit, headOid), reuse it. A `false`
+      // verdict (not a strict ancestor — current/ahead/unrelated) lets us skip the
+      // cat-file + merge-base spawns entirely; the verdict auto-invalidates when HEAD
+      // moves (new oid → new key). A `true` verdict still needs the diff
+      // classification below, which is itself memoized on the same head oid.
+      let head = knownHeadOid;
+      const ancestryKey = head ? `${repoPath}::${build.commit}::${head}` : null;
+      if (ancestryKey) {
+        const cachedVerdict = buildBehindAncestryCache.get(ancestryKey);
+        if (cachedVerdict === false) continue;
+        if (cachedVerdict === undefined) {
+          if (head === build.commit) {
+            buildBehindAncestryCache.set(ancestryKey, false);
+            continue;
+          }
+          // Build commit must be a real object in THIS repo, else it's a different repo.
+          await runGit(repoPath, ['cat-file', '-e', `${build.commit}^{commit}`], options);
+          try {
+            await runGit(repoPath, ['merge-base', '--is-ancestor', build.commit, 'HEAD'], options);
+          } catch {
+            // Not a strict ancestor — cache the negative verdict so the next probe at
+            // this same HEAD short-circuits, then move on to the next scope.
+            buildBehindAncestryCache.set(ancestryKey, false);
+            continue;
+          }
+          buildBehindAncestryCache.set(ancestryKey, true);
+        }
+        // cachedVerdict === true (or just proven true) → fall through to classification.
+      } else {
+        // No known HEAD oid for this scope — fall back to the original probe (resolve
+        // HEAD via rev-parse). This keeps correctness when porcelain/submodule oid is
+        // unavailable; the verdict is still cached once HEAD is known.
+        await runGit(repoPath, ['cat-file', '-e', `${build.commit}^{commit}`], options);
+        const headResult = await runGit(repoPath, ['rev-parse', 'HEAD'], options);
+        head = headResult.stdout.trim();
+        if (!head || head === build.commit) continue;
+        await runGit(repoPath, ['merge-base', '--is-ancestor', build.commit, 'HEAD'], options);
+        buildBehindAncestryCache.set(`${repoPath}::${build.commit}::${head}`, true);
+      }
       // No throw → build commit IS an ancestor of HEAD → daemon is behind.
       // Inspect WHICH packages changed in buildCommit..HEAD. A daemon rebuild/restart
       // is only actually required when a daemon-runtime package changed; if only web /
@@ -465,6 +614,7 @@ async function detectDaemonBuildBehind(
       // verdict is memoized on (repoPath, buildCommit, head, config) to suppress
       // re-evaluation on the hot status path.
       const evalKey = `${repoPath}${build.commit}${head}${configKey}`;
+      if (!head) continue; // proven non-empty oid here; every other branch above continued
       let evaluated = changeImpactEvalCache.get(evalKey);
       if (!evaluated) {
         evaluated = await classifyDaemonBuildChange(repoPath, build.commit, options, policy);
@@ -509,6 +659,8 @@ async function detectDaemonBuildBehind(
 
 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;
@@ -540,6 +692,20 @@ async function refreshTrackedUpstream(
     return { upstreamStatus: 'no_upstream' };
   }
 
+  // C2: throttle the actual network fetch. If we fetched this workspace within
+  // GIT_FETCH_THROTTLE_MS, skip the fetch and serve ahead/behind from the local
+  // porcelain (re-read fresh every call by the caller). forceFresh callers
+  // (convergence-critical: ff / refine) always re-fetch — they need true upstream.
+  const now = Date.now();
+  const lastFetch = upstreamFetchedAt.get(repo.workspace);
+  if (!options.forceFresh && lastFetch !== undefined && now - lastFetch < GIT_FETCH_THROTTLE_MS) {
+    return {
+      upstreamStatus: 'fresh',
+      upstreamFetchedAt: lastFetch,
+      didFetch: false,
+    };
+  }
+
   const remoteName = (await readBranchRemote(repo, parsed.branch, options)) ?? inferRemoteName(parsed.upstream);
   if (!remoteName) {
     return {
@@ -550,9 +716,12 @@ async function refreshTrackedUpstream(
 
   try {
     await runGit(repo, ['fetch', '--quiet', '--prune', '--no-tags', remoteName], options);
+    const fetchedAt = Date.now();
+    upstreamFetchedAt.set(repo.workspace, fetchedAt);
     return {
       upstreamStatus: 'fresh',
-      upstreamFetchedAt: Date.now(),
+      upstreamFetchedAt: fetchedAt,
+      didFetch: true,
     };
   } catch (error) {
     return {
@@ -589,6 +758,7 @@ function formatGitError(error: unknown): string {
 export function parsePorcelainV2Status(output: string): ParsedPorcelainStatus {
   const parsed: ParsedPorcelainStatus = {
     branch: null,
+    headOid: null,
     upstream: null,
     ahead: 0,
     behind: 0,
@@ -603,6 +773,13 @@ export function parsePorcelainV2Status(output: string): ParsedPorcelainStatus {
   for (const line of output.split('\n')) {
     if (!line) continue;
 
+    if (line.startsWith('# branch.oid ')) {
+      const oid = line.slice('# branch.oid '.length).trim();
+      // `(initial)` is git's sentinel for an unborn HEAD — not a real object id.
+      parsed.headOid = oid && oid !== '(initial)' && /^[0-9a-f]{7,64}$/.test(oid) ? oid : null;
+      continue;
+    }
+
     if (line.startsWith('# branch.head ')) {
       const branch = line.slice('# branch.head '.length).trim();
       parsed.branch = branch && branch !== '(detached)' ? branch : null;
@@ -719,11 +896,17 @@ function emptyStatus(workspace: string, lastCheckedAt: number, error: GitCommand
 
 // ─── Submodule Status ───────────────────────────
 
+interface SubmoduleStatusResult {
+  submodules: GitSubmoduleStatus[];
+  /** Actual checked-out HEAD oid per submodule path (for the C3 ancestry cache key). */
+  headOidByPath: Map<string, string>;
+}
+
 async function getSubmoduleStatuses(
   repo: ResolvedGitRepo,
   options: GitStatusOptions,
-): Promise<GitSubmoduleStatus[]> {
-  if (!repo.repoRoot) return [];
+): Promise<SubmoduleStatusResult> {
+  if (!repo.repoRoot) return { submodules: [], headOidByPath: new Map() };
 
   try {
     // Do NOT shell out to `git submodule status`. That porcelain wrapper is a
@@ -743,11 +926,11 @@ async function getSubmoduleStatuses(
     // (conflict) prefix is surfaced separately via the superproject porcelain
     // status that the caller already parses, and a conflicted submodule's own
     // status read here also flags it dirty — so no row is lost.
-    const submodules = await deriveSubmoduleGitlinkStatuses(repo, options);
+    const { submodules, headOidByPath } = await deriveSubmoduleGitlinkStatuses(repo, options);
     await Promise.all(submodules.map(submodule => enrichSubmoduleWorktreeStatus(repo, submodule, options)));
-    return submodules;
+    return { submodules, headOidByPath };
   } catch {
-    return [];
+    return { submodules: [], headOidByPath: new Map() };
   }
 }
 
@@ -760,11 +943,12 @@ async function getSubmoduleStatuses(
 async function deriveSubmoduleGitlinkStatuses(
   repo: ResolvedGitRepo,
   options: GitStatusOptions,
-): Promise<GitSubmoduleStatus[]> {
-  if (!repo.repoRoot) return [];
+): Promise<SubmoduleStatusResult> {
+  if (!repo.repoRoot) return { submodules: [], headOidByPath: new Map() };
   const paths = await readSubmodulePaths(repo, options);
   const ignoreSet = new Set(options.submoduleIgnorePaths || []);
   const lastCheckedAt = Date.now();
+  const headOidByPath = new Map<string, string>();
 
   const entries = await Promise.all(
     paths
@@ -773,6 +957,10 @@ async function deriveSubmoduleGitlinkStatuses(
         const repoPath = repo.repoRoot + '/' + path;
         const expected = await readGitlinkExpectedSha(repo, path, options);
         const actual = await readSubmoduleHeadSha(repo, repoPath, options);
+        // Reuse the actual checked-out HEAD oid for the C3 build-behind ancestry cache
+        // key — it's the submodule HEAD the daemon build commit is tested against, and
+        // we already paid this rev-parse for the outOfSync check, so no extra spawn.
+        if (actual) headOidByPath.set(path, actual);
         // Uninitialized / no checked-out HEAD reproduces `git submodule status`'s
         // `-` prefix; a present-but-divergent HEAD reproduces the `+` prefix.
         const outOfSync = actual === null
@@ -790,7 +978,7 @@ async function deriveSubmoduleGitlinkStatuses(
         };
       }),
   );
-  return entries;
+  return { submodules: entries, headOidByPath };
 }
 
 /** Read submodule paths from `.gitmodules` via plumbing (no shell wrapper). */

package/src/index.ts

@@ -247,7 +247,7 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
+export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, isTaskReadonly, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
 export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord, MeshToolCallRateResult } from './mesh/mesh-work-queue.js';
 export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary, classifyStaleDirectForPrune, pruneStaleDirectDispatches, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
 export type { StaleDirectPruneClassification, StaleDirectPruneResult, PruneStaleDirectDispatchesOptions } from './mesh/mesh-active-work.js';

package/src/mesh/mesh-fast-forward.ts

@@ -87,7 +87,11 @@ type MeshFastForwardBase = Pick<
   'workspace' | 'mode' | 'dryRun' | 'updateSubmodules' | 'plannedSteps' | 'trigger'
 > & Pick<Partial<MeshFastForwardResult>, 'nodeId' | 'meshId'>;
 
-const STATUS_OPTIONS = { refreshUpstream: true, includeSubmodules: true, timeoutMs: 15_000 } as const;
+// forceFresh: fast-forward is a mutating/decision path — its preflight blockers and its
+// post-merge re-reads MUST see live git state, never a TTL-cached status from a
+// concurrent reconcile/mesh_status probe. It also bypasses the fetch throttle so
+// ahead/behind reflects a true upstream at decision time.
+const STATUS_OPTIONS = { refreshUpstream: true, includeSubmodules: true, timeoutMs: 15_000, forceFresh: true } as const;
 
 export async function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promise<MeshFastForwardResult> {
   const workspace = typeof args.workspace === 'string' ? args.workspace.trim() : '';