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

35.2 KB
Raw Blame
/**
 * `.quality.json` — the numeric quality snapshot a repository carries at its
 * root. Writers emit canonical file schema v2 (`appQualitySnapshotFormat.js`).
 * That file is not the peer wire payload: federation stays on
 * `PORTOS_SCHEMA_VERSIONS.appQuality` v1.
 *
 * PortOS's own checkout is not special: it is a managed app like any other, so
 * its release snapshot is this same file, written by this same publisher, under
 * this same per-app `publishQualitySnapshot` toggle.
 *
 * The filename is deliberately generic and PortOS-agnostic: it is generated
 * data any tool can read, not PortOS configuration. Publishing is opt-in per app
 * (`publishQualitySnapshot`), commits only this one path on a dedicated branch,
 * and merges its pull request immediately so the live checkout never
 * diverges from origin and repos that block pushes to the default branch still
 * receive the file. Repositories advertising `pregate:merged` first validate
 * the combined tree and pin the immediate merge to that exact head and base.
 * A guarded refusal retains its checkout and evidence for a later publish cycle;
 * generic repositories retain their existing merge-on-green fallback.
 * The immediate merge is the one step that advances the default branch, so it
 * runs under this install's repository merge admission (`cosMergeAdmission.js`)
 * like every other final merge. A busy lease leaves the PR recoverable for
 * a later admitted attempt. Reads never write. A v1 file or historical
 * `quality-snapshot.json` is explicit legacy input. Before publication, live
 * review ownership and non-snapshot branch changes defer replacement; the push
 * lease pins only the exact head this invocation inspected.
 */
import { basename, join } from 'node:path';
import { tmpdir } from 'node:os';
import { mkdtemp, readFile, rm } from 'node:fs/promises';
import { atomicWrite } from '../lib/fileCore.js';
import {
  APP_QUALITY_LEGACY_SNAPSHOT_FILENAME,
  APP_QUALITY_SNAPSHOT_FILENAME,
  classifyQualitySnapshot,
  serializeQualitySnapshot,
} from './appQualitySnapshotFormat.js';

export { APP_QUALITY_SNAPSHOT_FILENAME };
export const APP_QUALITY_SNAPSHOT_MAX_BYTES = 4 * 1024 * 1024;
export const QUALITY_SNAPSHOT_BRANCH = 'portos/quality-snapshot';

const snapshotPath = (repoPath, filename = APP_QUALITY_SNAPSHOT_FILENAME) => join(repoPath, filename);
// 'future-categories' is readable (known rows are used) but was written by a
// newer install whose categories this one would drop on rewrite.
const REWRITE_BLOCKED = new Set(['future', 'future-categories', 'unrecognized', 'malformed', 'oversize', 'unreadable']);

const QUALITY_PR_TITLE = 'chore: publish quality snapshot';
const QUALITY_PR_BODY = `## Summary
Update the repository \`.quality.json\` numeric quality snapshot generated by PortOS.

## Test plan
- Generated numeric measurements only; no application code changes
- No code review required; repository structural guards and merge policy still apply
`;

async function readSnapshotEntry(repoPath, filename, deps = {}) {
  try {
    const body = await (deps.readFile || readFile)(join(repoPath, filename), 'utf8');
    if (typeof body !== 'string') return { status: 'absent' };
    if (Buffer.byteLength(body) > APP_QUALITY_SNAPSHOT_MAX_BYTES) return { status: 'oversize' };
    return { status: 'text', body };
  } catch (error) {
    return { status: error?.code === 'ENOENT' ? 'absent' : 'unreadable' };
  }
}

/** Parsed `.quality.json`, or null for every failure mode. Never throws.
 *  Legacy filename resolution lives in `readStoredQualitySnapshot`. */
export async function readAppQualitySnapshotFile(repoPath, deps = {}) {
  if (!repoPath) return null;
  const entry = await readSnapshotEntry(repoPath, APP_QUALITY_SNAPSHOT_FILENAME, deps);
  if (entry.status !== 'text') return null;
  // Inline rather than jsonIo.safeJSONParse: routes/apps/crud.js reaches this
  // module statically, so a lib import here lands in the suite import budget.
  const parsed = await Promise.resolve().then(() => JSON.parse(entry.body)).catch(() => null);
  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
}

async function readClassified(repoPath, filename, deps) {
  if (!repoPath) return { status: 'absent' };
  let body;
  try {
    body = await (deps.readFile || readFile)(snapshotPath(repoPath, filename), 'utf8');
  } catch (error) {
    return { status: error?.code === 'ENOENT' ? 'absent' : 'unreadable', filename };
  }
  if (typeof body !== 'string') return { status: 'absent' };
  if (Buffer.byteLength(body) > APP_QUALITY_SNAPSHOT_MAX_BYTES) return { status: 'oversize' };
  return { body, filename, ...classifyQualitySnapshot(body) };
}

