Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

9.3 KB
Raw Blame
/**
 * Run-window git probes — the machine-checkable "what did this run leave
 * behind?" primitives (#3637).
 *
 * Two questions share one module: `did it
 * commit anything?` (the success criterion) and `what did it commit?` (the
 * accumulated diff the goal-fidelity review reads, #5994). The count uses
 * committer dates; the diff additionally excludes absorbed upstream history,
 * which dates alone cannot attribute to the run (#7690).
 *
 * `commitsSince` replaced the `[task-<id>]` commit-marker grep that used to live in
 * `agentRunTracking.js`: nothing in PortOS ever emitted that marker (the root
 * AGENTS.md requires human-readable commit subjects, so stamping an opaque task
 * id into every permanent commit was never an option), so the criterion was
 * unsatisfiable and scored every ordinary code-editing run a failure.
 *
 * Lives in `server/lib/` rather than under `services/agentTuiSpawning/` because
 * four separate agent paths — finalize's success-criteria evaluation, run
 * completion, runner completion, and orphan recovery — all need the same
 * answer, and none of them should have to reach into the TUI spawner for it.
 */

import { execGit } from './execGit.js';
import { resolveRemoteDefaultRef } from './primaryCheckoutGuard.js';

/**
 * Count commits reachable from HEAD whose COMMITTER date falls inside the run
 * window. `git rev-list --since` filters on committer date, which is what makes
 * this a usable "did this agent commit anything?" probe: commits the agent
 * created (or rewrote via rebase) are stamped now, while commits merely pulled
 * in from the remote keep the committer date they were written with — usually
 * before the run started, so they don't count as this agent's work.
 *
 * Non-throwing: a repo with no commits yet (`rev-list HEAD` fails), a missing,
 * detached, or broken checkout, or a git timeout all return 0.
 *
 * @param {string} workspacePath
 * @param {number} sinceMs - epoch ms marking the start of the run window
 * @returns {Promise<number>}
 */
export async function commitsSince(workspacePath, sinceMs) {
  if (!workspacePath || typeof workspacePath !== 'string') return 0;
  if (!Number.isFinite(sinceMs)) return 0;
  // `Number.isFinite` is not enough: a finite but out-of-range epoch (±1e15)
  // makes `toISOString()` throw RangeError, which would break this function's
  // non-throwing contract on a path that runs outside the request lifecycle.
  const since = new Date(sinceMs);
  if (Number.isNaN(since.getTime())) return 0;
  // `ignoreExitCode` so a repo with no HEAD resolves to a non-zero exit we can
  // read as "no commits" rather than rejecting — the house convention for
  // probe-shaped git calls (see git.js `isRepo` / `getRemote`).
  //
  // `timeout` preserves the retired marker-grep's 10s bound rather than taking
  // execGit's 30s default: this sits on the agent-completion path, and a git
  // wedged on a locked index or a slow network mount must not hold finalize open
  // for half a minute. A timeout rejects, which the catch below reads as 0.
  const result = await execGit(
    ['rev-list', '--count', `--since=${since.toISOString()}`, 'HEAD'],
    workspacePath,
    { ignoreExitCode: true, timeout: 10_000 },
  ).catch(() => null);
  if (!result || result.exitCode !== 0) return 0;
  const count = parseInt(result.stdout.trim(), 10);
  return Number.isFinite(count) ? count : 0;
}

/**
 * Coerce an agent record's `startedAt` to epoch ms, whichever shape it is in.
 * The in-memory agent maps stamp `Date.now()` (a NUMBER); the persisted record
 * stamps an ISO string. `Date.parse(1754696324000)` stringifies its argument and
 * returns NaN, so a bare `Date.parse` silently drops the numeric half — and a
 * dropped window means the commit probe is skipped for that whole spawn path.
 *
 * @returns {number} epoch ms, or NaN when there is no usable timestamp.
 */
export function toEpochMs(startedAt) {
  if (typeof startedAt === 'number') return startedAt;
  if (typeof startedAt === 'string') return Date.parse(startedAt);
  if (startedAt instanceof Date) return startedAt.getTime();
  return NaN;
}

/**
 * Boolean form of `commitsSince` — "did this run leave a commit behind?".
 * The shape every agent-completion path actually wants.
 */
export async function committedDuringRun(workspacePath, sinceMs) {
  return (await commitsSince(workspacePath, sinceMs)) > 0;
}

