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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* `.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 },
},
});
}