/**
 * `.quality.json` when it exists, otherwise the historical `quality-snapshot.json`.
 * A present canonical file is never replaced by the legacy name. Never writes.
 */
export async function readStoredQualitySnapshot(repoPath, deps = {}) {
  const primary = await readClassified(repoPath, APP_QUALITY_SNAPSHOT_FILENAME, deps);
  if (primary.status !== 'absent') return primary;
  const legacy = await readClassified(repoPath, APP_QUALITY_LEGACY_SNAPSHOT_FILENAME, deps);
  return legacy.status === 'absent' ? { status: 'absent', filename: null } : legacy;
}

function skipped(app, reason) {
  console.log(`📊 Quality snapshot skipped for app ${app?.id}: ${reason}`);
  return { published: false, reason, path: APP_QUALITY_SNAPSHOT_FILENAME };
}

// One tail per checkout. Several audit categories for the same app finish
// together, and read-modify-write against `.quality.json` plus `.git/index` is
// not re-entrant — the second run must see the first run's bytes (and answer
// `no-changes`) rather than race it. Keyed by repo path, not app id: two app
// records can point at one checkout. Same shape as `queueSeriesIssuesWrite`.
const publishTails = new Map();
// Bytes the in-process publisher last landed (or confirmed on origin) for a
// checkout. Origin/default still holds the previous file until the PR merges,
// so the next audit in this process must not open a duplicate PR of the same
// snapshot.
const lastPublishedBody = new Map();

export function __resetQualitySnapshotPublishState() {
  publishTails.clear();
  lastPublishedBody.clear();
}

function enqueue(repoPath, task) {
  const run = (publishTails.get(repoPath) ?? Promise.resolve()).then(task, task);
  // The queued value never rejects, so one failed publish cannot poison the tail.
  const queued = run.then(() => {}, () => {});
  publishTails.set(repoPath, queued);
  // Only the newest tail owns the slot; an older one settling must not evict it.
  queued.then(() => { if (publishTails.get(repoPath) === queued) publishTails.delete(repoPath); });
  return run;
}

/**
 * Rebuild the app's numeric snapshot and land it as canonical v2 `.quality.json`
 * through an immediately-merged pull request. An empty snapshot never overwrites a
 * populated file. A v1 file is rewritten when current evidence exists. An
 * already-canonical v2 snapshot with the same records never reaches git.
 */
export async function publishAppQualitySnapshot(app, deps = {}) {
  if (!app?.repoPath) return skipped(app, 'no-repo-path');
  return enqueue(app.repoPath, () => publishNow(app, deps));
}

/**
 * Convert a v1 `.quality.json` or historical `quality-snapshot.json` to canonical
 * v2 using only the rows already in the file. Same isolated worktree and pull
 * request as publication. Does not read the database and does not invent rows.
 */
export async function migrateAppQualitySnapshot(app, deps = {}) {
  if (!app?.repoPath) return skipped(app, 'no-repo-path');
  return enqueue(app.repoPath, () => migrateNow(app, deps));
}

async function readGitSnapshot(git, repoPath, spec) {
  let result;
  try {
    result = await git.execGit(['show', spec], repoPath, {
      ignoreExitCode: true,
      maxBuffer: APP_QUALITY_SNAPSHOT_MAX_BYTES + 1,
    });
  } catch {
    return { status: 'unreadable' };
  }
  if (!result || result.exitCode !== 0) return { status: 'absent' };
  const body = result.stdout;
  if (typeof body !== 'string') return { status: 'absent' };
  if (Buffer.byteLength(body) > APP_QUALITY_SNAPSHOT_MAX_BYTES) return { status: 'oversize' };
  return { body, ...classifyQualitySnapshot(body) };
}

function untouched(app, status) {
  console.log(`📊 Quality snapshot left untouched for app ${app?.id}: ${status}`);
  return { published: false, reason: 'unsupported-format', path: APP_QUALITY_SNAPSHOT_FILENAME };
}

function sameSnapshot(stored, next) {
  if (!stored || stored.status === 'absent' || stored.status === 'unreadable') return false;
  if (stored.body === next) return true;
  return stored.status === 'v2' && stored.canonical === next;
}

async function repoBase(app, git) {
  if (!await git.isRepo(app.repoPath)) return { skip: skipped(app, 'not-a-repo') };
  if (!hasOrigin(await git.getRemote(app.repoPath))) return { skip: skipped(app, 'no-remote') };
  // A failed fetch cannot authorize replacing a branch from stale local refs.
  await git.fetchOrigin(app.repoPath, { prune: true });
  const defaultBranch = await git.getDefaultBranch(app.repoPath);
  if (!defaultBranch) return { skip: skipped(app, 'no-default-branch') };
  return { defaultBranch };
}

