@adhdev/daemon-core 0.9.82-rc.7 → 0.9.82-rc.9

package/dist/repo-mesh-types.d.ts

@@ -213,14 +213,135 @@ export interface RepoMeshStatus {
     repoIdentity: string;
     refreshedAt: string;
     nodes: RepoMeshNodeStatus[];
+    queue?: RepoMeshQueueStatus;
+    ledger?: RepoMeshLedgerStatus;
+}
+export interface RepoMeshSessionStatus {
+    sessionId: string;
+    providerType?: string;
+    state?: string;
+    lifecycle?: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'interrupted';
+    surfaceKind?: 'live_runtime' | 'recovery_snapshot' | 'inactive_record';
+    recoveryState?: string | null;
+    workspace?: string | null;
+    title?: string | null;
+    lastActivityAt?: string | null;
+    isCached?: boolean;
+}
+export type RepoMeshPeerConnectionState = 'self' | 'connected' | 'connecting' | 'disconnected' | 'failed' | 'closed' | 'unknown';
+export type RepoMeshPeerConnectionTransport = 'local' | 'direct' | 'relay' | 'unknown';
+export interface RepoMeshPeerConnectionStatus {
+    perspective: 'selected_coordinator';
+    source: 'mesh_peer_status' | 'not_reported';
+    state: RepoMeshPeerConnectionState;
+    transport: RepoMeshPeerConnectionTransport;
+    reported: boolean;
+    reason?: string;
+    lastStateChangeAt?: string;
+    lastConnectedAt?: string;
+    lastCommandAt?: string;
 }
 export interface RepoMeshNodeStatus {
     nodeId: string;
     machineLabel: string;
     workspace: string;
+    repoRoot?: string;
+    daemonId?: string;
+    machineId?: string;
+    machineStatus?: string;
+    isLocalWorktree?: boolean;
+    worktreeBranch?: string;
     health: RepoMeshNodeHealth;
     git?: GitRepoStatus;
     providers: string[];
     activeSessions: string[];
+    activeSessionDetails?: RepoMeshSessionStatus[];
+    providerPriority?: string[];
+    launchReady?: boolean;
+    lastSeenAt?: string;
+    updatedAt?: string;
+    connection?: RepoMeshPeerConnectionStatus;
     error?: string;
 }
+export type RepoMeshQueueTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
+export interface RepoMeshQueueTask {
+    id: string;
+    meshId: string;
+    message: string;
+    status: RepoMeshQueueTaskStatus;
+    targetNodeId?: string;
+    targetSessionId?: string;
+    assignedNodeId?: string;
+    assignedSessionId?: string;
+    cancelReason?: string;
+    cancelledAt?: string;
+    requeueReason?: string;
+    requeuedAt?: string;
+    requeueCount?: number;
+    autoLaunch?: {
+        status: 'skipped' | 'started' | 'failed' | 'completed';
+        reason?: string;
+        nodeId?: string;
+        providerType?: string;
+        sessionId?: string;
+        updatedAt: string;
+    };
+    dispatchTimestamp?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RepoMeshQueueSummary {
+    total: number;
+    active: number;
+    historical: number;
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    activeCounts: {
+        pending: number;
+        assigned: number;
+    };
+    historicalCounts: {
+        completed: number;
+        failed: number;
+        cancelled: number;
+    };
+    activeAssignments: Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+        message: string;
+    }>;
+}
+export interface RepoMeshQueueStatus {
+    tasks: RepoMeshQueueTask[];
+    summary: RepoMeshQueueSummary;
+}
+export interface RepoMeshLedgerEntryStatus {
+    id: string;
+    meshId: string;
+    timestamp: string;
+    kind: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    payload: Record<string, unknown>;
+}
+export interface RepoMeshLedgerSummaryStatus {
+    meshId: string;
+    totalEntries: number;
+    taskDispatched: number;
+    taskCompleted: number;
+    taskFailed: number;
+    taskStalled: number;
+    sessionLaunched: number;
+    checkpointCreated: number;
+    lastActivityAt: string | null;
+    recentFailures: number;
+}
+export interface RepoMeshLedgerStatus {
+    entries: RepoMeshLedgerEntryStatus[];
+    summary: RepoMeshLedgerSummaryStatus;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.7",
+  "version": "0.9.82-rc.9",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/boot/daemon-lifecycle.ts

@@ -86,6 +86,8 @@ export interface DaemonInitConfig {
 
     /** Relays a command to a remote mesh node daemon */
     dispatchMeshCommand?: (daemonId: string, command: string, args: Record<string, unknown>) => Promise<any>;
+    /** Returns selected-coordinator mesh peer telemetry for a target daemon when available. */
+    getMeshPeerConnectionStatus?: (daemonId: string) => Record<string, unknown> | null;
 }
 
 // ─── Result ───
@@ -306,6 +308,7 @@ export async function initDaemonComponents(config: DaemonInitConfig): Promise<Da
         sessionHostControl: config.sessionHostControl,
         statusInstanceId: config.statusInstanceId,
         statusVersion: config.statusVersion,
+        getMeshPeerConnectionStatus: config.getMeshPeerConnectionStatus,
         getCdpLogFn: config.getCdpLogFn || ((ideType: string) => LOG.forComponent(`CDP:${ideType}`).asLogFn()),
     });
 

