@adhdev/daemon-core 0.9.82-rc.19 → 0.9.82-rc.190

package/src/mesh/mesh-work-queue.ts

@@ -1,24 +1,76 @@
-import { existsSync, writeFileSync, readFileSync } from 'fs';
-import { join } from 'path';
 import { randomUUID } from 'crypto';
-import { getLedgerDir } from './mesh-ledger.js';
+import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
+import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
+import { BeadsDB } from './beads-db.js';
 
 export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed' | 'cancelled';
 export type MeshActiveTaskStatus = Extract<MeshTaskStatus, 'pending' | 'assigned'>;
 export type MeshHistoricalTaskStatus = Extract<MeshTaskStatus, 'completed' | 'failed' | 'cancelled'>;
+export type MeshTaskMode = 'code_change' | 'validation' | 'live_debug_readonly' | 'launch_app' | 'convergence';
 
 export const ACTIVE_MESH_QUEUE_STATUSES: MeshActiveTaskStatus[] = ['pending', 'assigned'];
 export const HISTORICAL_MESH_QUEUE_STATUSES: MeshHistoricalTaskStatus[] = ['completed', 'failed', 'cancelled'];
+export const MESH_TASK_MODES: MeshTaskMode[] = ['code_change', 'validation', 'live_debug_readonly', 'launch_app', 'convergence'];
+
+export interface MeshTaskModeValidationResult {
+    valid: boolean;
+    taskMode?: MeshTaskMode;
+    violations: string[];
+    allowedOperations?: string[];
+}
+
+const LIVE_DEBUG_READONLY_FORBIDDEN: Array<{ label: string; pattern: RegExp }> = [
+    { label: 'source_edit', pattern: /\b(edit|modify|patch|apply\s+patch|write\s+(?:to\s+)?(?:file|source)|overwrite|delete\s+file|remove\s+file|create\s+file|touch\s+file)\b/i },
+    { label: 'git_mutation', pattern: /\b(?:git\s+(?:add|commit|push|reset|rebase|clean|checkout|switch|merge|tag|restore|rm|mv|stash|worktree\s+(?:add|remove|move))|push\b)/i },
+    { label: 'checkpoint', pattern: /\b(checkpoint|mesh_checkpoint)\b/i },
+    { label: 'deploy_or_version_bump', pattern: /\b(deploy|wrangler\s+deploy|version[-\s]?bump|npm\s+version|release|npm\s+publish|yarn\s+publish|pnpm\s+publish)\b/i },
+    { label: 'destructive_shell', pattern: /\b(rm\s+-rf|mv\s+\S+\s+\S+|truncate\s|tee\s+\S+|sed\s+-i|shred\b)\b/i },
+    { label: 'package_install', pattern: /\b(npm\s+(?:install|i|add|link|uninstall|remove)|yarn\s+(?:add|remove|link)|pnpm\s+(?:add|remove|link)|pip\s+install|brew\s+install|apt\s+install|cargo\s+install)\b/i },
+    { label: 'container_mutation', pattern: /\b(docker\s+(?:build|run|exec|push|tag|rmi|rm|create|start|stop|kill)|kubectl\s+(?:apply|delete|patch|replace|create|scale))\b/i },
+];
+
+export function normalizeMeshTaskMode(value: unknown): MeshTaskMode | undefined {
+    if (typeof value !== 'string') return undefined;
+    const normalized = value.trim() as MeshTaskMode;
+    return (MESH_TASK_MODES as string[]).includes(normalized) ? normalized : undefined;
+}
+
+export function validateMeshTaskModeRequest(mode: unknown, message: string): MeshTaskModeValidationResult {
+    const taskMode = normalizeMeshTaskMode(mode);
+    if (!taskMode) {
+        return { valid: true, violations: [] };
+    }
+    if (taskMode !== 'live_debug_readonly') {
+        return { valid: true, taskMode, violations: [] };
+    }
+    const violations = LIVE_DEBUG_READONLY_FORBIDDEN
+        .filter(rule => rule.pattern.test(message || ''))
+        .map(rule => rule.label);
+    return {
+        valid: violations.length === 0,
+        taskMode,
+        violations,
+        allowedOperations: [
+            'process/log/window/port/session inspection',
+            'read-only filesystem listing/reading',
+            'status probes and keep-running handle reporting',
+            'diagnostic summaries without source edits, commits, checkpoints, pushes, deploys, resets, rebases, or destructive cleanups',
+        ],
+    };
+}
 
 export interface MeshWorkQueueEntry {
     id: string;
     meshId: string;
     message: string;
     status: MeshTaskStatus;
+    taskMode?: MeshTaskMode;
     /** 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 */
     targetSessionId?: string;
+    /** If specified, a node must expose all tags before it can claim the task. */
+    requiredTags?: string[];
     /** The node that actually claimed and is executing the task */
     assignedNodeId?: string;
     /** The session currently executing the task */
@@ -45,25 +97,63 @@ export interface MeshWorkQueueEntry {
     updatedAt: string;
 }
 
-function getQueuePath(meshId: string): string {
-    const safe = meshId.replace(/[^a-zA-Z0-9_-]/g, '_');
-    return join(getLedgerDir(), `${safe}.queue.json`);
+export interface MeshQueueMutationOptions {
+    ownerRole?: RepoMeshDaemonRole;
+}
+
+export function normalizeMeshCapabilityTags(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    const seen = new Set<string>();
+    return value
+        .map(tag => typeof tag === 'string' ? tag.trim() : '')
+        .filter(Boolean)
+        .filter(tag => {
+            if (seen.has(tag)) return false;
+            seen.add(tag);
+            return true;
+        });
+}
+
+function firstProviderPriority(policy: unknown): string | undefined {
+    const raw = policy && typeof policy === 'object' && !Array.isArray(policy)
+        ? (policy as Record<string, unknown>).providerPriority
+        : undefined;
+    if (!Array.isArray(raw)) return undefined;
+    return raw.find(type => typeof type === 'string' && type.trim())?.trim();
+}
+
+export function buildMeshNodeCapabilityTags(
+    node: { capabilities?: unknown; policy?: unknown } | undefined,
+    providerType?: string,
+): string[] {
+    const provider = typeof providerType === 'string' && providerType.trim()
+        ? providerType.trim()
+        : firstProviderPriority(node?.policy);
+    return normalizeMeshCapabilityTags([
+        ...(Array.isArray(node?.capabilities) ? node.capabilities : []),
+        `os=${process.platform}`,
+        `arch=${process.arch}`,
+        ...(provider ? [`provider=${provider}`] : []),
+    ]);
+}
+
+export function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags: unknown): boolean {
+    const required = normalizeMeshCapabilityTags(requiredTags);
+    if (required.length === 0) return true;
+    const available = new Set(normalizeMeshCapabilityTags(capabilityTags));
+    return required.every(tag => available.has(tag));
+}
+
+function withQueueLock<T>(_meshId: string, fn: () => T): T {
+    return BeadsDB.getInstance().transaction(fn);
 }
 
 function readQueue(meshId: string): MeshWorkQueueEntry[] {
-    const path = getQueuePath(meshId);
-    if (!existsSync(path)) return [];
-    try {
-        const content = readFileSync(path, 'utf-8');
-        return JSON.parse(content) as MeshWorkQueueEntry[];
-    } catch {
-        return [];
-    }
+    return BeadsDB.getInstance().getQueueEntries(meshId);
 }
 
 function writeQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
-    const path = getQueuePath(meshId);
-    writeFileSync(path, JSON.stringify(queue, null, 2), 'utf-8');
+    BeadsDB.getInstance().replaceQueue(meshId, queue);
 }
 
 /**
@@ -72,21 +162,26 @@ function writeQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
 export function enqueueTask(
     meshId: string,
     message: string,
-    opts?: { targetNodeId?: string; targetSessionId?: string }
+    opts?: { targetNodeId?: string; targetSessionId?: string; taskMode?: MeshTaskMode | string; requiredTags?: string[] } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry {
-    const queue = readQueue(meshId);
+    requireMeshHostQueueOwner(opts);
+    const modeValidation = validateMeshTaskModeRequest(opts?.taskMode, message);
+    if (!modeValidation.valid) {
+        throw new Error(`live_debug_readonly_guardrail_violation: forbidden operations (${modeValidation.violations.join(', ')})`);
+    }
     const entry: MeshWorkQueueEntry = {
         id: randomUUID(),
         meshId,
         message,
         status: 'pending',
+        taskMode: modeValidation.taskMode,
         targetNodeId: opts?.targetNodeId,
         targetSessionId: opts?.targetSessionId,
+        requiredTags: normalizeMeshCapabilityTags(opts?.requiredTags),
         createdAt: new Date().toISOString(),
         updatedAt: new Date().toISOString(),
     };
-    queue.push(entry);
-    writeQueue(meshId, queue);
+    BeadsDB.getInstance().insertQueueEntry(entry);
     return entry;
 }
 
@@ -94,51 +189,18 @@ export function enqueueTask(
  * Get all tasks in the queue, optionally filtered by status.
  */
 export function getQueue(meshId: string, opts?: { status?: MeshTaskStatus[] }): MeshWorkQueueEntry[] {
-    let queue = readQueue(meshId);
-    if (opts?.status?.length) {
-        const statuses = new Set(opts.status);
-        queue = queue.filter(q => statuses.has(q.status));
-    }
-    return queue;
+    return BeadsDB.getInstance().getQueueEntries(meshId, opts?.status?.length ? opts.status : undefined);
+}
+
+export function getMeshQueueRevision(meshId: string): string {
+    return BeadsDB.getInstance().getQueueRevision(meshId);
 }
 
 /**
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
-export function claimNextTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-
-    // A worker must finish or fail its current queued assignment before it can
-    // claim another one. maxParallelTasks limits total mesh concurrency; it is
-    // not permission for one node/session to accumulate multiple assigned items.
-    const hasActiveAssignment = queue.some(q => q.status === 'assigned' && (
-        q.assignedSessionId === sessionId || q.assignedNodeId === nodeId
-    ));
-    if (hasActiveAssignment) return null;
-    
-    // Find highest priority task:
-    // 1. Pending tasks explicitly targeted at this runtime session
-    // 2. Pending tasks explicitly targeted at this node (but not another session)
-    // 3. Pending tasks with no target node/session
-    let targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetSessionId === sessionId);
-    if (targetIdx === -1) {
-        targetIdx = queue.findIndex(q => q.status === 'pending' && q.targetNodeId === nodeId && !q.targetSessionId);
-    }
-    if (targetIdx === -1) {
-        targetIdx = queue.findIndex(q => q.status === 'pending' && !q.targetNodeId && !q.targetSessionId);
-    }
-
-    if (targetIdx === -1) return null;
-
-    const entry = queue[targetIdx];
-    entry.status = 'assigned';
-    entry.assignedNodeId = nodeId;
-    entry.assignedSessionId = sessionId;
-    entry.dispatchTimestamp = new Date().toISOString();
-    entry.updatedAt = new Date().toISOString();
-
-    writeQueue(meshId, queue);
-    return entry;
+export function claimNextTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[]): MeshWorkQueueEntry | null {
+    return BeadsDB.getInstance().claimNextQueueTask(meshId, nodeId, sessionId, capabilityTags);
 }
 
 /**
@@ -149,15 +211,16 @@ export function updateTaskStatus(
     meshId: string,
     taskId: string,
     status: MeshTaskStatus,
+    opts?: MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-
-    queue[idx].status = status;
-    queue[idx].updatedAt = new Date().toISOString();
-    writeQueue(meshId, queue);
-    return queue[idx];
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
+        entry.status = status;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
+    });
 }
 
 export function recordTaskAutoLaunch(
@@ -165,17 +228,14 @@ export function recordTaskAutoLaunch(
     taskId: string,
     autoLaunch: Omit<NonNullable<MeshWorkQueueEntry['autoLaunch']>, 'updatedAt'>,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-    const now = new Date().toISOString();
-    queue[idx].autoLaunch = {
-        ...autoLaunch,
-        updatedAt: now,
-    };
-    queue[idx].updatedAt = now;
-    writeQueue(meshId, queue);
-    return queue[idx];
+    return withQueueLock(meshId, () => {
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
+        const now = new Date().toISOString();
+        entry.autoLaunch = { ...autoLaunch, updatedAt: now };
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
+    });
 }
 
 /**
@@ -184,19 +244,19 @@ export function recordTaskAutoLaunch(
 export function cancelTask(
     meshId: string,
     taskId: string,
-    opts?: { reason?: string },
+    opts?: { reason?: string } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-
-    const now = new Date().toISOString();
-    queue[idx].status = 'cancelled';
-    queue[idx].updatedAt = now;
-    queue[idx].cancelledAt = now;
-    if (opts?.reason) queue[idx].cancelReason = opts.reason;
-    writeQueue(meshId, queue);
-    return queue[idx];
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
+        const now = new Date().toISOString();
+        entry.status = 'cancelled';
+        entry.cancelledAt = now;
+        if (opts?.reason) entry.cancelReason = opts.reason;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
+    });
 }
 
 /**
@@ -212,29 +272,27 @@ export function requeueTask(
         targetSessionId?: string;
         clearTargetNode?: boolean;
         clearTargetSession?: boolean;
-    },
+    } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    const idx = queue.findIndex(q => q.id === taskId);
-    if (idx === -1) return null;
-
-    const entry = queue[idx];
-    const now = new Date().toISOString();
-    entry.status = 'pending';
-    delete entry.assignedNodeId;
-    delete entry.assignedSessionId;
-    delete entry.cancelledAt;
-    delete entry.cancelReason;
-    if (opts?.clearTargetNode) delete entry.targetNodeId;
-    if (typeof opts?.targetNodeId === 'string') entry.targetNodeId = opts.targetNodeId;
-    if (opts?.clearTargetSession !== false) delete entry.targetSessionId;
-    if (typeof opts?.targetSessionId === 'string') entry.targetSessionId = opts.targetSessionId;
-    entry.updatedAt = now;
-    entry.requeuedAt = now;
-    entry.requeueCount = (entry.requeueCount || 0) + 1;
-    if (opts?.reason) entry.requeueReason = opts.reason;
-    writeQueue(meshId, queue);
-    return entry;
+    requireMeshHostQueueOwner(opts);
+    return withQueueLock(meshId, () => {
+        const entry = BeadsDB.getInstance().findQueueEntryById(meshId, taskId);
+        if (!entry) return null;
+        entry.status = 'pending';
+        delete entry.assignedNodeId;
+        delete entry.assignedSessionId;
+        delete entry.cancelledAt;
+        delete entry.cancelReason;
+        if (opts?.clearTargetNode) delete entry.targetNodeId;
+        if (typeof opts?.targetNodeId === 'string') entry.targetNodeId = opts.targetNodeId;
+        if (opts?.clearTargetSession !== false) delete entry.targetSessionId;
+        if (typeof opts?.targetSessionId === 'string') entry.targetSessionId = opts.targetSessionId;
+        entry.requeuedAt = new Date().toISOString();
+        entry.requeueCount = (entry.requeueCount || 0) + 1;
+        if (opts?.reason) entry.requeueReason = opts.reason;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
+    });
 }
 
 /**
@@ -244,29 +302,16 @@ export function updateSessionTaskStatus(
     meshId: string,
     sessionId: string,
     status: MeshTaskStatus,
+    opts?: { occurredAt?: string },
 ): MeshWorkQueueEntry | null {
-    const queue = readQueue(meshId);
-    // Collect all assigned tasks for this session, then pick the one with the
-    // most recent dispatchTimestamp (or updatedAt fallback for legacy entries).
-    // This prevents completing the wrong task when multiple tasks were assigned
-    // to the same session in rapid succession.
-    let bestIdx = -1;
-    let bestTime = 0;
-    for (let i = queue.length - 1; i >= 0; i--) {
-        if (queue[i].assignedSessionId === sessionId && queue[i].status === 'assigned') {
-            const time = new Date(queue[i].dispatchTimestamp || queue[i].updatedAt).getTime();
-            if (time > bestTime) {
-                bestTime = time;
-                bestIdx = i;
-            }
-        }
-    }
-    if (bestIdx === -1) return null;
-
-    queue[bestIdx].status = status;
-    queue[bestIdx].updatedAt = new Date().toISOString();
-    writeQueue(meshId, queue);
-    return queue[bestIdx];
+    return withQueueLock(meshId, () => {
+        const occurredAtIso = opts?.occurredAt ? new Date(opts.occurredAt).toISOString() : undefined;
+        const entry = BeadsDB.getInstance().findAssignedBySession(meshId, sessionId, occurredAtIso);
+        if (!entry) return null;
+        entry.status = status;
+        BeadsDB.getInstance().updateQueueEntry(entry);
+        return entry;
+    });
 }
 
 export interface MeshWorkQueueStats {
@@ -294,14 +339,16 @@ export interface MeshWorkQueueStats {
  * Return aggregate queue statistics for the given mesh.
  */
 export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