function hasOrigin(remote) {
  return Boolean(remote?.origin && (remote.origin.fetch || remote.origin.push || remote.origin['']));
}

const SNAPSHOT_WINDOW_DAYS = 30;

/**
 * Canonical text for the fresh evidence UNIONED with the rows already on the
 * default branch (same 30-day window). The fresh build only sees this install's
 * database plus whichever peers answer right now; a rewrite from that alone
 * silently deleted every row a peer (or an expired local row) had contributed
 * whenever the peer was offline. Fresh rows still win a same-day collision.
 */
function mergeWithPublished(snapshot, onDefault, now) {
  const cutoff = new Date(now - SNAPSHOT_WINDOW_DAYS * 86400000).toISOString().slice(0, 10);
  const kept = (onDefault.records || []).filter(record => record.assessedAt.slice(0, 10) >= cutoff);
  const fresh = snapshot.measurements.map(({ measurementId, assessedAt, report }) => ({ ...report, assessedAt, measurementId }));
  return serializeQualitySnapshot(snapshot.repository, [...kept, ...fresh]);
}

async function publishNow(app, deps) {
  const git = deps.git || await import('./git.js');
  // Evidence is resolved before any remote check so a repo that is not a
  // checkout never builds, and an empty projection never reaches git.
  if (!await git.isRepo(app.repoPath)) return skipped(app, 'not-a-repo');
  const build = deps.buildQualitySnapshot || (await import('./appQualityFederation.js')).buildQualitySnapshot;
  const snapshot = await build(app, 30, deps);
  if (!snapshot?.measurements?.length) return skipped(app, 'no-evidence');

  const base = await repoBase(app, git);
  if (base.skip) return base.skip;
  const onDefault = await readGitSnapshot(
    git, app.repoPath, `origin/${base.defaultBranch}:${APP_QUALITY_SNAPSHOT_FILENAME}`,
  );
  if (REWRITE_BLOCKED.has(onDefault.status)) return untouched(app, onDefault.status);
  const next = mergeWithPublished(snapshot, onDefault, deps.now ?? Date.now());
  if (!next) return skipped(app, 'invalid-evidence');
  if (lastPublishedBody.get(app.repoPath) === next) return skipped(app, 'no-changes');
  // v1 bytes are a real migration even when the scores match. Only v2 that
  // already canonicalizes to `next` is "no changes".
  if (sameSnapshot(onDefault, next)) {
    lastPublishedBody.set(app.repoPath, next);
    return skipped(app, 'no-changes');
  }
  return landOrReuse(app, git, base.defaultBranch, deps, next, snapshot.measurements.length, { snapshot });
}

async function migrateNow(app, deps) {
  const git = deps.git || await import('./git.js');
  if (!await git.isRepo(app.repoPath)) return skipped(app, 'not-a-repo');
  const base = await repoBase(app, git);
  if (base.skip) return base.skip;

  let source = await readGitSnapshot(
    git, app.repoPath, `origin/${base.defaultBranch}:${APP_QUALITY_SNAPSHOT_FILENAME}`,
  );
  let removeLegacy = false;
  if (source.status === 'absent') {
    source = await readGitSnapshot(
      git, app.repoPath, `origin/${base.defaultBranch}:${APP_QUALITY_LEGACY_SNAPSHOT_FILENAME}`,
    );
    removeLegacy = source.status === 'v1' || source.status === 'v2';
  }
  if (source.status === 'absent') return skipped(app, 'no-legacy-file');
  if (REWRITE_BLOCKED.has(source.status)) return untouched(app, source.status);
  if (!source.records?.length || !source.canonical) return skipped(app, 'no-evidence');

  const next = source.canonical;
  if (!removeLegacy && source.status === 'v2' && source.body === next) {
    lastPublishedBody.set(app.repoPath, next);
    return skipped(app, 'no-changes');
  }
  if (lastPublishedBody.get(app.repoPath) === next && !removeLegacy) return skipped(app, 'no-changes');
  return landOrReuse(app, git, base.defaultBranch, deps, next, source.records.length, {
    removeLegacy,
    message: `chore: migrate quality snapshot to schema v2 (${source.records.length} measurements)`,
  });
}

// Remote rows can be newer than our initial default-branch read: another
// install may have queued a PR, or landed it while our push lost its lease.
// Keep those contributions while retaining full timestamps for local evidence
// (the compact file has already reduced timestamps to UTC days).
function mergeRemoteRows(next, stored, deps, options) {
  const candidate = classifyQualitySnapshot(next);
  if (options.snapshot) {
    return mergeWithPublished(options.snapshot, {
      records: [...candidate.records, ...(stored.records || [])],
    }, deps.now ?? Date.now());
  }
  // Explicit format migration does not expire historical rows.
  return serializeQualitySnapshot(candidate.repository, [...candidate.records, ...(stored.records || [])]);
}