/**
 * The accumulated run-window diff, excluding history absorbed from the remote
 * default branch. Start with the newest pre-window commit and advance to the
 * remote-default merge base only when ancestry proves it is newer. Never use
 * the remote tip directly: it can include work this checkout has not absorbed.
 *
 * Non-throwing, like its siblings, and every failure is a REASON rather than an
 * empty diff. That distinction is the whole point: `''` would read as "this run
 * changed nothing", and a consumer gating on the diff must never confuse a git
 * that could not answer with a run that did nothing.
 *
 * No new persisted agent field is required: old records still supply startedAt.
 * Without a resolvable local remote-default ref, retain the time-based fallback.
 * This deliberately excludes agent work already reachable from that remote;
 * it is a review of the remaining change, not exact authorship attribution.
 * No fetch or other repository mutation is performed.
 *
 * `--before` resolves the initial base off COMMITTER date.
 * A repo whose entire history falls inside the window has no such base; that is
 * reported rather than diffed against the empty tree, because on a real
 * workspace it means the window is wrong, not that the run wrote the repo.
 *
 * @param {string} workspacePath
 * @param {number} sinceMs - epoch ms marking the start of the run window
 * @param {Object} [options]
 * @param {number} [options.maxChars] - hard cap on the returned text; the diff
 *   is truncated (and flagged) rather than returned whole, because the caller
 *   feeds it to a model with a fixed context window.
 * @param {string} [options.head] - pinned commit to review; defaults to HEAD
 * @returns {Promise<{diff: string|null, base: string|null, truncated: boolean, reason: string|null}>}
 */
export async function runWindowDiff(workspacePath, sinceMs, { maxChars = 60_000, head = 'HEAD' } = {}) {
  const decline = (reason) => ({ diff: null, base: null, truncated: false, reason });
  if (!workspacePath || typeof workspacePath !== 'string') return decline('no workspace path');
  if (!Number.isFinite(sinceMs)) return decline('no run window');
  const since = new Date(sinceMs);
  if (Number.isNaN(since.getTime())) return decline('unusable run window');

  const baseResult = await execGit(
    ['rev-list', '-n', '1', `--before=${since.toISOString()}`, head],
    workspacePath,
    { ignoreExitCode: true, timeout: 10_000 },
  ).catch(() => null);
  if (!baseResult || baseResult.exitCode !== 0) return decline('could not resolve the run window base commit');
  let base = baseResult.stdout.trim();
  if (!base) return decline('no commit predates the run window');

  const upstream = await resolveRemoteDefaultRef(workspacePath);
  if (upstream) {
    const mergeBaseResult = await execGit(
      ['merge-base', head, upstream.sha], workspacePath,
      { ignoreExitCode: true, timeout: 10_000 },
    ).catch(() => null);
    const upstreamBase = mergeBaseResult?.exitCode === 0 ? mergeBaseResult.stdout.trim() : null;
    if (!upstreamBase) return decline('could not resolve the absorbed upstream base');
    if (upstreamBase !== base) {
      const ancestry = await execGit(
        ['merge-base', '--is-ancestor', base, upstreamBase], workspacePath,
        { ignoreExitCode: true, timeout: 10_000 },
      ).catch(() => null);
      if (ancestry?.exitCode === 0) {
        base = upstreamBase;
      } else if (ancestry?.exitCode === 1) {
        // A later pre-window agent commit must stay excluded. If neither base
        // contains the other, one two-tree diff cannot exclude both histories.
        const reverse = await execGit(
          ['merge-base', '--is-ancestor', upstreamBase, base], workspacePath,
          { ignoreExitCode: true, timeout: 10_000 },
        ).catch(() => null);
        if (reverse?.exitCode !== 0) return decline('run window and upstream bases could not be ordered');
      } else {
        return decline('could not compare the run window and upstream bases');
      }
    }
  }

  // `--no-ext-diff` so a user's configured external difftool can't replace the
  // unified text (or block on a GUI); `--no-color` so escape codes don't reach
  // a model reading it as source.
  const diffResult = await execGit(
    ['diff', '--no-color', '--no-ext-diff', `${base}..${head}`],
    workspacePath,
    { ignoreExitCode: true, timeout: 30_000 },
  ).catch(() => null);
  if (!diffResult || diffResult.exitCode !== 0) return decline('could not read the run window diff');

  const diff = diffResult.stdout;
  if (!diff.trim()) return { diff: '', base, truncated: false, reason: null };
  // The cap bounds what the CALLER receives, marker included — a consumer that
  // re-checks the length against the same constant would otherwise reject the
  // very text this function handed it.
  if (diff.length > maxChars) {
    const marker = '\n…[diff truncated]';
    return { diff: `${diff.slice(0, Math.max(0, maxChars - marker.length))}${marker}`, base, truncated: true, reason: null };
  }
  return { diff, base, truncated: false, reason: null };
}