-    const queue = readQueue(meshId);
-    const pending = queue.filter(q => q.status === 'pending').length;
-    const assigned = queue.filter(q => q.status === 'assigned').length;
-    const completed = queue.filter(q => q.status === 'completed').length;
-    const failed = queue.filter(q => q.status === 'failed').length;
-    const cancelled = queue.filter(q => q.status === 'cancelled').length;
+    const rows = BeadsDB.getInstance().getQueueStatsByStatus(meshId);
+    const counts: Record<string, number> = {};
+    for (const r of rows) counts[r.status] = r.count;
+    const pending = counts['pending'] ?? 0;
+    const assigned = counts['assigned'] ?? 0;
+    const completed = counts['completed'] ?? 0;
+    const failed = counts['failed'] ?? 0;
+    const cancelled = counts['cancelled'] ?? 0;
     return {
-        total: queue.length,
+        total: pending + assigned + completed + failed + cancelled,
         active: pending + assigned,
         historical: completed + failed + cancelled,
         pending,
@@ -309,22 +356,83 @@ export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
         completed,
         failed,
         cancelled,
-        activeCounts: {
-            pending,
-            assigned,
-        },
-        historicalCounts: {
-            completed,
-            failed,
-            cancelled,
-        },
-        activeAssignments: queue
-            .filter(q => q.status === 'assigned')
-            .map(q => ({
-                id: q.id,
-                nodeId: q.assignedNodeId,
-                sessionId: q.assignedSessionId,
-                message: q.message,
-            })),
+        activeCounts: { pending, assigned },
+        historicalCounts: { completed, failed, cancelled },
+        activeAssignments: BeadsDB.getInstance().getActiveAssignmentDetails(meshId),
     };
 }