async function publicationGuard(app, git, defaultBranch, deps) {
  const probe = deps.probePrForBranch || (await import('./prProbe.js')).probePrForBranch;
  const pr = await probe(app.repoPath, QUALITY_SNAPSHOT_BRANCH).catch(() => null);
  if (pr?.readable !== true || (pr.prState !== null && !['OPEN', 'MERGED', 'CLOSED'].includes(pr.prState))
    || (pr.prState === 'OPEN' && (!pr.prUrl || !pr.prNumber))) {
    return { reason: 'publish-pr-unreadable' };
  }
  const check = deps.checkSnapshotPublicationOwnership
    || (await import('./cosClaimOwnership.js')).checkSnapshotPublicationOwnership;
  const ownership = await check({ appId: app.id, branch: QUALITY_SNAPSHOT_BRANCH, prUrl: pr.prUrl }).catch(() => null);
  if (ownership?.admitted !== true) return { reason: ownership?.reason || 'ownership-unreadable' };
  const remote = await git.execGit(
    ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${QUALITY_SNAPSHOT_BRANCH}`],
    app.repoPath, { ignoreExitCode: true },
  ).catch(() => null);
  if (remote?.exitCode === 1) return { remoteSha: '' };
  const remoteSha = remote?.stdout?.trim();
  if (remote?.exitCode !== 0 || !/^[0-9a-f]{40,64}$/i.test(remoteSha || '')) return { reason: 'publish-branch-unreadable' };
  // Three-dot comparison excludes unrelated base movement, but retains every
  // change the remote branch would lose when rebuilt from the default branch.
  const diff = await git.execGit(
    ['diff', '--name-only', '-z', `origin/${defaultBranch}...${remoteSha}`, '--'],
    app.repoPath, { ignoreExitCode: true },
  ).catch(() => null);
  if (diff?.exitCode !== 0 || typeof diff.stdout !== 'string') return { reason: 'publish-branch-unreadable' };
  const allowed = new Set([APP_QUALITY_SNAPSHOT_FILENAME, APP_QUALITY_LEGACY_SNAPSHOT_FILENAME]);
  if (diff.stdout.split('\0').filter(Boolean).some(path => !allowed.has(path))) return { reason: 'non-snapshot-changes' };
  return { remoteSha };
}

function deferredPublication(app, reason) {
  return { ...skipped(app, reason), deferredPublication: true };
}

async function landOrReuse(app, git, defaultBranch, deps, next, count, options = {}) {
  const guard = await publicationGuard(app, git, defaultBranch, deps);
  if (guard.reason) return deferredPublication(app, guard.reason);
  const onBranch = await readGitSnapshot(
    git, app.repoPath, `origin/${QUALITY_SNAPSHOT_BRANCH}:${APP_QUALITY_SNAPSHOT_FILENAME}`,
  );
  const legacyOnBranch = options.removeLegacy
    ? await readGitSnapshot(git, app.repoPath, `origin/${QUALITY_SNAPSHOT_BRANCH}:${APP_QUALITY_LEGACY_SNAPSHOT_FILENAME}`)
    : { status: 'absent' };
  // The snapshot branch can hold a future file the default branch does not.
  // Force-pushing canonical v2 over it would discard a format we do not read.
  if (REWRITE_BLOCKED.has(onBranch.status) || REWRITE_BLOCKED.has(legacyOnBranch.status)) {
    return untouched(app, REWRITE_BLOCKED.has(onBranch.status) ? onBranch.status : legacyOnBranch.status);
  }
  next = mergeRemoteRows(next, onBranch, deps, options);
  if (!next) return skipped(app, 'invalid-evidence');
  if (sameSnapshot(onBranch, next) && legacyOnBranch.status === 'absent') {
    const reused = await reuseOpenSnapshotPr(app, git, defaultBranch, deps, guard.remoteSha);
    if (reused.published) rememberPublished(app, next, reused);
    return reused;
  }
  let result;
  try {
    result = await landSnapshotPr(app, {
      body: next, count, defaultBranch, git, deps,
      message: options.message, removeLegacy: options.removeLegacy === true, remoteSha: guard.remoteSha,
    });
  } catch (error) {
    // Another install can advance the shared publish branch after our ref read.
    // The lease must reject that push; rebuild from fresh refs exactly once.
    if (options.leaseRetry || error?.qualitySnapshotStaleLease !== true) throw error;
    await git.fetchOrigin(app.repoPath, { prune: true });
    const freshDefaultBranch = await git.getDefaultBranch(app.repoPath);
    if (!freshDefaultBranch) throw new Error('Quality snapshot lease retry: default branch unavailable');
    const onDefault = await readGitSnapshot(
      git, app.repoPath, `origin/${freshDefaultBranch}:${APP_QUALITY_SNAPSHOT_FILENAME}`,
    );
    if (REWRITE_BLOCKED.has(onDefault.status)) return untouched(app, onDefault.status);
    next = mergeRemoteRows(next, onDefault, deps, options);
    if (!next) return skipped(app, 'invalid-evidence');
    if (sameSnapshot(onDefault, next)) {
      lastPublishedBody.set(app.repoPath, next);
      return skipped(app, 'no-changes');
    }
    const probe = deps.probePrForBranch || (await import('./prProbe.js')).probePrForBranch;
    const pr = await probe(app.repoPath, QUALITY_SNAPSHOT_BRANCH);
    if (!pr?.readable || (pr.prState && !['OPEN', 'MERGED', 'CLOSED'].includes(String(pr.prState).toUpperCase()))) {
      throw new Error('Quality snapshot lease retry: publish PR state unavailable');
    }
    return landOrReuse(app, git, freshDefaultBranch, deps, next, count, {
      ...options, leaseRetry: true,
    });
  }
  rememberPublished(app, next, result);
  return result;
}

// A merge deferred by admission with nothing queued to land it (GitLab) must
// stay retryable: remembering the body would turn the next unchanged cycle
// into a 'no-changes' skip and strand the open PR.
function rememberPublished(app, body, result) {
  if (result.published !== true) return;
  if (result.deferredMerge === true && result.queuedMerge !== true) return;
  lastPublishedBody.set(app.repoPath, body);
}

async function reuseOpenSnapshotPr(app, git, defaultBranch, deps, expectedHeadSha) {
  const probe = deps.probePrForBranch
    || (await import('./prProbe.js')).probePrForBranch;
  const found = await probe(app.repoPath, QUALITY_SNAPSHOT_BRANCH);
  const prState = typeof found?.prState === 'string' ? found.prState.toUpperCase() : '';
  if (found?.prUrl && found?.prNumber && prState === 'OPEN') {
    const outcome = await mergeSnapshotPr(app, {
      url: found.prUrl, number: found.prNumber, cli: found.cli,
    }, deps, git, defaultBranch, { expectedHeadSha });
    console.log(`📊 Quality snapshot PR already open for app ${app.id}: ${found.prUrl}`);
    return {
      published: true, hash: null, path: APP_QUALITY_SNAPSHOT_FILENAME,
      prUrl: found.prUrl, prNumber: found.prNumber,
      ...mergeOutcomeFields(outcome),
    };
  }
  return landExistingBranchPr(app, git, defaultBranch, deps, expectedHeadSha);
}

async function landExistingBranchPr(app, git, defaultBranch, deps, expectedHeadSha) {
  const created = await openOrAdoptPr(git, app.repoPath, defaultBranch, deps);
  if (!created?.url) {
    return skipped(app, 'pr-failed');
  }
  const outcome = await mergeSnapshotPr(app, created, deps, git, defaultBranch, { expectedHeadSha });
  console.log(`📊 Quality snapshot PR opened for app ${app.id}: ${created.url}`);
  return {
    published: true, hash: null, path: APP_QUALITY_SNAPSHOT_FILENAME,
    prUrl: created.url, prNumber: created.number,
    ...mergeOutcomeFields(outcome),
  };
}

async function landSnapshotPr(app, { body, count, defaultBranch, git, deps, message, removeLegacy = false, remoteSha }) {
  const makeTemp = deps.mkdtemp || mkdtemp;
  let worktreePath;
  let retainWorktree = false;
  const removeTemp = deps.rm || rm;
  const commitPaths = removeLegacy
    ? [APP_QUALITY_SNAPSHOT_FILENAME, APP_QUALITY_LEGACY_SNAPSHOT_FILENAME]
    : [APP_QUALITY_SNAPSHOT_FILENAME];
  const commitMessage = message || `chore: publish PortOS quality snapshot (${count} measurements)`;

  const run = async () => {
    const baseRef = `origin/${defaultBranch}`;
    await addSnapshotWorktree(app, deps, worktreePath, baseRef);
    await (deps.writeFile || atomicWrite)(join(worktreePath, APP_QUALITY_SNAPSHOT_FILENAME), body);
    if (removeLegacy) {
      await git.execGit(['rm', '-f', '--', APP_QUALITY_LEGACY_SNAPSHOT_FILENAME], worktreePath);
    }
    await git.stageFiles(worktreePath, [APP_QUALITY_SNAPSHOT_FILENAME]);
    const { hash } = await git.commit(
      worktreePath,
      commitMessage,
      { paths: commitPaths },
    ).catch(err => git.unstageFiles(worktreePath, commitPaths)
      .catch(() => {}).then(() => Promise.reject(err)));

    const guard = await publicationGuard(app, git, defaultBranch, deps);
    if (guard.reason) return deferredPublication(app, guard.reason);
    if (guard.remoteSha !== remoteSha) {
      throw Object.assign(new Error('Quality snapshot branch changed during preparation'), { qualitySnapshotStaleLease: true });
    }
    await pushSnapshotBranch(git, worktreePath, remoteSha).catch(error => {
      if (/stale info/i.test(error?.message || '')) error.qualitySnapshotStaleLease = true;
      throw error;
    });
    const pr = await openOrAdoptPr(git, worktreePath, defaultBranch, deps);
    if (!pr?.url) {
      throw new Error(pr?.error || 'quality snapshot pull request was not created');
    }
    // If validation is interrupted, preserve the published checkout by default.
    retainWorktree = true;
    const queued = await mergeSnapshotPr(app, pr, deps, git, defaultBranch, { worktreePath, expectedHeadSha: hash });
    retainWorktree = queued.guardManaged === true;
    console.log(`📊 Published quality snapshot for app ${app.id}: ${count} measurements → ${hash} (${pr.url})`);
    return {
      published: true, hash, path: APP_QUALITY_SNAPSHOT_FILENAME,
      prUrl: pr.url, prNumber: pr.number,
      ...mergeOutcomeFields(queued),
    };
  };

  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(app.repoPath, async () => {
    worktreePath = await makeTemp(join(tmpdir(), 'portos-quality-'));
    return run().finally(() => retainWorktree ? undefined : cleanupSnapshotWorktree(app, git, worktreePath, removeTemp));
  });
}

async function addSnapshotWorktree(app, deps, path, ref) {
  const add = deps.addWorktree || (await import('./worktreeManager.js')).addWorktreeWithRetry;
  // Detached checkouts leave the stable PR branch attachable for review/recovery.
  await add(['worktree', 'add', '--detach', path, ref], app.repoPath);
}

const removeWorktreeRegistration = (git, repoPath, worktreePath) => git
  .execGit(['worktree', 'remove', '--force', worktreePath], repoPath, { ignoreExitCode: true })
  .then(result => (result?.exitCode ?? 0) === 0 ? null : String(result.stderr || `exit ${result.exitCode}`))
  .catch(err => err?.message || String(err));

// Serialized cleanup of the ONE temporary worktree this invocation created
// (#8726): Git removal first, then the directory, then a retry of the
// registration removal (Git accepts a missing directory), then a verification
// against `worktree list`. The mkdtemp basename is unique, so matching on it
// never touches another worktree and survives /var ↔ /private/var aliasing.
// Cleanup failure is reported, never thrown — the publication outcome stands.
async function cleanupSnapshotWorktree(app, git, worktreePath, removeTemp) {
  const redact = text => String(text || '').split(worktreePath).join('<snapshot-worktree>')
    .replace(/\s+/g, ' ').trim().slice(0, 200);
  let gitError = await removeWorktreeRegistration(git, app.repoPath, worktreePath);
  const rmError = await removeTemp(worktreePath, { recursive: true, force: true })
    .then(() => null, err => err?.code || err?.message || String(err));
  if (gitError) gitError = await removeWorktreeRegistration(git, app.repoPath, worktreePath);
  const listing = await git.execGit(['worktree', 'list', '--porcelain'], app.repoPath, { ignoreExitCode: true })
    .catch(() => null);
  const name = basename(worktreePath);
  const verificationFailed = !listing || listing.exitCode !== 0 || typeof listing.stdout !== 'string';
  const stillRegistered = String(listing?.stdout || '').split('\n')
    .some(line => line.startsWith('worktree ') && basename(line.slice(9).trim()) === name);
  if (!verificationFailed && !stillRegistered && !rmError) return;
  const reasons = [
    verificationFailed && 'registration verification unavailable',
    stillRegistered && `registration remains (${redact(gitError) || 'no error reported'})`,
    rmError && `directory removal failed (${redact(rmError)})`,
  ].filter(Boolean).join('; ');
  console.warn(`⚠️ Quality snapshot worktree cleanup incomplete for app ${app.id}: ${reasons}`);
}

async function pushSnapshotBranch(git, worktreePath, remoteSha) {
  // Pin the exact ref whose contents were inspected, including its absence.
  // Re-reading a newer ref here would authorize discarding uninspected work.
  await git.execGit([
    'push', `--force-with-lease=refs/heads/${QUALITY_SNAPSHOT_BRANCH}:${remoteSha}`,
    'origin', `HEAD:refs/heads/${QUALITY_SNAPSHOT_BRANCH}`,
  ], worktreePath);
}

async function openOrAdoptPr(git, cwd, base, deps) {
  const created = await git.createPR(cwd, {
    title: QUALITY_PR_TITLE,
    body: QUALITY_PR_BODY,
    base,
    head: QUALITY_SNAPSHOT_BRANCH,
  }).catch(err => ({ success: false, error: err.message }));

  if (created?.success && created.url) return decoratePr(git, created);

  const probe = deps.probePrForBranch
    || (await import('./prProbe.js')).probePrForBranch;
  const found = await probe(cwd, QUALITY_SNAPSHOT_BRANCH);
  const prState = typeof found?.prState === 'string' ? found.prState.toUpperCase() : '';
  if (found?.prUrl && found?.prNumber && prState === 'OPEN') {
    return { url: found.prUrl, number: found.prNumber, cli: found.cli || created?.cli };
  }
  return { error: created?.error || 'pull request was not created' };
}

function decoratePr(git, created) {
  const parsed = git.parsePullRequestUrl(created.url);
  return {
    url: created.url,
    number: parsed?.number ?? null,
    cli: created.cli,
  };
}

const mergeOutcomeFields = outcome => ({
  merged: outcome.merged === true,
  queuedMerge: outcome.queued === true,
  ...(outcome.deferred === true ? { deferredMerge: true } : {}),
  ...(outcome.guard ? { mergeGuard: outcome.guard } : {}),
  ...(outcome.retainedCheckouts?.length ? { retainedMergeCheckouts: outcome.retainedCheckouts } : {}),
});

/**
 * Guard-capable repositories validate outside admission and recheck both inputs
 * inside it. They never fall through to an unguarded merge or pending queue.
 * Other repositories keep their existing immediate/merge-on-green behavior.
 *
 * The immediate attempt needs this install's repository merge admission. When
 * another owner holds it (or ownership cannot be verified) the merge is
 * deferred. Only generic GitHub repositories use the local pending-merge
 * queue. Guard-capable PRs and GitLab admission refusals stay open for retry.
 *
 * @returns {{merged: boolean, queued: boolean, deferred?: boolean}} — merged
 *   and queued are never both true.
 */
async function mergeSnapshotPr(app, pr, deps, git, defaultBranch, checkout = {}) {
  if (!pr?.url || !pr?.number) return { merged: false, queued: false };
  const guards = await import('./appQualitySnapshotMerge.js');
  const evidence = await guards.readSnapshotMergeInputs(app, pr, defaultBranch, git, deps);
  if (evidence.required) {
    if (checkout.expectedHeadSha !== evidence.headSha) evidence.reason ||= 'snapshot-merge-published-head-changed';
    return guardedSnapshotMerge(app, pr, deps, git, guards, evidence, checkout.worktreePath);
  }
  const attempt = await withSnapshotMergeAdmission(app, deps, () => tryImmediateMerge(app, pr, deps, git));
  if (attempt.deferred) {
    const queued = pr.cli === 'glab' ? false : await queueMergeWhenGreenFallback(app, pr, deps);
    return { merged: false, queued: queued === true, deferred: true };
  }
  if (attempt.result) return { merged: true, queued: false };
  const queued = await queueMergeWhenGreenFallback(app, pr, deps);
  return { merged: false, queued: queued === true };
}

async function guardedSnapshotMerge(app, pr, deps, git, guards, evidence, existingPath) {
  const deferred = () => ({ merged: false, queued: false, deferred: true, guard: evidence, guardManaged: true });
  const run = async path => {
    evidence.worktreePath = path;
    try {
      const current = await git.execGit(['rev-parse', '--verify', 'HEAD^{commit}'], path);
      if (current.exitCode !== 0 || !/^[a-f0-9]{40}$/i.test(current.stdout?.trim() || '')) {
        throw new Error('snapshot-checkout-head-unreadable');
      }
      evidence.checkoutHead = current.stdout.trim();
      await guards.recordSnapshotMergeEvidence(pr, evidence, deps, { status: 'preparing' });
      if (evidence.reason) throw new Error(evidence.reason);
      await guards.validateSnapshotMerge(app, pr, evidence, git, deps);
      const attempt = await withSnapshotMergeAdmission(app, deps, async () => {
        await guards.verifySnapshotMergeInputs(app, pr, evidence, git, deps);
        return tryImmediateMerge(app, pr, deps, git, evidence.headSha);
      });
      if (attempt.result) {
        const retire = deps.retireSnapshotMergeCheckouts || guards.retireSnapshotMergeCheckouts;
        const retainedCheckouts = await retire(app, pr, deps).catch(() => [path]);
        return { merged: true, queued: false, guardManaged: true, retainedCheckouts };
      }
      evidence.reason = attempt.reason || 'snapshot-merge-deferred';
    } catch (error) {
      evidence.reason = error.stdout !== undefined || error.stderr !== undefined ? 'snapshot-merge-guards-failed' : error.message;
      console.log(`⏳ Quality snapshot merge retained for app ${app.id}: ${evidence.reason}`);
      await guards.recordSnapshotMergeEvidence(pr, evidence, deps, {
        status: 'deferred', error: error.message, stdout: error.stdout, stderr: error.stderr,
      });
      return deferred();
    }
    await guards.recordSnapshotMergeEvidence(pr, evidence, deps, { status: 'deferred' });
    return deferred();
  };
  if (existingPath) return run(existingPath);
  if (evidence.reason) return deferred();
  const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
  return withCheckoutPublication(app.repoPath, async () => {
    const retained = await guards.retainedSnapshotMergeCheckouts(app, pr, deps);
    const matching = retained.find(tree => tree.head === evidence.headSha);
    const path = matching?.path || await (deps.mkdtemp || mkdtemp)(join(tmpdir(), 'portos-quality-'));
    if (!matching) await addSnapshotWorktree(app, deps, path, evidence.headSha);
    return run(path);
  }).catch(error => {
    evidence.reason = error.message;
    return deferred();
  });
}

async function withSnapshotMergeAdmission(app, deps, work) {
  const readOrigin = deps.getOriginInfo || (await import('../lib/gitRemote.js')).getOriginInfo;
  const withAdmission = deps.withMergeAdmission
    || (await import('./cosMergeAdmission.js')).withPendingMergeAdmission;
  const origin = await readOrigin(app.repoPath).catch(() => null);
  const admitted = await withAdmission(origin, work)
    .catch(err => ({ admitted: false, reason: err?.message || 'admission-error' }));
  if (admitted.admitted !== true) {
    console.log(`⏳ Quality snapshot merge deferred for app ${app.id}: ${admitted.reason || 'admission refused'}`);
    return { deferred: true, reason: admitted.reason || 'admission-refused' };
  }
  return { deferred: false, result: admitted.result === true };
}

async function tryImmediateMerge(app, pr, deps, git, expectedHeadSha) {
  if (pr.cli === 'glab') {
    const execGlab = deps.execGlab || (await import('./gitlab.js')).execGlab;
    const run = args => execGlab(args, app.repoPath, undefined, { rejectOnError: true })
      .then(() => true, err => err);
    // Immediate merge: explicitly NOT waiting for the pipeline.
    let result = await run(['mr', 'merge', String(pr.number), '--yes', '--when-pipeline-succeeds=false']);
    if (result !== true && /unknown flag|unknown shorthand/i.test(result?.message || '')) {
      result = await run(['mr', 'merge', String(pr.number), '--yes']);
    }
    if (result !== true) {
      console.log(`📊 Quality snapshot MR #${pr.number} immediate merge unavailable for app ${app.id}: ${result?.message || 'merge refused'}`);
      return false;
    }
    console.log(`📊 Quality snapshot MR #${pr.number} merged immediately for app ${app.id}`);
    return true;
  }
  const mergePR = deps.mergePR || git?.mergePR;
  if (typeof mergePR !== 'function') return false;
  const result = await mergePR.call(git || null,
    app.repoPath, pr.number, { forgeAccount: app?.forgeAccount || null, ...(expectedHeadSha ? { expectedHeadSha } : {}) },
  ).catch(err => ({ success: false, error: err?.message }));
  if (result?.success !== true) {
    console.log(`📊 Quality snapshot PR #${pr.number} immediate merge unavailable for app ${app.id}: ${result?.error || 'merge refused'}`);
    return false;
  }
  console.log(`📊 Quality snapshot PR #${pr.number} merged immediately for app ${app.id}`);
  return true;
}