package/src/commands/router.ts

@@ -259,17 +259,93 @@ function readCachedInlineMeshActiveSessions(node: any): string[] {
     return sessionId ? [sessionId] : [];
 }
 
+function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<string, unknown>> {
+    const cachedStatus = readObjectRecord(node?.cachedStatus);
+    const activeSession = readObjectRecord(cachedStatus.activeSession);
+    const fallbackSession = Object.keys(activeSession).length
+        ? activeSession
+        : readObjectRecord(node?.activeSession ?? node?.active_session);
+    const sessionId = readStringValue(
+        fallbackSession.id,
+        fallbackSession.sessionId,
+        fallbackSession.session_id,
+        node?.activeSessionId,
+        node?.active_session_id,
+        node?.sessionId,
+        node?.session_id,
+    );
+    if (!sessionId) return [];
+    return [{
+        sessionId,
+        providerType: readStringValue(
+            fallbackSession.providerType,
+            fallbackSession.provider_type,
+            fallbackSession.cliType,
+            fallbackSession.cli_type,
+            fallbackSession.provider,
+            node?.providerType,
+            node?.provider_type,
+        ),
+        state: readStringValue(fallbackSession.status, fallbackSession.state, fallbackSession.lifecycle),
+        lifecycle: readStringValue(fallbackSession.lifecycle),
+        title: readStringValue(fallbackSession.title, fallbackSession.displayName, fallbackSession.display_name) ?? null,
+        workspace: readStringValue(fallbackSession.workspace, node?.workspace) ?? null,
+        lastActivityAt: readStringValue(fallbackSession.lastActivityAt, fallbackSession.last_activity_at) ?? null,
+        recoveryState: readStringValue(fallbackSession.recoveryState, fallbackSession.recovery_state) ?? null,
+        isCached: true,
+    }];
+}
+
+function readLiveMeshSessionState(record: any): string | undefined {
+    return readStringValue(
+        record?.meta?.sessionStatus,
+        record?.meta?.status,
+        record?.meta?.providerStatus,
+        record?.status,
+        record?.state,
+        record?.lifecycle,
+    );
+}
+
+function toIsoTimestamp(value: unknown): string | null {
+    if (typeof value === 'number' && Number.isFinite(value)) return new Date(value).toISOString();
+    const stringValue = readStringValue(value);
+    return stringValue || null;
+}
+
+function summarizeMeshSessionRecord(record: any): Record<string, unknown> {
+    return {
+        sessionId: readStringValue(record?.sessionId) || 'unknown',
+        providerType: readStringValue(record?.providerType),
+        state: readLiveMeshSessionState(record),
+        lifecycle: readStringValue(record?.lifecycle),
+        surfaceKind: getSessionHostSurfaceKind(record as any),
+        recoveryState: readStringValue(record?.meta?.runtimeRecoveryState) ?? null,
+        workspace: readStringValue(record?.workspace) ?? null,
+        title: readStringValue(record?.displayName, record?.workspaceLabel) ?? null,
+        lastActivityAt: toIsoTimestamp(record?.updatedAt ?? record?.lastActivityAt ?? record?.last_activity_at),
+        isCached: false,
+    };
+}
+
 function applyCachedInlineMeshNodeStatus(status: Record<string, unknown>, node: any): boolean {
     const cachedStatus = readObjectRecord(node?.cachedStatus);
     const git = buildCachedInlineMeshGitStatus(node);
     const error = readStringValue(cachedStatus.error, node?.error);
     const health = readStringValue(cachedStatus.health, node?.health);
     const machineStatus = readStringValue(cachedStatus.machineStatus, node?.machineStatus);
+    const lastSeenAt = toIsoTimestamp(cachedStatus.lastSeenAt ?? cachedStatus.last_seen_at ?? node?.lastSeenAt ?? node?.last_seen_at);
+    const updatedAt = toIsoTimestamp(cachedStatus.updatedAt ?? cachedStatus.updated_at ?? node?.updatedAt ?? node?.updated_at);
     const activeSessions = readCachedInlineMeshActiveSessions(node);
-    if (!git && !error && !health && !machineStatus && activeSessions.length === 0) return false;
+    const activeSessionDetails = readCachedInlineMeshActiveSessionDetails(node);
+    if (!git && !error && !health && !machineStatus && !lastSeenAt && !updatedAt && activeSessions.length === 0) return false;
     if (git) status.git = git;
     if (error) status.error = error;
+    if (machineStatus) status.machineStatus = machineStatus;
+    if (lastSeenAt) status.lastSeenAt = lastSeenAt;
+    if (updatedAt) status.updatedAt = updatedAt;
     if (activeSessions.length > 0) status.activeSessions = activeSessions;
+    if (activeSessionDetails.length > 0) status.activeSessionDetails = activeSessionDetails;
     if (health) {
         status.health = health;
         return true;
@@ -278,7 +354,7 @@ function applyCachedInlineMeshNodeStatus(status: Record<string, unknown>, node:
         status.health = deriveMeshNodeHealthFromGit(git);
         return true;
     }
-    return activeSessions.length > 0 || !!machineStatus;
+    return activeSessions.length > 0 || !!machineStatus || !!lastSeenAt || !!updatedAt;
 }
 
 async function resolveProviderTypeFromPriority(args: {
@@ -698,6 +774,8 @@ export interface CommandRouterDeps {
     statusVersion?: string;
     /** Session host control plane */
     sessionHostControl?: SessionHostControlPlane | null;
+    /** Selected-coordinator mesh peer telemetry surface for target daemons, when supported by the runtime. */
+    getMeshPeerConnectionStatus?: (daemonId: string) => Record<string, unknown> | null;
 }
 
 export interface CommandRouterResult {
@@ -2955,36 +3033,91 @@ export class DaemonCommandRouter {
                         : [];
                     const liveMeshSessions = partitionSessionHostRecords(Array.isArray(sessionHostRecords) ? sessionHostRecords : []).liveRuntimes;
 
+                    const localMachineId = loadConfig().machineId || '';
+                    const inlineCoordinatorNodeId = meshRecord?.inline && Array.isArray(mesh.nodes)
+                        ? readStringValue((mesh.nodes[0] as any)?.id, (mesh.nodes[0] as any)?.nodeId)
+                        : undefined;
+                    const refreshedAt = new Date().toISOString();
                     const nodeStatuses = [];
-                    for (const node of mesh.nodes || []) {
+                    for (const [nodeIndex, node] of (mesh.nodes || []).entries()) {
+                        const nodeId = String(node.id || node.nodeId || '');
+                        const daemonId = readStringValue(node.daemonId);
+                        const providerPriority = readProviderPriorityFromPolicy(node.policy);
+                        const isSelfNode = Boolean(
+                            nodeId && inlineCoordinatorNodeId && nodeId === inlineCoordinatorNodeId,
+                        ) || Boolean(
+                            daemonId && (daemonId === localMachineId || daemonId === this.deps.statusInstanceId),
+                        ) || Boolean(meshRecord?.inline && nodeIndex === 0);
                         const status: Record<string, unknown> = {
-                            nodeId: node.id || node.nodeId,
+                            nodeId,
                             machineLabel: node.machineLabel || node.id || node.nodeId,
                             workspace: node.workspace,
                             repoRoot: node.repoRoot,
                             isLocalWorktree: node.isLocalWorktree,
                             worktreeBranch: node.worktreeBranch,
-                            daemonId: node.daemonId,
+                            daemonId,
                             machineId: node.machineId,
+                            machineStatus: node.machineStatus,
                             health: 'unknown',
                             providers: node.providers || [],
+                            providerPriority,
                             activeSessions: [],
+                            activeSessionDetails: [],
+                            launchReady: false,
                         };
-                        const nodeId = String(node.id || node.nodeId || '');
-                        const matchedLiveSessions = liveMeshSessions
-                            .filter((record) => this.sessionMatchesMeshNode(record, node, nodeId))
-                            .map((record: any) => typeof record?.sessionId === 'string' ? record.sessionId : '')
-                            .filter(Boolean);
-                        if (matchedLiveSessions.length > 0) {
-                            status.activeSessions = matchedLiveSessions;
+                        if (isSelfNode) {
+                            status.connection = {
+                                perspective: 'selected_coordinator',
+                                source: 'mesh_peer_status',
+                                state: 'self',
+                                transport: 'local',
+                                reported: true,
+                                reason: 'Selected coordinator daemon',
+                                lastStateChangeAt: refreshedAt,
+                            };
+                        } else if (daemonId) {
+                            const connection = this.deps.getMeshPeerConnectionStatus?.(daemonId);
+                            status.connection = connection ?? {
+                                perspective: 'selected_coordinator',
+                                source: 'not_reported',
+                                state: 'unknown',
+                                transport: 'unknown',
+                                reported: false,
+                                reason: 'No live mesh peer telemetry reported by the selected coordinator yet.',
+                            };
+                        } else {
+                            status.connection = {
+                                perspective: 'selected_coordinator',
+                                source: 'not_reported',
+                                state: 'unknown',
+                                transport: 'unknown',
+                                reported: false,
+                                reason: 'Node has no daemon id, so mesh transport cannot be reported from the selected coordinator.',
+                            };
+                        }
+                        const matchedLiveSessionRecords = liveMeshSessions
+                            .filter((record) => this.sessionMatchesMeshNode(record, node, nodeId));
+                        if (matchedLiveSessionRecords.length > 0) {
+                            const sessionIds = matchedLiveSessionRecords
+                                .map((record: any) => typeof record?.sessionId === 'string' ? record.sessionId : '')
+                                .filter(Boolean);
+                            const providerTypes = matchedLiveSessionRecords
+                                .map((record: any) => readStringValue(record?.providerType))
+                                .filter(Boolean) as string[];
+                            status.activeSessions = sessionIds;
+                            status.activeSessionDetails = matchedLiveSessionRecords.map(summarizeMeshSessionRecord);
+                            if (providerTypes.length > 0) {
+                                status.providers = Array.from(new Set([...(Array.isArray(status.providers) ? status.providers as string[] : []), ...providerTypes]));
+                            }
                         }
                         if (node.workspace && typeof node.workspace === 'string') {
                             if (!fs.existsSync(node.workspace as string) && applyCachedInlineMeshNodeStatus(status, node)) {
+                                status.launchReady = !!daemonId && (readStringValue(status.machineStatus) === 'online' || isSelfNode);
                                 nodeStatuses.push(status);
                                 continue;
                             }
                             try {
-                                const gitStatus = await getGitRepoStatus(node.workspace as string, { timeoutMs: 10_000 });
+                                const gitStatus = await getGitRepoStatus(node.workspace as string, { timeoutMs: 10_000, refreshUpstream: true });
                                 status.git = gitStatus;
                                 if (gitStatus.isGitRepo) {
                                     status.health = deriveMeshNodeHealthFromGit(gitStatus as unknown as Record<string, unknown>);
@@ -3000,6 +3133,7 @@ export class DaemonCommandRouter {
                         } else {
                             applyCachedInlineMeshNodeStatus(status, node);
                         }
+                        status.launchReady = !!daemonId && (readStringValue(status.machineStatus) === 'online' || isSelfNode);
                         nodeStatuses.push(status);
                     }
 
@@ -3009,6 +3143,7 @@ export class DaemonCommandRouter {
                         meshName: mesh.name,
                         repoIdentity: mesh.repoIdentity,
                         defaultBranch: mesh.defaultBranch,
+                        refreshedAt: new Date().toISOString(),
                         nodes: nodeStatuses,
                         queue: { tasks: queue, summary: queueSummary },
                         ledger: { entries: ledgerEntries, summary: ledgerSummary },

package/src/git/git-commands.ts

@@ -62,7 +62,7 @@ export interface GitPushResult extends GitRepoIdentity {
 }
 
 export interface GitCommandServices {
-  getStatus?: (params: { workspace: string }) => Promise<GitRepoStatus> | GitRepoStatus;
+  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;
   createSnapshot?: (params: {
@@ -171,7 +171,7 @@ const defaultSnapshotStore = createGitSnapshotStore({
 
 export function createDefaultGitCommandServices(): GitCommandServices {
   return {
-    getStatus: ({ workspace }) => getGitRepoStatus(workspace),
+    getStatus: ({ workspace, refreshUpstream }) => getGitRepoStatus(workspace, { refreshUpstream }),
     getDiffSummary: ({ workspace }) => getGitDiffSummary(workspace),
     getDiffFile: ({ workspace, path: filePath }) => getGitFileDiff(workspace, filePath),
     createSnapshot: ({ workspace, reason, sessionId, turnId }) => defaultSnapshotStore.create({
@@ -290,7 +290,7 @@ export async function handleGitCommand(
   switch (command) {
     case 'git_status': {
       if (!services.getStatus) return serviceNotImplemented(command);
-      const status = await runService(() => services.getStatus!({ workspace }));
+      const status = await runService(() => services.getStatus!({ workspace, refreshUpstream: optionalBoolean(args?.refreshUpstream) }));
       return 'success' in status ? status : { success: true, status };
     }
 

package/src/git/git-status.ts

@@ -1,12 +1,25 @@
-import type { GitRepoStatus, GitSubmoduleStatus } from './git-types.js';
+import type { GitRepoStatus, GitSubmoduleStatus, GitUpstreamFreshness } from './git-types.js';
 import { GitCommandError, resolveGitRepository, runGit } from './git-executor.js';
 
+type ResolvedGitRepo = { workspace: string; repoRoot: string | null; isGitRepo: boolean };
+
 export interface GitStatusOptions {
   timeoutMs?: number;
   /** When true, include submodule status in the result. Defaults to true. */
   includeSubmodules?: boolean;
   /** Optional filter to exclude specific submodule paths from status */
   submoduleIgnorePaths?: string[];
+  /**
+   * When true, refresh the tracked remote before trusting ahead/behind.
+   * Callers should opt into this only for convergence-critical surfaces.
+   */
+  refreshUpstream?: boolean;
+}
+
+interface GitUpstreamProbe {
+  upstreamStatus: GitUpstreamFreshness;
+  upstreamFetchedAt?: number;
+  upstreamFetchError?: string;
 }
 
 export async function getGitRepoStatus(
@@ -18,8 +31,16 @@ export async function getGitRepoStatus(
 
   try {
     const repo = await resolveGitRepository(workspace, options);
-    const statusOutput = await runGit(repo, ['status', '--porcelain=v2', '--branch'], options);
-    const parsed = parsePorcelainV2Status(statusOutput.stdout);
+    let parsed = await readPorcelainStatus(repo, options);
+    let upstreamProbe: GitUpstreamProbe = getInitialUpstreamProbe(parsed);
+
+    if (options.refreshUpstream) {
+      upstreamProbe = await refreshTrackedUpstream(repo, parsed, options);
+      if (upstreamProbe.upstreamStatus === 'fresh') {
+        parsed = await readPorcelainStatus(repo, options);
+      }
+    }
+
     const head = await readHead(repo, options);
     const stashCount = await readStashCount(repo, options);
 
@@ -36,6 +57,9 @@ export async function getGitRepoStatus(
       headCommit: head.commit,
       headMessage: head.message,
       upstream: parsed.upstream,
+      upstreamStatus: parsed.upstream ? upstreamProbe.upstreamStatus : 'no_upstream',
+      upstreamFetchedAt: upstreamProbe.upstreamFetchedAt,
+      upstreamFetchError: upstreamProbe.upstreamFetchError,
       ahead: parsed.ahead,
       behind: parsed.behind,
       staged: parsed.staged,
@@ -74,6 +98,72 @@ interface ParsedPorcelainStatus {
   conflictFiles: string[];
 }
 
+async function readPorcelainStatus(repo: ResolvedGitRepo, options: GitStatusOptions): Promise<ParsedPorcelainStatus> {
+  const statusOutput = await runGit(repo, ['status', '--porcelain=v2', '--branch'], options);
+  return parsePorcelainV2Status(statusOutput.stdout);
+}
+
+function getInitialUpstreamProbe(parsed: ParsedPorcelainStatus): GitUpstreamProbe {
+  return {
+    upstreamStatus: parsed.upstream ? 'unchecked' : 'no_upstream',
+  };
+}
+
+async function refreshTrackedUpstream(
+  repo: ResolvedGitRepo,
+  parsed: ParsedPorcelainStatus,
+  options: GitStatusOptions,
+): Promise<GitUpstreamProbe> {
+  if (!parsed.upstream || !parsed.branch) {
+    return { upstreamStatus: 'no_upstream' };
+  }
+
+  const remoteName = (await readBranchRemote(repo, parsed.branch, options)) ?? inferRemoteName(parsed.upstream);
+  if (!remoteName) {
+    return {
+      upstreamStatus: 'stale',
+      upstreamFetchError: `Unable to resolve remote for upstream '${parsed.upstream}'`,
+    };
+  }
+
+  try {
+    await runGit(repo, ['fetch', '--quiet', '--prune', '--no-tags', remoteName], options);
+    return {
+      upstreamStatus: 'fresh',
+      upstreamFetchedAt: Date.now(),
+    };
+  } catch (error) {
+    return {
+      upstreamStatus: 'stale',
+      upstreamFetchError: formatGitError(error),
+    };
+  }
+}
+
+async function readBranchRemote(repo: ResolvedGitRepo, branch: string, options: GitStatusOptions): Promise<string | null> {
+  try {
+    const result = await runGit(repo, ['config', '--get', `branch.${branch}.remote`], options);
+    return result.stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function inferRemoteName(upstream: string): string | null {
+  const [remoteName] = upstream.split('/');
+  return remoteName?.trim() || null;
+}
+
+function formatGitError(error: unknown): string {
+  if (error instanceof GitCommandError) {
+    return error.stderr || error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
 export function parsePorcelainV2Status(output: string): ParsedPorcelainStatus {
   const parsed: ParsedPorcelainStatus = {
     branch: null,
@@ -145,7 +235,7 @@ export function parsePorcelainV2Status(output: string): ParsedPorcelainStatus {
 }
 
 async function readHead(
-  repo: { workspace: string; repoRoot: string | null; isGitRepo: boolean },
+  repo: ResolvedGitRepo,
   options: GitStatusOptions,
 ): Promise<{ commit: string | null; message: string | null }> {
   try {
@@ -163,7 +253,7 @@ async function readHead(
 }
 
 async function readStashCount(
-  repo: { workspace: string; repoRoot: string | null; isGitRepo: boolean },
+  repo: ResolvedGitRepo,
   options: GitStatusOptions,
 ): Promise<number> {
   try {
@@ -187,6 +277,7 @@ function emptyStatus(workspace: string, lastCheckedAt: number, error: GitCommand
     headCommit: null,
     headMessage: null,
     upstream: null,
+    upstreamStatus: 'unavailable',
     ahead: 0,
     behind: 0,
     staged: 0,
@@ -206,7 +297,7 @@ function emptyStatus(workspace: string, lastCheckedAt: number, error: GitCommand
 // ─── Submodule Status ───────────────────────────
 
 async function getSubmoduleStatuses(
-  repo: { workspace: string; repoRoot: string | null; isGitRepo: boolean },
+  repo: ResolvedGitRepo,
   options: GitStatusOptions,
 ): Promise<GitSubmoduleStatus[]> {
   if (!repo.repoRoot) return [];

package/src/git/git-summary.ts

@@ -22,6 +22,9 @@ export function createGitCompactSummary(status: GitRepoStatus, diffSummary?: Git
     isGitRepo: status.isGitRepo,
     repoRoot: status.repoRoot,
     branch: status.branch,
+    upstreamStatus: status.upstreamStatus,
+    upstreamFetchedAt: status.upstreamFetchedAt,
+    upstreamFetchError: status.upstreamFetchError,
     dirty:
       status.staged > 0 ||
       status.modified > 0 ||

package/src/git/git-types.ts

@@ -40,11 +40,19 @@ export interface GitSubmoduleStatus {
   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;
@@ -134,6 +142,9 @@ export interface GitCompactSummary {
   isGitRepo: boolean;
   repoRoot: string | null;
   branch: string | null;
+  upstreamStatus: GitUpstreamFreshness;
+  upstreamFetchedAt?: number;
+  upstreamFetchError?: string;
   dirty: boolean;
   changedFiles: number;
   ahead: number;

package/src/index.ts

@@ -103,6 +103,14 @@ export type {
   LocalMeshNodeEntry,
   RepoMeshStatus,
   RepoMeshNodeStatus,
+  RepoMeshSessionStatus,
+  RepoMeshQueueTask,
+  RepoMeshQueueTaskStatus,
+  RepoMeshQueueSummary,
+  RepoMeshQueueStatus,
+  RepoMeshLedgerEntryStatus,
+  RepoMeshLedgerSummaryStatus,
+  RepoMeshLedgerStatus,
 } from './repo-mesh-types.js';
 export { DEFAULT_MESH_POLICY } from './repo-mesh-types.js';