+
+export function __replaceMeshQueueForTests(meshId: string, queue: MeshWorkQueueEntry[]): void {
+    BeadsDB.getInstance().transaction(() => {
+        BeadsDB.getInstance().replaceQueue(meshId, queue);
+    });
+}
+
+export function __clearMeshQueueForTests(meshId: string): void {
+    BeadsDB.getInstance().deleteQueue(meshId);
+}
+
+export function __clearDirectDispatchesForTests(meshId: string): void {
+    BeadsDB.getInstance().deleteDirectDispatches(meshId);
+}
+
+export function __resetBeadsDBForTests(): void {
+    BeadsDB.resetForTests();
+}
+
+// ── Direct Dispatch Tracking ─────────────────────────────────────────────────
+// Persists direct (non-queue) task dispatches so buildMeshActiveWork can read
+// active work from BeadsDB instead of scanning ledger JSONL entries.
+
+export type DirectDispatchRecord = ReturnType<BeadsDB['getActiveDirectDispatches']>[number];
+
+export function insertDirectDispatch(
+    meshId: string,
+    data: {
+        taskId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        message: string;
+        taskMode?: string;
+        via: string;
+        dispatchedToIdleSession?: boolean;
+        dispatchedAt: string;
+    },
+): void {
+    try {
+        BeadsDB.getInstance().insertDirectDispatch({ ...data, meshId });
+    } catch (e: any) {
+        process.stderr.write(`[adhdev-mesh] insertDirectDispatch failed for task ${data.taskId}: ${e?.message || e}\n`);
+    }
+}
+
+export function getActiveDirectDispatches(meshId: string): DirectDispatchRecord[] {
+    try {
+        return BeadsDB.getInstance().getActiveDirectDispatches(meshId);
+    } catch {
+        return [];
+    }
+}
+
+export function updateDirectDispatchStatus(
+    meshId: string,
+    sessionId: string,
+    status: 'acked' | 'completed' | 'failed' | 'stale',
+): void {
+    try {
+        BeadsDB.getInstance().updateDirectDispatchStatus(meshId, sessionId, status);
+    } catch { /* best-effort */ }
+}
+
+export function cleanupTerminalDirectDispatches(olderThanMs = 7 * 24 * 60 * 60_000): void {
+    try {
+        BeadsDB.getInstance().cleanupTerminalDirectDispatches(olderThanMs);
+    } catch { /* best-effort */ }
+}
+
+export function markStaleDirectDispatches(meshId: string, olderThanMs = 60 * 60_000): void {
+    try {
+        BeadsDB.getInstance().markStaleDirectDispatches(meshId, olderThanMs);
+    } catch { /* best-effort */ }
+}