async function queueMergeWhenGreenFallback(app, pr, deps) {
  if (!pr?.url || !pr?.number) return false;
  if (pr.cli === 'glab') {
    const execGlab = deps.execGlab || (await import('./gitlab.js')).execGlab;
    const run = args => execGlab(args, app.repoPath, undefined, { rejectOnError: true })
      .then(() => true, err => err);
    let result = await run(['mr', 'merge', String(pr.number), '--yes', '--auto-merge']);
    if (result !== true && /unknown flag|unknown shorthand/i.test(result?.message || '')) {
      result = await run(['mr', 'merge', String(pr.number), '--yes', '--when-pipeline-succeeds']);
    }
    if (result !== true) {
      console.log(`📊 Quality snapshot MR #${pr.number} left open for app ${app.id}: ${result?.message || 'auto-merge unavailable'}`);
      return false;
    }
    return true;
  }
  const queuePendingMerge = deps.queuePendingMerge
    || (await import('./prWatcher.js')).queuePendingMerge;
  return queuePendingMerge(app.id, {
    prUrl: pr.url,
    prNumber: pr.number,
    prBranch: QUALITY_SNAPSHOT_BRANCH,
    sourceAgentId: null,
    sourceTask: {
      id: `quality-snapshot-${app.id}`,
      priority: 'LOW',
      description: 'Publish PortOS quality snapshot',
      metadata: { app: app.id },
    },
  });
}