package/src/mesh/preview-freshness.ts

@@ -0,0 +1,118 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export type PreviewFreshnessStatus = 'fresh' | 'stale' | 'unknown' | 'not_configured';
+
+export interface PreviewFreshness {
+    status: PreviewFreshnessStatus;
+    lastPreviewCommit: string | null;
+    currentMainCommit: string | null;
+    currentMainCommitSource: 'origin/main' | 'HEAD' | 'unknown';
+    recordPath: string;
+    lastDeployedAt?: string;
+    lastTarget?: string;
+    previewVersion?: string;
+    targets: Record<'npm' | 'server' | 'web', {
+        commit: string | null;
+        deployedAt?: string;
+        status: PreviewFreshnessStatus;
+    }>;
+    nextAction: string;
+}
+
+const PREVIEW_DEPLOY_RECORD = '.adhdev/preview-deploy.json';
+
+function runGit(repoRoot: string, args: readonly string[]): string {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+    } catch {
+        return '';
+    }
+}
+
+function readRecord(repoRoot: string): Record<string, unknown> | null {
+    const path = resolve(repoRoot, PREVIEW_DEPLOY_RECORD);
+    if (!existsSync(path)) return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed as Record<string, unknown>
+            : null;
+    } catch {
+        return null;
+    }
+}
+
+function normalizeCommit(value: unknown): string | null {
+    return typeof value === 'string' && /^[0-9a-f]{7,40}$/i.test(value.trim())
+        ? value.trim()
+        : null;
+}
+
+function readTargetFreshness(record: Record<string, unknown> | null, currentCommit: string | null): PreviewFreshness['targets'] {
+    const targets = record?.targets && typeof record.targets === 'object' && !Array.isArray(record.targets)
+        ? record.targets as Record<string, unknown>
+        : {};
+    const result = {} as PreviewFreshness['targets'];
+    for (const targetName of ['npm', 'server', 'web'] as const) {
+        const targetRecord = targets[targetName] && typeof targets[targetName] === 'object' && !Array.isArray(targets[targetName])
+            ? targets[targetName] as Record<string, unknown>
+            : {};
+        const commit = normalizeCommit(targetRecord.commit);
+        result[targetName] = {
+            commit,
+            deployedAt: typeof targetRecord.deployedAt === 'string' ? targetRecord.deployedAt : undefined,
+            status: commit && currentCommit ? (commit === currentCommit ? 'fresh' : 'stale') : 'unknown',
+        };
+    }
+    return result;
+}
+
+function readCurrentMainCommit(repoRoot: string): Pick<PreviewFreshness, 'currentMainCommit' | 'currentMainCommitSource'> {
+    const originMain = runGit(repoRoot, ['rev-parse', '--verify', 'origin/main^{commit}']);
+    if (originMain) {
+        return { currentMainCommit: originMain, currentMainCommitSource: 'origin/main' };
+    }
+    const head = runGit(repoRoot, ['rev-parse', '--verify', 'HEAD']);
+    if (head) {
+        return { currentMainCommit: head, currentMainCommitSource: 'HEAD' };
+    }
+    return { currentMainCommit: null, currentMainCommitSource: 'unknown' };
+}
+
+export function buildPreviewFreshness(repoRoot: string): PreviewFreshness {
+    const current = readCurrentMainCommit(repoRoot);
+    const record = readRecord(repoRoot);
+    const lastPreviewCommit = normalizeCommit(record?.lastPreviewCommit);
+    const targets = readTargetFreshness(record, current.currentMainCommit);
+    let status: PreviewFreshnessStatus = 'unknown';
+    let nextAction = 'Run npm run deploy:preview from the current main commit, then smoke preview.';
+
+    if (lastPreviewCommit && current.currentMainCommit) {
+        status = lastPreviewCommit === current.currentMainCommit ? 'fresh' : 'stale';
+        nextAction = status === 'fresh'
+            ? 'No preview deploy action needed.'
+            : 'Run npm run deploy:preview from origin/main, then smoke preview.';
+    } else if (!current.currentMainCommit) {
+        nextAction = 'Resolve the current main commit before judging preview freshness.';
+    }
+
+    return {
+        status,
+        lastPreviewCommit,
+        currentMainCommit: current.currentMainCommit,
+        currentMainCommitSource: current.currentMainCommitSource,
+        recordPath: PREVIEW_DEPLOY_RECORD,
+        lastDeployedAt: typeof record?.updatedAt === 'string' ? record.updatedAt : undefined,
+        lastTarget: typeof record?.target === 'string' ? record.target : undefined,
+        previewVersion: typeof record?.previewVersion === 'string' ? record.previewVersion : undefined,
+        targets,
+        nextAction,
+    };
+}