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
import { existsSync, realpathSync } from 'fs';
import { randomUUID } from 'node:crypto';
import { AsyncLocalStorage } from 'node:async_hooks';
import { mkdtemp } from 'fs/promises';
import { tmpdir } from 'os';
import { delimiter, dirname, join, resolve } from 'path';
import { safeJSONParse, PATHS, sleep, rmGuarded } from '../lib/fileUtils.js';
import { isGitLockError, listWorktrees } from './worktreeManager.js';
import { execGit, execGitSafe } from '../lib/execGit.js';
import { clearStaleGitLock } from '../lib/gitStaleLock.js';
import { resolveForgeForRepo } from './forgeAuth.js';
export { resolveForgeForRepo, resolveForgeTokenEnv } from './forgeAuth.js';
import {
parseStatus,
parseDiffStat,
parseBranchVerboseLine,
parseSubmoduleStatusLine,
extractAgentSummary,
isBenignConcurrentFetchRefRace
} from '../lib/gitOutputParsers.js';
import {
parseGitRemote,
parseGitHubOwnerFromRemote,
pickGhAccountForOwner,
detectForgeCli,
parsePullRequestUrl
} from '../lib/gitForge.js';
import { PROTECTED_BRANCHES, validateFilePaths, toLiteralPathspec, assertSafeRef } from '../lib/gitArgs.js';
import { ServerError } from '../lib/errorHandler.js';
import { securityScanPRDisclosure } from '../lib/securityScanEvidence.js';
// Re-export so callers that used to import from services/git.js keep working.
export { execGit, execGitSafe };
// Re-export the extracted pure helpers so existing
// `import { … } from 'services/git.js'` call sites keep working.
export {
parseStatus,
parseGitRemote,
parseGitHubOwnerFromRemote,
pickGhAccountForOwner,
detectForgeCli,
parsePullRequestUrl,
extractAgentSummary
};
const checkoutMutations = new Map();
const checkoutMutationContext = new AsyncLocalStorage();
// Existing writers register so an exclusive rebase/push cannot overlap them.
// Nested calls retain their own publication lifetime, even if they outlive a parent.
async function withCheckoutMutation(dir, work, { exclusive = false } = {}) {
let key;
try { key = realpathSync(dir); }
catch (error) {
if (error.code !== 'ENOENT') throw error;
key = resolve(dir);
}
// API paths may name a subdirectory or a symlink into the same checkout.
for (let root = key; ; root = dirname(root)) {
if (existsSync(join(root, '.git'))) { key = root; break; }
if (dirname(root) === root) break;
}
const active = checkoutMutations.get(key);
const parent = checkoutMutationContext.getStore();
const inherited = parent?.active && parent.key === key && parent.state === active;
if (!inherited && (active?.exclusive || (exclusive && active))) {
throw new ServerError('A Git operation is already running for this checkout', { status: 409, code: 'GIT_BUSY' });
}
const state = active || { count: 0, exclusive };
state.count++;
checkoutMutations.set(key, state);
const context = { key, state, active: true };
try {
const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
return await withCheckoutPublication(dir, () => checkoutMutationContext.run(context, work));
} finally {
context.active = false;
if (--state.count === 0) checkoutMutations.delete(key);
}
}
/**
* Get git status for a directory.
*
* `paths` scopes the answer to a pathspec, for a caller whose follow-up write
* is itself scoped — a repo-wide "is anything dirty?" does not answer "did THIS
* file change?", and a partial `git commit -- <path>` exits 1 when that path
* carries no change.
*/
export async function getStatus(dir, { paths = [] } = {}) {
const result = await execGit(
['status', '--porcelain', ...(paths.length ? ['--', ...paths] : [])],
dir,
{ env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } },
);
// trimEnd (not trim): porcelain status codes use leading spaces (e.g. ' M' = unstaged)
const lines = result.stdout.trimEnd().split('\n').filter(Boolean);
const files = lines.map(line => {
const status = line.substring(0, 2);
const path = line.substring(3);
return {
path,
status: parseStatus(status),
staged: status[0] !== ' ' && status[0] !== '?',
modified: status[1] === 'M',
added: status[0] === 'A' || status === '??',
deleted: status[0] === 'D' || status[1] === 'D'
};
});
return {
clean: files.length === 0,
files,
staged: files.filter(f => f.staged).length,
unstaged: files.filter(f => !f.staged).length
};
}
/**
* Raw `git status --porcelain` output, for callers that need to feed it to
* `classifyWorktreeDirt` (worktreeManager.js) rather than re-deriving "is this
* dirt real work?" from the parsed shape. Kept separate from `getStatus` because
* that one is returned verbatim by `POST /api/git/status`, where a raw duplicate
* of `files[]` would just double the payload on every dirty tree.
*/
export async function getStatusPorcelain(dir) {
return (await execGit(['status', '--porcelain'], dir,
{ env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } })).stdout;
}
/**
* Get current branch name
*/
export async function getBranch(dir) {
const result = await execGit(['rev-parse', '--abbrev-ref', 'HEAD'], dir);
return result.stdout.trim();
}
/**
* Get recent commits
*/
export async function getCommits(dir, limit = 10) {
// Validate limit is a positive integer to prevent injection
const safeLimit = Math.max(1, Math.min(100, parseInt(limit, 10) || 10));
const format = '--format={"hash":"%h","message":"%s","author":"%an","date":"%cI"}';
const result = await execGit(['log', format, '-n', String(safeLimit)], dir);
const commits = result.stdout.trim().split('\n').filter(Boolean)
.map(line => safeJSONParse(line, null))
.filter(Boolean);
return commits;
}
/**
* Get diff for unstaged changes
*/
export async function getDiff(dir, staged = false) {
const args = staged ? ['diff', '--cached'] : ['diff'];
const result = await execGit(args, dir, { maxBuffer: 10 * 1024 * 1024 });
return result.stdout;
}
/**
* Get diff stats
*/
export async function getDiffStats(dir) {
const result = await execGit(['diff', '--stat'], dir);
return parseDiffStat(result.stdout);
}
/**
* Stage files. Paths are passed with `:(literal)` pathspec magic so git
* treats wildcard characters as literal filename bytes — `[id].jsx` stages
* that exact file, and a crafted `*` can't expand to the whole tree.
*/
export async function stageFiles(dir, files) {
return withCheckoutMutation(dir, () => stageFilesAdmitted(dir, files));
}
async function stageFilesAdmitted(dir, files) {
const safePaths = validateFilePaths(files).map(toLiteralPathspec);
await execGit(['add', '--', ...safePaths], dir);
return true;
}
/**
* Unstage files (same literal-pathspec handling as stageFiles).
*/
export async function unstageFiles(dir, files) {
return withCheckoutMutation(dir, () => unstageFilesAdmitted(dir, files));
}
async function unstageFilesAdmitted(dir, files) {
const safePaths = validateFilePaths(files).map(toLiteralPathspec);
await execGit(['reset', 'HEAD', '--', ...safePaths], dir);
return true;
}
/**
* Create commit.
*
* `paths` scopes the commit to those repo-relative files (`git commit -m … -- <pathspecs>`),
* so an automated commit can never sweep in whatever the user happened to have staged.
* Same `:(literal)` pathspec handling as stageFiles. Omitted = commit the index as-is.
*/
export async function commit(dir, message, { paths = [] } = {}) {
return withCheckoutMutation(dir, () => commitAdmitted(dir, message, { paths }));
}
// Snapshot only read-only identities. Detached/unborn HEAD cannot verify an
// ambiguous result; ordinary successful commits there still work as before.
async function commitIdentity(dir) {
const branch = await execGit(['symbolic-ref', '--quiet', 'HEAD'], dir, { ignoreExitCode: true });
const head = await execGit(['rev-parse', '--verify', 'HEAD'], dir, { ignoreExitCode: true });
return {
branch: branch.exitCode === 0 ? branch.stdout.trim() : null,
head: head.exitCode === 0 && /^[a-f0-9]{40,64}$/.test(head.stdout.trim()) ? head.stdout.trim() : null
};
}
async function verifyCommitReadback(dir, before, action) {
const after = await commitIdentity(dir);
if (!before.branch?.startsWith('refs/heads/') || !before.head
|| after.branch !== before.branch || !after.head || after.head === before.head) return { after, verified: false };
const log = await execGit(['reflog', '-1', '--format=%H%x00%gs', before.branch], dir);
const [hash, subject] = log.stdout.trim().split('\0');
const parent = await execGit(['rev-parse', `${after.head}^1`], dir);
// A matching tree/message alone could belong to a competing writer. The
// per-invocation reflog action correlates this advance with our child process.
const current = await commitIdentity(dir);
return { after, verified: hash === after.head && subject?.startsWith(`${action}: `)
&& parent.stdout.trim() === before.head
&& current.branch === before.branch && current.head === after.head };
}
async function commitAdmitted(dir, message, { paths = [] } = {}) {
const pathspecs = paths.length ? ['--', ...validateFilePaths(paths).map(toLiteralPathspec)] : [];
const before = await commitIdentity(dir);
const action = `portos-commit-${randomUUID()}`;
// Rerere can fail AFTER commit updated the ref (#13292). Never repeat the
// mutation or touch a lock. Timeouts/signals remain uncertain lifetime errors.
const result = await execGit(['commit', '-m', message, ...pathspecs], dir, {
ignoreExitCode: true, env: { ...process.env, GIT_REFLOG_ACTION: action }
});
if (result.exitCode !== 0) {
const readback = Number.isInteger(result.exitCode) && !result.terminated
? await verifyCommitReadback(dir, before, action).catch(() => null) : null;
const commitOutcome = {
command: 'commit', exitCode: result.exitCode, beforeHead: before.head,
afterHead: readback?.after?.head ?? null,
status: readback?.verified ? 'verified-committed' : 'unverified'
};
if (readback?.verified) return { hash: readback.after.head, message, commitOutcome };
throw Object.assign(new Error(result.stderr || `git exited with code ${result.exitCode}`), {
commitOutcome, ...(result.terminated ? { name: 'AbortError', terminated: true, signal: result.signal } : {})
});
}
// Stop at the header's hash before bracketed hexadecimal text in the subject.
const hashMatch = result.stdout.match(/^\[[^\r\n]*? ([a-f0-9]+)\]/m);
return {
hash: hashMatch ? hashMatch[1] : null,
message
};
}
/**
* Check if directory is a git repo
*/
export async function isRepo(dir) {
const result = await execGit(['rev-parse', '--is-inside-work-tree'], dir, { ignoreExitCode: true }).catch(() => null);
return result?.stdout.trim() === 'true';
}
/** Actionable refusal text shared by task creation and spawn-time worktree prep. */
export function notGitRepoMessage(appName) {
return `${appName} is not a git repository — run \`git init\` in its directory (and add a remote if PRs are needed), or disable worktree/PR for this task`;
}
/**
* Get remote info
*/
export async function getRemote(dir) {
const result = await execGit(['remote', '-v'], dir, { ignoreExitCode: true }).catch(() => null);
if (!result) return null;
const lines = result.stdout.trim().split('\n');
const origins = {};
lines.forEach(line => {
const [name, url, type] = line.split(/\s+/);
if (!origins[name]) origins[name] = {};
origins[name][type?.replace(/[()]/g, '')] = url;
});
return origins;
}
/**
* Fetch from origin
*/
const FETCH_MAX_ATTEMPTS = 4;
const FETCH_RETRY_DELAY_MS = 250;
const FETCH_FRESHNESS_MS = 15000;
const SUBMODULE_UPDATE_TIMEOUT_MS = 60000;
const lastFetchTimes = new Map();
const activeFetches = new Map();
export function recordFetchSuccess(dir) {
if (dir) lastFetchTimes.set(dir, Date.now());
}
export function isFetchFresh(dir, windowMs = FETCH_FRESHNESS_MS) {
if (!dir) return false;
const last = lastFetchTimes.get(dir);
if (!last) return false;
return (Date.now() - last) < windowMs;
}
export function clearFetchCache() {
lastFetchTimes.clear();
activeFetches.clear();
}
function fetchOriginAttempt(dir, attempt, prune = false) {
return execGit(prune ? ['fetch', '--prune', 'origin'] : ['fetch', 'origin'], dir).then(
() => {
recordFetchSuccess(dir);
return true;
},
(err) => {
// A concurrent fetch that already wrote the exact refs this one wanted is
// a SUCCESS reported as a failure — git exits non-zero on the lost
// compare-and-swap even though the remote-tracking refs now hold the
// right commits. Retrying re-runs a whole network fetch to learn there is
// nothing to do, and on a busy repo every attempt loses the same race, so
// the caller surfaced a red error for work that had actually completed.
if (isBenignConcurrentFetchRefRace(err.message)) {
recordFetchSuccess(dir);
return true;
}
// Another PortOS surface or agent may advance the same remote ref mid-fetch.
if (attempt >= FETCH_MAX_ATTEMPTS || !isGitLockError(err.message)) throw err;
return sleep(FETCH_RETRY_DELAY_MS).then(() => fetchOriginAttempt(dir, attempt + 1, prune));
}
);
}
/**
* Fetch origin with the concurrency handling a raw `git fetch` lacks: retries an
* `index.lock` collision, and treats a lost compare-and-swap on refs another
* PortOS surface already wrote as the SUCCESS it is.
* @param {string} dir
* @param {{prune?: boolean}} [opts] - `prune` also drops remote-tracking refs whose
* remote branch is gone, for callers that go on to reason about what origin still has.
*/
export async function fetchOrigin(dir, { prune = false } = {}) {
const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
return withCheckoutPublication(dir, () => fetchOriginAdmitted(dir, { prune }));
}
function fetchOriginAdmitted(dir, { prune = false } = {}) {
return fetchOriginAttempt(dir, 1, prune);
}
/**
* Update all local branches that have remote tracking branches.
* Uses fetch refspecs for non-current branches to avoid checkout (which
* would swap files on disk and trigger HMR/server restarts).
*/
export async function updateBranches(dir) {
return withCheckoutMutation(dir, () => updateBranchesAdmitted(dir));
}
async function updateBranchesAdmitted(dir) {
await fetchOrigin(dir);
const status = await getStatus(dir);
const currentBranch = await getBranch(dir);
const allBranches = await getBranches(dir);
const trackBranches = allBranches.filter(b => b.tracking).map(b => b.name);
const results = { currentBranch };
// Update non-current branches via fetch refspec (no checkout needed)
for (const branch of trackBranches.filter(b => b !== currentBranch)) {
const r = await execGit(['fetch', 'origin', `${branch}:${branch}`], dir, { ignoreExitCode: true });
results[branch] = (r.stderr?.includes('fatal') || r.stderr?.includes('rejected')) ? 'failed' : 'updated';
}
// Update current branch if it's one of the tracked branches — requires merge
// Skip if working tree is dirty — other agents may own those uncommitted changes
if (trackBranches.includes(currentBranch)) {
if (!status.clean) {
results[currentBranch] = 'skipped-dirty';
} else {
const r = await execGit(['merge', '--ff-only', `origin/${currentBranch}`], dir, { ignoreExitCode: true });
results[currentBranch] = r.stderr?.includes('fatal') ? 'failed' : 'updated';
}
}
return results;
}
/**
* Get branch comparison (how far ahead headBranch is from baseBranch)
*/
export async function getBranchComparison(dir, baseBranch = 'main', headBranch = 'dev') {
assertSafeRef(baseBranch);
assertSafeRef(headBranch);
const format = '--format={"hash":"%h","message":"%s","author":"%an","date":"%cI"}';
const logResult = await execGit(
['log', format, `${baseBranch}..${headBranch}`], dir, { ignoreExitCode: true }
);
const commits = logResult.stdout.trim()
.split('\n')
.filter(Boolean)
.map(line => safeJSONParse(line, null))
.filter(Boolean);
const statResult = await execGit(
['diff', '--stat', `${baseBranch}...${headBranch}`], dir, { ignoreExitCode: true }
);
return {
ahead: commits.length,
commits,
stats: parseDiffStat(statResult.stdout)
};
}
/**
* Push to origin
*/
export async function push(dir, branch = null) {
return withCheckoutMutation(dir, () => pushAdmitted(dir, branch));
}
async function pushAdmitted(dir, branch = null) {
if (branch) assertSafeRef(branch);
const args = branch ? ['push', 'origin', branch] : ['push'];
const result = await execGit(args, dir);
return { success: true, output: result.stdout + result.stderr };
}
/**
* Push all local branches that are ahead of their remote tracking branch.
* Never uses --force. Returns per-branch results.
*/
export async function pushAll(dir) {
return withCheckoutMutation(dir, () => pushAllAdmitted(dir));
}
async function pushAllAdmitted(dir) {
const allBranches = await getBranches(dir);
const pushable = allBranches.filter(b => b.tracking && b.ahead > 0);
if (pushable.length === 0) {
return { success: true, pushed: 0, results: {}, message: 'Nothing to push' };
}
const results = {};
let failed = 0;
for (const branch of pushable) {
const r = await execGit(['push', 'origin', branch.name], dir, { ignoreExitCode: true });
const output = (r.stdout || '') + (r.stderr || '');
const ok = r.exitCode === 0;
results[branch.name] = { success: ok, output: output.trim() };
if (!ok) failed++;
}
return {
success: failed === 0,
pushed: pushable.length - failed,
failed,
total: pushable.length,
results
};
}
/**
* Create and switch to a new branch
*/
export async function createBranch(dir, branchName) {
return withCheckoutMutation(dir, () => createBranchAdmitted(dir, branchName));
}
async function createBranchAdmitted(dir, branchName) {
await execGit(['checkout', '-b', branchName], dir);
return { success: true, branch: branchName };
}
/**
* Switch to an existing branch
*/
export async function checkout(dir, branchName) {
return withCheckoutMutation(dir, () => checkoutAdmitted(dir, branchName));
}
async function checkoutAdmitted(dir, branchName) {
assertSafeRef(branchName);
await execGit(['checkout', branchName], dir);
return { success: true, branch: branchName };
}
async function execForgeCli(cli, args, dir, env) {
if (cli === 'glab') {
const { execGlab } = await import('./gitlab.js');
return execGlab(args, dir, undefined, { env, rejectOnError: true });
}
const { execGh } = await import('./github.js');
return execGh(args, undefined, { cwd: dir, env });
}
/**
* Create a pull request (GitHub) or merge request (GitLab) using `gh` / `glab`.
* Forge is auto-detected from the repo's `origin` URL; gh identity is auto-pinned
* to the matching account when multiple gh accounts are logged in.
* Fails gracefully if the relevant CLI is not installed.
* @param {string} dir - Working directory (repo root)
* @param {object} options - PR options
* @param {string} options.title - PR/MR title
* @param {string} options.body - PR/MR description
* @param {string} options.base - Base branch (target)
* @param {string} options.head - Head branch (source, must be pushed to remote)
* @returns {Promise<{success: boolean, url?: string, error?: string, cli?: string, account?: string|null, owner?: string|null, host?: string|null}>}
*/
export async function createPR(dir, { title, body, base, head, draft = false }) {
const { cli, env, host, owner, account } = await resolveForgeForRepo(dir);
const args = cli === 'glab'
? ['mr', 'create', '--title', title, '--description', body || '', '--target-branch', base, '--source-branch', head]
: ['pr', 'create', '--title', title, '--body', body || '', '--base', base, '--head', head];
if (draft) args.push('--draft');
const meta = { cli, account, owner, host };
try {
const stdout = await execForgeCli(cli, args, dir, env);
if (stdout === null) {
return { success: false, error: `${cli} command failed or timed out`, ...meta };
}
// Both gh and glab print the resulting URL on stdout (gh: just the URL;
// glab: a couple lines ending in the URL — extract the last http(s)-looking line).
const urlMatch = stdout.trim().match(/(https?:\/\/\S+)\s*$/);
const url = urlMatch ? urlMatch[1] : stdout.trim();
return { success: true, url, ...meta };
} catch (err) {
return { success: false, error: err.message || `${cli} command failed`, ...meta };
}
}
/**
* Merge an already-open GitHub pull request with the same owner-pinned `gh`
* environment used to create it. Callers decide when CI is green; this helper
* only performs the deterministic merge and reports its outcome.
*
* The actual `gh pr merge` invocation is the shared core in
* `appPullRequestMerge.js` (`runForgeMerge`), lazily imported like the other
* forge CLIs below — this stays the only owner of that argv (#7580), and its
* `['pr', 'merge', prNumber, '--merge']` shape and 60s
* default timeout are pinned by `git.forgeTimeout.test.js`.
*
* @param {string} dir - Working directory for the target repository
* @param {number|string} prNumber - Pull request number
* @returns {Promise<{success: boolean, error?: string, cli?: string, account?: string|null, owner?: string|null, host?: string|null}>}
*/
export async function mergePR(dir, prNumber, { forgeAccount = null, expectedHeadSha = null } = {}) {
// The pin matters here as much as on the read side: an owner-match alone picks
// the wrong account for an org repo, and the merge fails authorization (#7540).
const { cli, env, host, owner, account } = await resolveForgeForRepo(dir, { forgeAccount });
const meta = { cli, account, owner, host };
if (cli !== 'gh') {
return { success: false, error: `Merge-only PR automation requires gh, not ${cli}`, ...meta };
}
const { runForgeMerge } = await import('./appPullRequestMerge.js');
const result = await runForgeMerge({
cwd: dir,
env,
forge: 'github',
repoSpec: null,
number: prNumber,
method: 'merge',
deleteBranch: false,
expectedHeadSha,
});
if (result.code === 'invalid-head') return { success: false, error: result.error, ...meta };
// A zero exit may mean queued, and a timeout/nonzero exit may follow a
// completed merge. Read back before reporting success or deleting anything.
const { execGh } = await import('./github.js');
const merged = await execGh(['pr', 'view', String(prNumber), '--json',
'state,url,headRefName,headRefOid,baseRefName,isCrossRepository,headRepository'],
undefined, { cwd: dir, env }).then(value => safeJSONParse(value, null), () => null);
if (merged?.state !== 'MERGED') {
return { success: false, error: result.error || 'Pull request merge is not yet verified',
branchCleanup: { deleted: false, reason: 'merge-unverified' }, ...meta };
}
if (expectedHeadSha && (typeof merged.headRefOid !== 'string'
|| merged.headRefOid.toLowerCase() !== expectedHeadSha.toLowerCase())) {
return { success: false, error: 'Merged pull request does not match the reviewed head',
code: 'reviewed-head-changed', branchCleanup: { deleted: false, reason: 'reviewed-head-changed' }, ...meta };
}
const branchCleanup = await deleteVerifiedMergedHead(dir, merged, { expectedHeadSha, host, prNumber, env, account });
return { success: true, mergedHeadSha: merged.headRefOid, branchCleanup, ...meta };
}
/** Remote cleanup is independent of merge success; local refs and worktrees
* belong to the archive/ownership cleanup workflow, including ignored files. */
async function deleteVerifiedMergedHead(dir, merged, { expectedHeadSha, host, prNumber, env, account }) {
const retain = reason => ({ deleted: false, reason });
if (!expectedHeadSha) return retain('reviewed-head-unavailable');
const target = parsePullRequestUrl(merged.url);
if (!target || String(target.number) !== String(prNumber) || target.host.toLowerCase() !== String(host).toLowerCase()) {
return retain('repository-unverified');
}
const fullName = `${target.owner}/${target.repo}`.toLowerCase();
if (merged.isCrossRepository !== false || typeof merged.headRepository?.nameWithOwner !== 'string'
|| merged.headRepository.nameWithOwner.toLowerCase() !== fullName) {
return retain('source-repository-unverified');
}
const branch = merged.headRefName;
if (typeof branch !== 'string' || !branch || typeof merged.baseRefName !== 'string' || !merged.baseRefName
|| PROTECTED_BRANCHES.includes(branch) || branch === merged.baseRefName) {
return retain('protected-or-unknown-source');
}
const { execGh } = await import('./github.js');
const repository = await execGh(['repo', 'view', `${target.host}/${target.owner}/${target.repo}`, '--json', 'defaultBranchRef'],
undefined, { cwd: dir, env }).then(value => safeJSONParse(value, null), () => null);
const defaultBranch = repository?.defaultBranchRef?.name;
if (typeof defaultBranch !== 'string' || !defaultBranch) return retain('default-branch-unverified');
if (branch === defaultBranch) return retain('protected-default-source');
// forgeAuth only mints a new environment for a successfully resolved
// github.com account. A matched account plus ambient GH_TOKEN is not proof.
if (host !== 'github.com' || !account || env === process.env || !env?.GH_TOKEN) {
return retain('account-bound-push-unavailable');
}
const ref = `refs/heads/${branch}`;
const valid = await execGitSafe(['check-ref-format', ref], dir);
if (valid.exitCode !== 0) return retain('invalid-source-ref');
const urls = await execGitSafe(['remote', 'get-url', '--push', '--all', 'origin'], dir);
const pushUrls = urls.stdout.trim().split('\n').filter(Boolean);
if (urls.exitCode !== 0 || pushUrls.length !== 1) return retain('push-target-ambiguous');
const { parseGitRemoteUrl } = await import('../lib/gitRemote.js');
const remote = parseGitRemoteUrl(pushUrls[0]);
if (!remote || remote.host.toLowerCase() !== target.host.toLowerCase()
|| `${remote.owner}/${remote.repo}`.toLowerCase() !== fullName) return retain('push-target-mismatch');
// SSH keys and embedded credentials can select a different identity from
// the merge token. Keep those sources for explicit owner cleanup.
if (!/^https:\/\/[^@/]+\//i.test(pushUrls[0])) return retain('account-bound-push-unavailable');
// Capture the URL rather than re-resolving a remote name at write time. The
// lease compares the server's actual ref, never a stale tracking branch.
const deletion = await execGitSafe(['-c', 'credential.helper=', '-c', 'credential.helper=!gh auth git-credential',
'-c', 'core.askPass=', 'push', `--force-with-lease=${ref}:${expectedHeadSha}`, '--', pushUrls[0], `:${ref}`], dir,
{ env: { ...env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', SSH_ASKPASS: '', GH_PROMPT_DISABLED: '1' } });
if (deletion.exitCode !== 0) return retain('remote-delete-failed-or-uncertain');
return { deleted: true, branch };
}
/**
* Request a Copilot code review on a GitHub PR. The reviewer login MUST include
* the `[bot]` suffix or GitHub returns 422 "must be a collaborator". GitLab has
* no equivalent — this is a GitHub-only no-op there, signaled with
* `{ success: true, skipped: true }` so callers can treat it as a successful
* non-event rather than a real failure (avoiding spurious warnings/notifications
* on GitLab MRs).
*
* @param {string} dir - Working directory used to resolve gh auth
* @param {string} prUrl - PR URL returned by createPR
* @returns {Promise<{success: boolean, skipped?: boolean, error?: string}>}
*/
export async function requestCopilotReview(dir, prUrl) {
const parsed = parsePullRequestUrl(prUrl);
if (!parsed) return { success: false, error: `unparseable PR URL: ${prUrl}` };
// Decide forge from the PR URL itself — that's the authoritative signal of where
// the review request needs to go. Falling back to the repo's `origin` (via
// resolveForgeForRepo) is wrong when `dir` isn't a parseable repo, or when the
// repo origin disagrees with the PR URL (e.g. GitLab MR URL reached via a
// mirror/fork on github.com). Non-GitHub PR URLs short-circuit as a successful
// skip so cleanupAgentWorktree doesn't emit a warning for every GitLab MR.
if (detectForgeCli(parsed.host) !== 'gh') return { success: true, skipped: true };
const { cli, env } = await resolveForgeForRepo(dir);
// Repo-side resolution might still come back non-gh (e.g. dir is empty/malformed
// and resolveForgeForRepo returned a glab host). Belt and suspenders: skip rather
// than try to talk to gh with the wrong env.
if (cli !== 'gh') return { success: true, skipped: true };
// Target the same GitHub instance the PR lives on. Without --hostname, gh uses
// its current default host, which is wrong for GHES installs or when the user
// has multiple gh hosts configured. github.com is gh's implicit default so we
// only need to set it explicitly for non-default hosts.
const args = ['api'];
if (parsed.host && parsed.host !== 'github.com') {
args.push('--hostname', parsed.host);
}
args.push(
`repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}/requested_reviewers`,
'-X', 'POST',
'-f', 'reviewers[]=copilot-pull-request-reviewer[bot]'
);
try {
const output = await execForgeCli('gh', args, dir, env);
if (output === null) return { success: false, error: 'gh command failed or timed out' };
return { success: true };
} catch (err) {
return { success: false, error: err.message || 'gh command failed' };
}
}
/**
* Generate a rich PR description from the agent's output summary.
* Prefers explicit final-response segments, then the tail of agent output,
* stripping tool-call artifacts and keeping only the meaningful explanation
* of what was implemented (new APIs, UI elements, behaviors, etc.).
* Falls back to commit messages when no agent output is available.
* @param {string} dir - Working directory (repo root)
* @param {string} baseBranch - Base branch (e.g., 'main')
* @param {string} headBranch - Head branch (agent's branch)
* @param {string} agentOutput - Raw agent output text
* @returns {Promise<string>} Formatted PR body
*/
export async function generatePRDescription(dir, baseBranch, headBranch, agentOutput, securityScan, securityScanControl) {
const summary = extractAgentSummary(agentOutput);
const prefix = `Automated PR created by PortOS Chief of Staff.\n\n${securityScanPRDisclosure(securityScan, securityScanControl)}`;
if (summary) {
return `${prefix}## Summary\n\n${summary}`;
}
// Fallback: build from commit messages when no usable agent output
const comparison = await getBranchComparison(dir, baseBranch, headBranch).catch(() => null);
if (comparison?.commits?.length) {
const commitLines = comparison.commits.map(c => `- ${c.message}`).join('\n');
return `${prefix}## Changes\n\n${commitLines}`;
}
return prefix.trimEnd();
}
/**
* Suggest a concise PR title from the branch's commits, falling back to a
* provided text (typically the task description).
*
* The CoS task description is often verbose user prose (e.g. "on the
* settings/backup page, we should have a button to run the backup. Also, we
* should show default exclusions"). Commit subjects on the branch are far
* better titles because the agent wrote them as conventional-commit summaries
* of the actual change.
*
* Picks the OLDEST commit on the branch when present — for multi-commit
* branches that include follow-ups like "address review:" or "/simplify"
* cleanups, the first commit is usually the main feature/fix.
*
* @param {string} dir - Working directory (repo root or worktree)
* @param {string} baseBranch - Base branch the PR will target
* @param {string} headBranch - Branch the PR will be opened from
* @param {string} fallbackText - Used when no commits are found
* @returns {Promise<string>} PR title (<= 100 chars)
*/
export async function suggestPRTitle(dir, baseBranch, headBranch, fallbackText) {
assertSafeRef(baseBranch);
assertSafeRef(headBranch);
// A worktree's local main may lag the PR target by many merged commits.
// Compare against the fetched remote target, matching what the forge reviews.
const remoteBase = `refs/remotes/origin/${baseBranch}`;
const remote = await execGitSafe(['rev-parse', '--verify', remoteBase], dir);
const baseRef = remote.exitCode === 0 ? remoteBase : baseBranch;
const log = await execGitSafe(
['log', '--reverse', '--no-merges', '--format=%s', `${baseRef}..${headBranch}`], dir,
);
// Subjects are plain text: JSON interpolation drops titles containing quotes.
const subject = log.stdout?.split(/\r?\n/).find(line => line.trim())?.trim();
if (subject) return subject.substring(0, 100);
const firstLine = (fallbackText || '').split(/[\r\n]/).find(l => l.trim()) || '';
return firstLine.trim().substring(0, 100) || 'CoS automated task';
}
export async function getDefaultBranch(dir, { allowRemote = true, strict = false } = {}) {
const symRef = await execGitSafe(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], dir);
if (symRef.stdout?.trim()) {
const branch = symRef.stdout.trim().replace(/^origin\//, '');
// Verify the ref actually exists (origin/HEAD could be stale)
const verify = await execGitSafe(['rev-parse', '--verify', `refs/remotes/origin/${branch}`], dir);
if (verify.exitCode === 0 || verify.stdout?.trim()) return branch;
}
// origin/HEAD not set locally — ask the remote (best-effort, short timeout)
if (allowRemote) {
await execGitSafe(['remote', 'set-head', 'origin', '--auto'], dir, { timeout: 5000 });
const symRef2 = await execGitSafe(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], dir);
if (symRef2.stdout?.trim()) {
const branch2 = symRef2.stdout.trim().replace(/^origin\//, '');
const verify2 = await execGitSafe(['rev-parse', '--verify', `refs/remotes/origin/${branch2}`], dir);
if (verify2.exitCode === 0 || verify2.stdout?.trim()) return branch2;
}
}
// Fall back to local branch detection
const result = await execGitSafe(['branch', '--list'], dir);
const branches = (result.stdout || '').trim().split('\n').map(b => b.replace(/^\*?\s+/, '')).filter(Boolean);
if (branches.includes('main')) return 'main';
if (branches.includes('master')) return 'master';
// Callers that are about to mutate a checkout need a known default branch;
// falling back to whichever feature branch happens to be checked out would
// make a remote-sync operation treat that branch as the canonical target.
if (strict) return null;
// Last resort: use the currently checked-out branch
const head = await execGitSafe(['rev-parse', '--abbrev-ref', 'HEAD'], dir);
if (head.stdout?.trim() && head.stdout.trim() !== 'HEAD') {
return head.stdout.trim();
}
return null;
}
/**
* Detect base and dev branches from local refs (origin/HEAD, local branch list).
* Does not contact the remote — safe for latency-sensitive request paths.
* Computes the branch list once and reuses it for both base and dev detection.
* @returns {{ baseBranch: string|null, devBranch: string|null }}
*/
export async function getRepoBranches(dir) {
// Check origin/HEAD first (fast, local-only)
const symRef = await execGitSafe(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], dir);
let baseBranch = null;
if (symRef.stdout?.trim()) {
const candidate = symRef.stdout.trim().replace(/^origin\//, '');
// Verify the ref actually exists (origin/HEAD could be stale)
const verify = await execGitSafe(['rev-parse', '--verify', `refs/remotes/origin/${candidate}`], dir);
if (verify.exitCode === 0 || verify.stdout?.trim()) {
baseBranch = candidate;
}
}
// Get local branches once — reused for both base fallback and dev detection
const result = await execGitSafe(['branch', '--list'], dir);
const branches = (result.stdout || '').trim().split('\n').map(b => b.replace(/^\*?\s+/, '')).filter(Boolean);
if (!baseBranch) {
if (branches.includes('main')) baseBranch = 'main';
else if (branches.includes('master')) baseBranch = 'master';
}
return {
baseBranch,
devBranch: branches.includes('dev') ? 'dev' : branches.includes('develop') ? 'develop' : null
};
}
/**
* Get the set of local branch names merged into the default branch.
* Prefers the local default-branch ref, but falls back to the remote-tracking
* ref when there's no local branch by that name (single-branch clones,
* feature-only worktrees) — otherwise `git branch --merged <defaultBranch>`
* fails and every branch silently reports unmerged.
* @param {string} dir - Working directory
* @param {string} defaultBranch - Default branch name (e.g. "main")
* @returns {Promise<Set<string>>}
*/
async function getLocalMergedBranchNames(dir, defaultBranch) {
let result = await execGit(
['branch', '--merged', defaultBranch, '--format=%(refname:short)'],
dir,
{ ignoreExitCode: true }
);
if (result.exitCode !== 0) {
result = await execGit(
['branch', '--merged', `origin/${defaultBranch}`, '--format=%(refname:short)'],
dir,
{ ignoreExitCode: true }
);
}
return new Set(result.stdout.trim().split('\n').filter(Boolean));
}
/**
* Get all local branches with tracking info
* @returns {Promise<Array<{name: string, current: boolean, tracking: string|null, ahead: number, behind: number, isDefault: boolean, merged: boolean, worktree: boolean}>>}
*/
export async function getBranches(dir, { strict = false } = {}) {
// Get branches with verbose info (includes tracking)
const [result, { baseBranch }, worktreeBranches] = await Promise.all([
execGit(
['branch', '-vv', '--format=%(HEAD)|%(refname:short)|%(upstream:short)|%(upstream:track)'],
dir,
{ ignoreExitCode: true }
),
getRepoBranches(dir),
getWorktreeBranches(dir)
]);
if (strict && result.exitCode !== 0) {
throw new Error(result.stderr || `git branch -vv failed with exit code ${result.exitCode}`);
}
const defaultBranch = baseBranch || 'main';
const protectedSet = new Set(PROTECTED_BRANCHES);
protectedSet.add(defaultBranch);
const mergedSet = await getLocalMergedBranchNames(dir, defaultBranch);
return result.stdout.trim().split('\n').filter(Boolean)
.map(parseBranchVerboseLine)
.map(b => ({
...b,
isDefault: b.name === defaultBranch,
// A branch checked out in another worktree can't be `git branch -d`'d, so
// cleanup-merged skips it. Flag it so the UI doesn't advertise it as
// deletable (otherwise the "Clean N merged" button promises deletions the
// server correctly refuses, and the user gets "No merged branches to clean up").
worktree: !b.current && worktreeBranches.has(b.name),
merged: !b.current && !protectedSet.has(b.name) && mergedSet.has(b.name)
}));
}
/**
* Pull changes from remote for current branch
*/
export async function pull(dir) {
return withCheckoutMutation(dir, () => pullAdmitted(dir));
}
async function pullAdmitted(dir) {
const result = await execGit(['pull', '--rebase', '--autostash'], dir).catch((err) => {
// A rebase killed mid-flight can leave the repo in a rebase-in-progress
// state, so a lock found here is cleared but NOT retried — blindly
// re-running `pull --rebase` could stack onto that abandoned state instead
// of starting clean. Surface it so the next explicit pull starts fresh.
const clearedLock = clearStaleGitLock(err.message);
if (clearedLock) {
throw new Error(
`Cleared an abandoned git lock (${clearedLock}) left by a killed git process. `
+ `The pull did not run — retry it now that the lock is clear.`
);
}
throw err;
});
return { success: true, output: result.stdout + result.stderr };
}
function gitResultOutput(result) {
return `${result.stdout || ''}${result.stderr || ''}`;
}
function gitResultError(result, fallback) {
return [result.stdout, result.stderr]
.map(stream => (stream || '').trim())
.filter(Boolean)
.join('\n') || fallback;
}
/**
* Run a pinned-submodule command, retrying once when Git names an abandoned
* lock. `git submodule update` is safe to retry after that specific rescue:
* unlike a pull/rebase, it has no partially-applied history operation to stack
* on top of.
*/
async function runPinnedSubmoduleCommand(args, dir) {
let result = await execGitSafe(args, dir, { timeout: SUBMODULE_UPDATE_TIMEOUT_MS });
if (result.exitCode === 0 || !clearStaleGitLock(result.stderr)) return result;
result = await execGitSafe(args, dir, { timeout: SUBMODULE_UPDATE_TIMEOUT_MS });
return result;
}
/**
* Synchronize submodule URLs and check out the commits pinned by the parent.
* The parent gitlink is the version contract; `--remote` is intentionally not
* used because a managed-app update must not consume an unreviewed submodule
* head. Kept private because callers need the parent update transaction, not
* an independently exposed submodule workflow.
*/
async function updatePinnedSubmodules(dir) {
const sync = await runPinnedSubmoduleCommand(['submodule', 'sync', '--recursive'], dir);
if (sync.exitCode !== 0) {
return {
success: false,
output: gitResultOutput(sync),
error: gitResultError(sync, 'could not synchronize submodule metadata')
};
}
const update = await runPinnedSubmoduleCommand(['submodule', 'update', '--init', '--recursive'], dir);
return {
success: update.exitCode === 0,
output: gitResultOutput(update),
...(update.exitCode === 0
? {}
: { error: gitResultError(update, 'could not update pinned submodules') })
};
}
/**
* Move a managed application's primary checkout onto origin's default branch
* and bring it up to date. Non-destructive: nothing is discarded, and local
* work is preserved either by carrying it across the checkout or by git's own
* `--autostash` (which re-applies it after the rebase).
*
* Order of attempts:
* 1. Reconcile submodules to the current parent gitlinks, so an interrupted
* earlier update cannot make the pull fail on a stale submodule checkout.
* 2. `pull --ff-only` — the common case, no rewrite, no stash.
* 3. `pull --rebase --autostash` — the checkout is dirty and/or the local
* branch has diverged from origin. This is what "Update App" used to
* refuse outright with DIRTY_WORKTREE.
* 4. Reconcile submodules again after the parent pull, because a new commit
* can advance a gitlink while leaving its worktree at the old commit.
* 5. On conflict, preserve the operation and report `conflict: true`
* so an agent or operator can inspect it and explicitly recover.
*
* A zero exit status is NOT enough to call the rebase clean. `--autostash`
* re-applies the stash after the rebase finishes, and git only WARNS when that
* apply conflicts ("Applying autostash resulted in conflicts") — the pull still
* exits 0 with conflict markers in the working tree. So a successful rebase is
* confirmed by asking git for unmerged paths, not by its exit code; otherwise
* the caller would build and restart on a broken tree. There is no rebase to
* abort in that state (it already completed).
*
* @param {string} dir
* @returns {Promise<{success: boolean, branch: string, output: string, conflict: boolean, rebased?: boolean, error?: string}>}
*/
export async function updateDefaultBranch(dir) {
return withCheckoutMutation(dir, () => updateDefaultBranchAdmitted(dir));
}
// Process-local lanes cannot exclude CLI actors or their conflict-resolution
// edits, even within a rebase this request started. Git has no conditional abort.
const SHARED_REBASE_RECOVERY = 'Git operation state and any autostash were preserved. Inspect git status and save any conflict-resolution edits before explicitly continuing or aborting the operation.';
async function updateDefaultBranchAdmitted(dir) {
if (await rebaseInProgress(dir)) {
return { success: false, branch: await getBranch(dir), output: '', conflict: true, error: `A rebase is already in progress. ${SHARED_REBASE_RECOVERY}` };
}
// Git splits a failed pull across both streams — fetch progress and rebase
// instructions on stderr, the `CONFLICT (content): …` lines naming the files
// on stdout — so an `stderr || stdout` pick would drop exactly the part that
// says WHICH files collided from the UI message and the CoS task's context.
const bothStreams = (result, fallback) => [result.stdout, result.stderr]
.map(stream => (stream || '').trim())
.filter(Boolean)
.join('\n') || fallback;
// A killed `fetch` can leave a shared ref lock (`refs/remotes/origin/*.lock`,
// `packed-refs.lock`) that every worktree of this repo shares. `fetch` is
// idempotent, so this uses the same clear-and-retry-once shape as
// `updateSubmodule` rather than surfacing a permanent, confusing failure.
await execGit(['fetch', 'origin'], dir).catch(async (err) => {
if (!clearStaleGitLock(err.message)) throw err;
await execGit(['fetch', 'origin'], dir);
});
const runtimeBranch = await execGit(['config', '--get', 'portos.runtimeBranch'], dir, { ignoreExitCode: true });
const branch = runtimeBranch.stdout.trim() || await getDefaultBranch(dir, { strict: true });
if (!branch) throw new ServerError('could not determine origin default branch', { status: 400, code: 'NO_DEFAULT_BRANCH' });
const currentBranch = await getBranch(dir);
let output = '';
const reconcileSubmodules = async () => {
const submodules = await updatePinnedSubmodules(dir);
output += submodules.output;
return submodules.success ? null : {
success: false,
branch,
output,
conflict: true,
error: `pinned submodule update failed: ${submodules.error}`
};
};
const currentSubmoduleError = await reconcileSubmodules();
if (currentSubmoduleError) return currentSubmoduleError;
if (currentBranch !== branch) {
// Uncommitted changes ride along when they don't collide with the target
// branch; when they do, git refuses and we route that to the conflict path
// instead of throwing an unactionable error at the UI.
const checkout = await execGit(['checkout', branch], dir, { ignoreExitCode: true });
output += checkout.stdout + checkout.stderr;
if (checkout.exitCode !== 0) {
// Checkout can leave a partially-written index, so a lock found here is
// cleared but NOT retried — the next explicit attempt starts from a
// lock-free repo instead of racing this one.
const clearedLock = clearStaleGitLock(checkout.stderr);
return {
success: false,
branch,
output,
conflict: true,
error: clearedLock
? `Cleared an abandoned git lock (${clearedLock}) left by a killed git process. The checkout onto ${branch} did not run — retry the update now that the lock is clear.`
: bothStreams(checkout, `could not check out ${branch}`)
};
}
// Checking out the target branch can change the gitlinks without moving
// the submodule worktrees. Reconcile that target tree before pulling so a
// previous branch's submodule checkout cannot make the pull fail.
const targetSubmoduleError = await reconcileSubmodules();
if (targetSubmoduleError) return targetSubmoduleError;
}
const fastForward = await execGit(['pull', '--ff-only', 'origin', branch], dir, { ignoreExitCode: true });
output += fastForward.stdout + fastForward.stderr;
if (await rebaseInProgress(dir) || fastForward.terminated) {
return { success: false, branch, output, conflict: true, error: `${bothStreams(fastForward, 'Pull did not complete.')} ${SHARED_REBASE_RECOVERY}` };
}
if (fastForward.exitCode === 0) {
const submoduleError = await reconcileSubmodules();
if (submoduleError) return submoduleError;
return { success: true, branch, output, conflict: false };
}
const fastForwardLock = clearStaleGitLock(fastForward.stderr);
if (fastForwardLock) {
return {
success: false,
branch,
output,
conflict: true,
error: `Cleared an abandoned git lock (${fastForwardLock}) left by a killed git process. The fast-forward pull did not run — retry the update now that the lock is clear.`
};
}
const rebase = await execGit(['pull', '--rebase', '--autostash', 'origin', branch], dir, { ignoreExitCode: true });
output += rebase.stdout + rebase.stderr;
const activeRebase = await rebaseInProgress(dir);
if (rebase.exitCode === 0 && !rebase.terminated && !activeRebase) {
const unmerged = await execGit(['diff', '--name-only', '--diff-filter=U'], dir, { ignoreExitCode: true });
const conflicted = unmerged.stdout.trim().split('\n').filter(Boolean);
if (unmerged.exitCode === 0 && !unmerged.terminated && !conflicted.length) {
const submoduleError = await reconcileSubmodules();
if (submoduleError) return submoduleError;
return { success: true, branch, output, conflict: false, rebased: true };
}
return {
success: false,
branch,
output,
conflict: true,
error: conflicted.length
? `re-applying the autostashed local changes conflicted in: ${conflicted.join(', ')}`
: bothStreams(unmerged, 'Could not verify local changes after rebasing.')
};
}
const rebaseLock = Number.isInteger(rebase.exitCode) && !rebase.terminated && !activeRebase
&& clearStaleGitLock(rebase.stderr);
return {
success: false,
branch,
output,
conflict: true,
error: rebaseLock
? `Cleared an abandoned git lock (${rebaseLock}). The rebase did not complete; inspect the checkout before retrying. ${SHARED_REBASE_RECOVERY}`
: `${bothStreams(rebase, `rebase onto origin/${branch} did not complete`)} ${SHARED_REBASE_RECOVERY}`
};
}
/**
* Sync branch - pull then push
*/
export async function syncBranch(dir, branch = null) {
return withCheckoutMutation(dir, () => syncBranchAdmitted(dir, branch), { exclusive: true });
}
/** Reconcile local default-branch commits with origin without stashing or force-pushing. */
export async function rebaseAndPushDefaultBranch(dir) {
return withCheckoutMutation(dir, () => rebaseAndPushDefaultBranchAdmitted(dir), { exclusive: true });
}
async function rebaseAndPushDefaultBranchAdmitted(dir) {
const refused = (error) => ({ success: false, pulled: false, pushed: false, error });
const gitDir = (await execGit(['rev-parse', '--absolute-git-dir'], dir)).stdout.trim();
if ([...SEQUENCER_STATE.map(([marker]) => marker), 'MERGE_HEAD', 'sequencer']
.some(marker => existsSync(join(gitDir, marker)))) {
return refused('Finish the Git operation already in progress before rebasing and pushing.');
}
const branch = await getBranch(dir);
const defaultBranch = await getDefaultBranch(dir, { strict: true });
if (!defaultBranch || branch !== defaultBranch) {
return refused('Check out the default branch before rebasing and pushing.');
}
assertSafeRef(branch);
if (!(await getStatus(dir)).clean) {
return refused('Commit or stash local changes before rebasing and pushing.');
}
await fetchOrigin(dir);
if (await getBranch(dir) !== branch || !(await getStatus(dir)).clean) {
return refused('The checkout changed while fetching. Check its branch and local changes before retrying.');
}
const remoteRef = `refs/remotes/origin/${branch}`;
const counts = await execGit(['rev-list', '--left-right', '--count', `HEAD...${remoteRef}`], dir);
if (!(Number(counts.stdout.trim().split(/\s+/)[0]) > 0)) {
return refused('The default branch has no local commits ahead of origin.');
}
const localMerges = await execGit(['rev-list', '--merges', `${remoteRef}..HEAD`], dir);
if (localMerges.stdout.trim()) {
return refused('Local history contains merge commits. Reconcile these with an agent or in the terminal to preserve merge resolutions; nothing was rebased or pushed.');
}
// Fetch + rebase is the explicit-origin equivalent of pull --rebase. Avoid
// pull.ff / upstream configuration and never move dirty work via autostash.
const rebased = await execGit(['rebase', '--no-autostash', remoteRef], dir, { ignoreExitCode: true });
if (rebased.exitCode !== 0 || rebased.terminated || await rebaseInProgress(dir)) {
return refused(`${gitResultError(rebased, 'Rebase did not complete.')} ${SHARED_REBASE_RECOVERY} Nothing was pushed.`);
}
if (await getBranch(dir) !== branch) return refused('The checked-out branch changed; nothing was pushed.');
const verifiedHead = (await execGit(['rev-parse', '--verify', `refs/heads/${branch}^{commit}`], dir)).stdout.trim();
if (!/^[a-f0-9]{40,64}$/.test(verifiedHead)) return refused('Could not verify the default-branch commit; nothing was pushed.');
const pushed = await execGit(['push', 'origin', `${verifiedHead}:refs/heads/${branch}`], dir, { ignoreExitCode: true });
return {
success: pushed.exitCode === 0,
branch,
pulled: true,
pushed: pushed.exitCode === 0,
output: gitResultOutput(rebased) + gitResultOutput(pushed),
error: pushed.exitCode === 0 ? null : gitResultError(pushed, 'Push failed; rebased commits remain local.'),
};
}
async function syncBranchAdmitted(dir, branch = null) {
if (branch) assertSafeRef(branch);
const refused = error => ({ success: false, pulled: false, pushed: false, error });
const gitDir = (await execGit(['rev-parse', '--absolute-git-dir'], dir)).stdout.trim();
const operationInProgress = () => [...SEQUENCER_STATE.map(([marker]) => marker), 'MERGE_HEAD', 'sequencer']
.some(marker => existsSync(join(gitDir, marker)));
if (operationInProgress()) {
return refused('Finish the Git operation already in progress before syncing.');
}
const currentBranch = branch || await getBranch(dir);
const pullResult = await execGit(['pull', '--rebase', '--autostash', 'origin', currentBranch], dir, { ignoreExitCode: true });
if (pullResult.exitCode !== 0 || pullResult.terminated) {
// The API lane does not exclude Git CLI actors. Even a request-specific
// reflog proves only who started a rebase, not who now owns its edits. Git
// has no generation-conditioned abort, so a check followed by --abort can
// still discard another actor's work. Preserve shared-checkout recovery.
const settled = Number.isInteger(pullResult.exitCode) && !pullResult.terminated;
const activeOperation = operationInProgress();
const clearedLock = settled && !activeOperation && clearStaleGitLock(pullResult.stderr);
const recovery = activeOperation
? ' Git operation state and any autostash were preserved. Inspect git status and save any conflict-resolution edits before explicitly continuing or aborting the operation; nothing was pushed.' : '';
const error = clearedLock
? `Cleared an abandoned git lock (${clearedLock}) left by a killed git process. The pull did not complete — inspect the checkout before retrying the sync.`
: gitResultError(pullResult, 'Pull failed; nothing was pushed.');
return refused(`${error}${recovery}`);
}
// A separate actor can start an operation during pull, including one with
// staged resolutions that lets pull exit zero. It still must not be pushed.
if (operationInProgress()) {
return refused('A Git operation is in progress after pulling. Its state and edits were preserved; inspect git status and finish that operation before syncing again. Nothing was pushed.');
}
// Autostash reapplication can conflict after Git has exited successfully.
// Preserve the conflicted files and Git's saved stash rather than aborting
// an already-completed rebase or attempting to apply/drop the stash again.
const unmerged = await execGit(['diff', '--name-only', '--diff-filter=U'], dir, { ignoreExitCode: true });
if (unmerged.exitCode !== 0) {
return refused(gitResultError(unmerged, 'Could not verify local changes after pulling; nothing was pushed.'));
}
if (unmerged.stdout.trim()) {
return refused(`Re-applying autostashed local changes conflicted in: ${unmerged.stdout.trim()}. Resolve the conflicts before syncing again; nothing was pushed.`);
}
const pushResult = await execGit(['push', 'origin', currentBranch], dir, { ignoreExitCode: true });
const pushSuccess = pushResult.exitCode === 0 && !pushResult.terminated;
return {
success: pushSuccess,
pulled: true,
pushed: pushSuccess,
output: gitResultOutput(pullResult) + gitResultOutput(pushResult),
error: pushSuccess ? null : gitResultError(pushResult, 'Push failed; local commits remain in the checkout.')
};
}
/**
* Check if a .changelog/ directory exists in the repo
*/
export function hasChangelogDir(dir) {
return existsSync(join(dir, '.changelog'));
}
/**
* Ensure workspace has the latest code from origin before agent work begins.
* Scripted pull: fetch + fast-forward merge on the dev/default branch.
* If the working tree is dirty, skips the pull — other agents may own those
* uncommitted changes and stashing could interfere with their work.
*
* @param {string} dir - Git repository directory
* @returns {{ success: boolean, branch: string, conflict: boolean, error: string|null }}
*/
// One pre-task pull per checkout at a time. Several agents for the same app
// prep concurrently; serialize them so a later request sees any stopped
// operation at preflight instead of launching Git on top of it.
const ensureLatestTails = new Map();
export async function ensureLatest(dir) {
const gitCheck = await execGit(['rev-parse', '--is-inside-work-tree'], dir, { ignoreExitCode: true });
if (gitCheck.exitCode === 128
&& /^fatal: not a git repository \(or any (?:of the parent directories|parent up to mount point)/im.test(gitCheck.stderr || '')) {
return { success: true, branch: null, conflict: false, error: null, skipped: 'not-a-repo' };
}
if (gitCheck.exitCode !== 0 || gitCheck.stdout.trim() !== 'true') {
throw new Error(gitCheck.stderr?.trim() || 'Could not verify Git working tree');
}
return withCheckoutMutation(dir, () => ensureLatestAdmitted(dir));
}
function ensureLatestAdmitted(dir) {
const key = resolve(dir);
const prev = ensureLatestTails.get(key) || Promise.resolve();
const run = prev.catch(() => {}).then(() => ensureLatestUnserialized(dir));
const tail = run.catch(() => {});
ensureLatestTails.set(key, tail);
tail.then(() => { if (ensureLatestTails.get(key) === tail) ensureLatestTails.delete(key); });
return run;
}
async function rebaseInProgress(dir) {
for (const name of ['rebase-merge', 'rebase-apply']) {
const res = await execGit(['rev-parse', '--git-path', name], dir, { ignoreExitCode: true });
const gitPath = res.stdout?.trim();
if (gitPath && existsSync(resolve(dir, gitPath))) return true;
}
return false;
}
// git's rebase failure output is a multi-line block of `hint:` advice with a
// `\r`-overwritten progress line glued in front — the part worth logging is
// the error plus the CONFLICT lines naming the files.
function summarizeRebaseConflict({ stdout = '', stderr = '' } = {}) {
const lines = `${stdout}\n${stderr}`.split(/[\r\n]+/).map(l => l.trim()).filter(Boolean);
const keep = lines.filter(l => /^(CONFLICT|error:|fatal:)/.test(l));
return (keep.length ? keep : lines.filter(l => !l.startsWith('hint:')).slice(0, 3)).join('; ') || 'rebase failed';
}
async function ensureLatestUnserialized(dir) {
// A rebase left in progress is someone's (a person's, or an agent resolving a
// conflict) — never start a second one on top of it, and never abort it.
if (await rebaseInProgress(dir)) {
const branch = await getBranch(dir).catch(() => null);
return {
success: false,
branch,
conflict: true,
error: 'a rebase is already in progress in this checkout; finish it (git rebase --continue) or abort it (git rebase --abort)'
};
}
const currentBranch = await getBranch(dir).catch(() => null);
if (!currentBranch) return { success: true, branch: null, conflict: false, error: null, skipped: 'no-branch' };
// Check for remote — no remote means nothing to pull
const remote = await getRemote(dir).catch(() => null);
if (!remote?.origin) return { success: true, branch: currentBranch, conflict: false, error: null, skipped: 'no-remote' };
// Fetch latest refs from origin. Idempotent, so an abandoned lock (left by a
// killed git process, shared by every worktree of this repo) is cleared and
// retried once rather than reported as a permanent failure.
let fetchResult = await execGit(['fetch', 'origin'], dir, { ignoreExitCode: true });
if (fetchResult.stderr?.includes('fatal') && clearStaleGitLock(fetchResult.stderr)) {
fetchResult = await execGit(['fetch', 'origin'], dir, { ignoreExitCode: true });
}
if (fetchResult.stderr?.includes('fatal')) {
return { success: false, branch: currentBranch, conflict: false, error: `fetch failed: ${fetchResult.stderr}` };
}
recordFetchSuccess(dir);
// Check if remote tracking branch exists
const remoteRef = await execGit(['rev-parse', `origin/${currentBranch}`], dir, { ignoreExitCode: true });
if (remoteRef.stderr?.includes('unknown revision')) {
return { success: true, branch: currentBranch, conflict: false, error: null, skipped: 'no-remote-tracking' };
}
// Check if already up to date
const localHead = (await execGit(['rev-parse', 'HEAD'], dir)).stdout.trim();
const remoteHead = remoteRef.stdout.trim();
if (localHead === remoteHead) {
return { success: true, branch: currentBranch, conflict: false, error: null, upToDate: true };
}
// Skip pull if working tree is dirty — other agents may own those changes
const status = await getStatus(dir).catch(() => ({ clean: true }));
if (!status.clean) {
return { success: true, branch: currentBranch, conflict: false, error: null, skipped: 'dirty-working-tree' };
}
// Try fast-forward merge first (safest — no rewrite)
const mergeResult = await execGit(['merge', '--ff-only', `origin/${currentBranch}`], dir, { ignoreExitCode: true });
if (await rebaseInProgress(dir) || mergeResult.terminated) {
return { success: false, branch: currentBranch, conflict: true, error: `${summarizeRebaseConflict(mergeResult)} ${SHARED_REBASE_RECOVERY}` };
}
const mergeOk = mergeResult.exitCode === 0;
if (mergeOk) {
return { success: true, branch: currentBranch, conflict: false, error: null };
}
// A lock found here is cleared but NOT retried — a blind retry could race a
// still-write-in-progress index. Surface it so the next explicit attempt
// starts from a lock-free repo.
const mergeLock = clearStaleGitLock(mergeResult.stderr);
if (mergeLock) {
return {
success: false,
branch: currentBranch,
conflict: true,
error: `Cleared an abandoned git lock (${mergeLock}) left by a killed git process. The fast-forward merge did not complete — retry now that the lock is clear.`
};
}
// Fast-forward failed — local branch has diverged. Try rebase.
const rebaseResult = await execGit(['rebase', `origin/${currentBranch}`], dir, { ignoreExitCode: true });
const activeRebase = await rebaseInProgress(dir);
if (rebaseResult.exitCode !== 0 || rebaseResult.terminated || activeRebase) {
const rebaseLock = Number.isInteger(rebaseResult.exitCode) && !rebaseResult.terminated && !activeRebase
&& clearStaleGitLock(rebaseResult.stderr);
return {
success: false,
branch: currentBranch,
conflict: true,
error: rebaseLock
? `Cleared an abandoned git lock (${rebaseLock}). The rebase did not complete; inspect the checkout before retrying. ${SHARED_REBASE_RECOVERY}`
: `branch ${currentBranch} has diverged from origin and rebase did not complete: ${summarizeRebaseConflict(rebaseResult)} ${SHARED_REBASE_RECOVERY}`
};
}
return { success: true, branch: currentBranch, conflict: false, error: null };
}
/**
* Get remote branches with merge status relative to the default branch.
* Returns branches that exist on origin, indicating whether each has been
* fully merged into the default branch and whether a local copy exists.
*/
export async function getRemoteBranches(dir, { force = false } = {}) {
// Fetch latest refs if forced or not fresh within window
if (force || !isFetchFresh(dir)) {
const { withCheckoutPublication } = await import('../lib/checkoutRetirementAdmission.js');
const freshen = () => withCheckoutPublication(dir, async () => {
if (activeFetches.has(dir)) {
await activeFetches.get(dir);
} else {
const fetchPromise = execGit(['fetch', 'origin', '--prune'], dir, { ignoreExitCode: true })
.then(res => {
if (res.exitCode === 0 || isBenignConcurrentFetchRefRace(res.stderr || res.stdout || '')) {
recordFetchSuccess(dir);
}
return res;
})
.finally(() => {
activeFetches.delete(dir);
});
activeFetches.set(dir, fetchPromise);
await fetchPromise;
}
});
if (force) {
await freshen();
} else {
await freshen().catch(error => {
if (error?.code === 'CHECKOUT_RETIREMENT_RESERVED' || error?.message === 'checkout-retirement-reserved') return null;
throw error;
});
}
}
// Detect default branch
const { baseBranch } = await getRepoBranches(dir);
const defaultBranch = baseBranch || 'main';
// Get all remote branches
const result = await execGit(
['branch', '-r', '--format=%(refname:short)|%(committerdate:iso8601)|%(authorname)'],
dir,
{ ignoreExitCode: true }
);
// Get merged remote branches relative to default branch
const mergedResult = await execGit(
['branch', '-r', '--merged', `origin/${defaultBranch}`, '--format=%(refname:short)'],
dir,
{ ignoreExitCode: true }
);
const mergedSet = new Set(mergedResult.stdout.trim().split('\n').filter(Boolean));
// Get local branches for cross-reference
const localResult = await execGit(['branch', '--format=%(refname:short)'], dir, { ignoreExitCode: true });
const localSet = new Set(localResult.stdout.trim().split('\n').filter(Boolean));
const remoteBranches = result.stdout.trim().split('\n').filter(Boolean)
.map(line => {
const [fullRef, date, author] = line.split('|');
// Only include refs from origin remote
if (!fullRef.startsWith('origin/')) return null;
// Strip "origin/" prefix
const name = fullRef.replace(/^origin\//, '');
// Skip HEAD pointer and refs without a branch name (bare remote name)
if (name === 'HEAD' || fullRef.includes('HEAD') || !name) return null;
return {
name,
fullRef,
merged: mergedSet.has(fullRef),
hasLocal: localSet.has(name),
lastCommitDate: date?.trim() || null,
author: author?.trim() || null,
isDefault: name === defaultBranch
};
})
.filter(Boolean);
return { branches: remoteBranches, defaultBranch };
}
/**
* Get branch names that are checked out in git worktrees.
* Delegates to worktreeManager's listWorktrees to avoid duplicating porcelain parsing.
* @param {string} dir - Working directory (main repo root)
* @returns {Promise<Set<string>>} Set of branch names in active worktrees
*/
export async function getWorktreeBranches(dir) {
const worktrees = await listWorktrees(dir).catch(() => []);
return new Set(
worktrees
.filter(wt => wt.branch)
.map(wt => wt.branch.replace(/^refs\/heads\//, ''))
);
}
/**
* Delete a branch locally, remotely, or both.
* @param {string} dir - Working directory
* @param {string} branchName - Branch name to delete
* @param {object} options
* @param {boolean} options.local - Delete local branch
* @param {boolean} options.remote - Delete remote branch
* @param {Set<string>} options.excludeBranches - Additional branches to protect (e.g., active agent branches)
*/
export async function deleteBranch(dir, branchName, options = {}) {
return withCheckoutMutation(dir, () => deleteBranchAdmitted(dir, branchName, options));
}
async function deleteBranchAdmitted(dir, branchName, { local = false, remote = false, excludeBranches } = {}) {
const { baseBranch } = await getRepoBranches(dir);
const protectedSet = new Set(PROTECTED_BRANCHES);
if (baseBranch) protectedSet.add(baseBranch);
if (protectedSet.has(branchName)) {
throw new Error(`Cannot delete protected branch: ${branchName}`);
}
// Safety: don't delete the current branch
const currentBranch = await getBranch(dir);
if (currentBranch === branchName && local) {
throw new Error(`Cannot delete the currently checked-out branch: ${branchName}`);
}
// Safety: don't delete branches checked out in worktrees (active agent workspaces)
if (local) {
const worktreeBranches = await getWorktreeBranches(dir);
if (worktreeBranches.has(branchName)) {
throw new Error(`Cannot delete branch checked out in a worktree: ${branchName}`);
}
}
// Safety: don't delete branches explicitly excluded (e.g., active CoS agent branches)
if (excludeBranches?.has(branchName)) {
throw new Error(`Cannot delete branch in active use by an agent: ${branchName}`);
}
const opts = { ignoreExitCode: true };
const [localResult, remoteResult] = await Promise.all([
local ? execGitSafe(['branch', '-D', branchName], dir, opts) : null,
remote ? execGitSafe(['push', 'origin', '--delete', branchName], dir, opts) : null
]);
const results = {};
if (localResult) {
results.local = localResult.exitCode === 0
? 'deleted'
: localResult.stderr?.includes('not found') ? 'not found' : `failed: ${localResult.stderr?.trim()}`;
}
if (remoteResult) {
results.remote = remoteResult.exitCode === 0
? 'deleted'
: remoteResult.stderr?.includes('not found') || remoteResult.stderr?.includes('does not exist')
? 'not found'
: `failed: ${remoteResult.stderr?.trim()}`;
}
return { branch: branchName, results };
}
/**
* Merge a branch into the current branch.
* Uses --no-ff to always create a merge commit for traceability.
* @param {string} dir - Working directory
* @param {string} branchName - Branch to merge into current
* @returns {Promise<{success: boolean, output: string}>}
*/
export async function mergeBranch(dir, branchName) {
return withCheckoutMutation(dir, () => mergeBranchAdmitted(dir, branchName));
}
async function mergeBranchAdmitted(dir, branchName) {
assertSafeRef(branchName);
const result = await execGit(['merge', '--no-ff', branchName], dir);
return { success: true, output: (result.stdout + result.stderr).trim() };
}
/**
* True means the merge probes found evidence; false means they did not establish
* it, including missing inputs, self-comparison, unresolved refs, and probe failures.
*
* - Normal / ff / no-ff merge: the branch tip becomes reachable from target, so
* `git merge-base --is-ancestor` settles it immediately.
* - Rebase-and-merge replays the branch commits as new SHAs; the original tip is
* not an ancestor, so we ask `git cherry` whether each branch commit has a
* patch-equivalent commit in target. `git cherry` prints "- <sha>" when an
* equivalent exists upstream and "+ <sha>" when it does not, so an all-"-"
* result means the branch was replayed.
* - Squash merge: the branch's commits are collapsed into a single NEW commit on
* target, so individual commits usually are not patch-equivalent. We synthesize
* a commit holding the branch's full tree on top of the merge-base and ask
* `git cherry` whether target already contains that combined patch.
*
* Fails CLOSED: any git error (or unresolvable ref) returns false, so a detection
* failure can never authorize a delete. This is the gate the merged-worktree
* reaper relies on — see reapMergedWorktrees in worktreeManager.js.
*
* @param {string} dir - Repo working directory
* @param {string} branch - Branch whose work we're checking (local name or ref)
* @param {string} target - Branch it should be merged into (e.g. 'main')
* @returns {Promise<boolean>}
*/
export async function hasBranchMergeEvidence(dir, branch, target) {
// Equal immutable commits prove inclusion; equal symbolic branch names do
// not prove that a feature branch landed anywhere else.
if (!branch || !target || (branch === target && !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(branch))) return false;
const env = { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_LAZY_FETCH: '1' };
// An inherited writer's quarantine/object override must not redirect a
// repository inspection away from this checkout's own common object store.
delete env.GIT_OBJECT_DIRECTORY;
const readOptions = { ignoreExitCode: true, env };
const resolve = (ref) => execGit(['rev-parse', '--verify', `${ref}^{commit}`], dir, readOptions)
.then(r => (r.exitCode === 0 ? r.stdout.trim() : null))
.catch(() => null);
const [branchSha, targetSha] = await Promise.all([resolve(branch), resolve(target)]);
if (!branchSha || !targetSha) return false;
// Fast path: branch tip already reachable from target (normal / ff / no-ff merge,
// or the branch carries no unique commits).
const ancestor = await execGit(['merge-base', '--is-ancestor', branchSha, targetSha], dir, readOptions)
.then(r => r.exitCode === 0)
.catch(() => false);
if (ancestor) return true;
// Rebase/cherry-pick path: does target contain every branch commit as an
// individual patch-equivalent commit?
const individualCherry = await execGit(['cherry', targetSha, branchSha], dir, readOptions)
.then(r => r.exitCode === 0 ? r.stdout.trim() : null)
.catch(() => null);
if (individualCherry === null) return false;
if (individualCherry !== '' && individualCherry.split('\n').every(line => line.startsWith('-'))) {
return true;
}
// Squash path: does target already contain the branch's combined patch?
const mergeBase = await execGit(['merge-base', targetSha, branchSha], dir, readOptions)
.then(r => (r.exitCode === 0 ? r.stdout.trim() : null))
.catch(() => null);
if (!mergeBase) return false;
// No unique work beyond the merge base → nothing would be lost.
if (mergeBase === branchSha) return true;
const branchTree = await execGit(['rev-parse', `${branchSha}^{tree}`], dir, readOptions)
.then(r => (r.exitCode === 0 ? r.stdout.trim() : null))
.catch(() => null);
if (!branchTree) return false;
// Polling must not add dangling synthetic commits to the shared object store:
// that invalidates an otherwise stable preservation snapshot. Both commands
// use a private object directory with the original store as a read alternate.
return probeCombinedPatch(dir, branchTree, mergeBase, targetSha, readOptions).catch(() => false);
}
async function probeCombinedPatch(dir, branchTree, mergeBase, targetSha, readOptions) {
const objects = await execGit(['rev-parse', '--path-format=absolute', '--git-path', 'objects'], dir, readOptions);
if (objects.exitCode !== 0 || !objects.stdout.trim()) return false;
const scratch = await mkdtemp(join(tmpdir(), 'portos-merge-probe-'));
try {
const options = { ...readOptions, env: { ...readOptions.env,
GIT_OBJECT_DIRECTORY: scratch,
// Git accepts C-quoted entries, including paths containing the platform
// list separator, quotes or backslashes. Existing alternates remain valid.
GIT_ALTERNATE_OBJECT_DIRECTORIES: [JSON.stringify(objects.stdout.trim()),
readOptions.env.GIT_ALTERNATE_OBJECT_DIRECTORIES].filter(Boolean).join(delimiter)
} };
// Preserve configured-identity behavior: an unavailable identity fails closed.
const synthetic = await execGit(['commit-tree', branchTree, '-p', mergeBase, '-m', 'merged-check-probe'], dir, options);
if (synthetic.exitCode !== 0 || !synthetic.stdout.trim()) return false;
const result = await execGit(['cherry', targetSha, synthetic.stdout.trim()], dir, options);
if (result.exitCode !== 0) return false;
const lines = result.stdout.trim();
return lines === '' || lines.split('\n').every(line => line.startsWith('-'));
} finally {
// Only this invocation's exclusively created scratch directory is removed.
await rmGuarded(scratch, { recursive: true, force: true, maxRetries: 3 });
}
}
// Backward-compatible name for callers using the original evidence predicate.
export const isBranchMergedInto = hasBranchMergeEvidence;
/**
* Checkout a remote branch that doesn't exist locally.
* Creates a local tracking branch from the remote ref.
* @param {string} dir - Working directory
* @param {string} branchName - Branch name (without origin/ prefix)
* @returns {Promise<{success: boolean, branch: string}>}
*/
export async function checkoutRemoteBranch(dir, branchName) {
return withCheckoutMutation(dir, () => checkoutRemoteBranchAdmitted(dir, branchName));
}
async function checkoutRemoteBranchAdmitted(dir, branchName) {
assertSafeRef(branchName);
await execGit(['checkout', '-b', branchName, `origin/${branchName}`], dir);
return { success: true, branch: branchName };
}
/**
* How many entries in raw `git status --porcelain` output a hard reset would
* actually destroy — i.e. everything except untracked (`??`) files, which
* survive because nothing here runs `git clean`.
* @param {string} porcelain - Raw `git status --porcelain` stdout
* @returns {number}
*/
export function countDiscardable(porcelain) {
return String(porcelain || '')
.split('\n')
.filter(line => line.trim() && !line.startsWith('??'))
.length;
}
/**
* Sequencer state files a forced checkout does NOT clear, mapped to the command
* that drops each. `--quit` rather than `--abort`: abort rewinds to the
* pre-operation HEAD, which is the very state a reset is discarding, while
* `--quit` removes the bookkeeping and leaves the tree the checkout just
* restored alone. (`MERGE_HEAD` is absent here on purpose — a plain conflicted
* merge IS cleared by `checkout --force`.)
*/
const SEQUENCER_STATE = [
['rebase-merge', 'rebase'],
['rebase-apply', 'rebase'],
['CHERRY_PICK_HEAD', 'cherry-pick'],
['REVERT_HEAD', 'revert']
];
/**
* Drop any half-finished rebase / cherry-pick / revert.
*
* Without this a checkout left mid-rebase still reports "You are currently
* rebasing" after the reset, and every later `git rebase` in that repo dies on
* "there is already a rebase-merge directory" until someone deletes it by hand
* — so the reset would report success while leaving the repo in exactly the
* stuck state it is advertised to fix.
*
* @param {string} dir - Repo root
* @param {string} gitDirPath - Absolute path to the repo's git dir
* @returns {Promise<string[]>} - The operations that were cleared
*/
async function clearSequencerState(dir, gitDirPath) {
const stuck = [...new Set(
SEQUENCER_STATE
.filter(([marker]) => existsSync(join(gitDirPath, marker)))
.map(([, command]) => command)
)];
for (const command of stuck) {
await execGitSafe([command, '--quit'], dir);
}
return stuck;
}
/**
* The id of a running CoS agent whose workspace IS `dir`, or null when none is.
* Paths are compared after `resolve` so a trailing slash or a `..` segment on
* either side doesn't let a live run slip past the check.
*
* Imported lazily: `services/git.js` is on the boot path and the agent
* lifecycle module is not, so a static import would drag agent state into
* every consumer of a git helper.
* @param {string} dir - Repo root to check
* @returns {Promise<string|null>} - Agent id, or null
*/
export async function findActiveAgentInWorkspace(dir, { includePaused = false, failClosed = false } = {}) {
const { getAgents } = await import('./cosAgentLifecycle.js').catch((err) => {
if (failClosed) throw err;
return { getAgents: null };
});
if (!getAgents) {
if (failClosed) throw new Error('could not load the CoS agent registry');
return null;
}
const agents = await getAgents().catch((err) => {
if (failClosed) throw err;
return [];
});
const target = resolve(dir);
const busy = agents.find(agent =>
(agent.status === 'running' || (includePaused && agent.status === 'paused'))
&& agent.metadata?.workspacePath
&& resolve(agent.metadata.workspacePath) === target
);
return busy?.id || null;
}
/**
* Throw away every local change and put the checkout back on origin's default
* branch, exactly as the remote has it. The escape hatch for a checkout that
* has drifted — a lockfile a local toolchain keeps rewriting, a half-finished
* edit, a branch left behind by an interrupted operation.
*
* Deliberately narrower than "make it look like a fresh clone":
* - Tracked modifications and local commits on the default branch go away;
* `previousHead` comes back in the result so `git reset --hard <sha>`
* recovers them (the commits stay in the reflog for git's gc window).
* - Untracked files stay. There is no `git clean` here: a checkout's
* untracked set is where `.env` files, build output, and scratch work live,
* and losing those is not recoverable from a reflog. `discardedFiles`
* excludes them for the same reason — it counts what was destroyed, not
* what was merely dirty.
* - Other local branches are untouched — this moves the default branch only.
* - A half-finished rebase / cherry-pick / revert IS cleared (`clearedOperations`
* names which), because leaving one behind is the stuck state this exists
* to escape.
*
* A fetch failure is not fatal: the reset falls back to the cached
* `origin/<default>` ref so an offline machine can still get back to a known
* state, and `fetched: false` says the target may be behind the remote.
*
* @param {string} dir - Working directory (a repo root, not a linked worktree)
* @returns {Promise<{success: boolean, branch: string, previousBranch: string|null,
* previousHead: string|null, discardedFiles: number, clearedOperations: string[],
* fetched: boolean}>}
*/
export async function resetToDefaultBranch(dir) {
return withCheckoutMutation(dir, () => resetToDefaultBranchAdmitted(dir));
}
async function resetToDefaultBranchAdmitted(dir) {
// A linked worktree cannot check out the default branch — the main checkout
// already holds it — and hard-resetting one would discard an agent's
// in-flight work on a branch that is not the default anyway. Fail with a
// reason instead of surfacing git's "already checked out" further down. The
// two dirs differ only in a linked worktree, and rev-parse answers both flags
// in one spawn, one value per line.
const dirs = await execGitSafe(['rev-parse', '--git-dir', '--git-common-dir'], dir);
const [gitDir, commonDir] = dirs.stdout.trim().split('\n').map(line => line.trim());
if (gitDir && commonDir && gitDir !== commonDir) {
throw new ServerError('cannot reset a linked worktree — run this on the main checkout', {
status: 400,
code: 'WORKTREE_RESET_REFUSED'
});
}
// A CoS agent without a worktree works directly in the checkout it was given
// (agentWorkspacePrep only isolates when the task asks for it), so resetting
// under a running one destroys tracked edits it is still producing and moves
// HEAD beneath a live process. primaryCheckoutGuard.js already treats
// `reset --hard` on the primary checkout as a decision a human makes
// deliberately — this keeps that decision from landing on top of a run.
const busyAgent = await findActiveAgentInWorkspace(dir);
if (busyAgent) {
throw new ServerError(
`a CoS agent (${busyAgent}) is running in this checkout — stop it before resetting`,
{ status: 409, code: 'AGENT_RUNNING' }
);
}
const fetched = await fetchOrigin(dir).then(() => true).catch(() => false);
// A failed fetch already told us the remote is unreachable, so skip
// getDefaultBranch's `remote set-head` probe rather than stall on its timeout.
const branch = await getDefaultBranch(dir, { allowRemote: fetched });
if (!branch) {
throw new ServerError('could not determine the default branch', { status: 400, code: 'NO_DEFAULT_BRANCH' });
}
const target = `origin/${branch}`;
const targetRef = await execGitSafe(['rev-parse', '--verify', `refs/remotes/${target}`], dir);
if (targetRef.exitCode !== 0 || !targetRef.stdout.trim()) {
throw new ServerError(`no ${target} ref to reset to`, { status: 400, code: 'NO_REMOTE_REF' });
}
// `rev-parse` takes both spellings of HEAD in one spawn: the sha, then the
// branch name. `getStatusPorcelain` is the cheap half of `getStatus` — a
// line count is all the caller needs, not a parsed per-file breakdown.
const [headBefore, dirty] = await Promise.all([
execGitSafe(['rev-parse', 'HEAD', '--abbrev-ref', 'HEAD'], dir),
getStatusPorcelain(dir).catch(() => '')
]);
// `|| null` rather than a destructuring default: on a repo with no commits
// rev-parse prints nothing, `''.split('\n')` is `['']`, and a default only
// fires on `undefined` — so the caller would get `''` where the contract (and
// the client's `if (result.previousHead)` recovery hint) says null.
const [head, branchName] = headBefore.stdout.trim().split('\n').map(line => line.trim());
const previousHead = head || null;
const previousBranch = branchName || null;
// A half-finished rebase/cherry-pick survives the checkout below, so drop it
// first — otherwise the reset "succeeds" into a repo that still refuses every
// later rebase.
const clearedOperations = await clearSequencerState(dir, resolve(dir, gitDir || '.git'));
// `checkout --force -B` is the whole operation: `-B` repoints the local branch
// at the remote ref and `--force` resets index AND working tree to it, so a
// trailing `reset --hard` would re-walk every tracked file to change nothing.
await execGit(['checkout', '--force', '-B', branch, target], dir);
return {
success: true,
branch,
previousBranch,
previousHead,
// Untracked files (`??`) are the ones this reset deliberately KEEPS, so
// counting them would tell the user more was destroyed than actually was —
// directly contradicting the "keeps untracked files" line the confirm
// dialog shows two rows above this number.
discardedFiles: countDiscardable(dirty),
clearedOperations,
fetched
};
}
// Prose for each `reapMergedWorktrees` skip slug, so `skipped` says WHY a merged
// branch survived rather than only that it did. An unlisted slug falls back to
// the plain "it's in a worktree" phrasing.
const WORKTREE_HOLD_REASONS = {
uncommitted: 'worktree has uncommitted changes',
unmerged: 'worktree has unmerged commits',
'status-failed': 'worktree status could not be read',
'worktree-locked': 'worktree is locked',
'worktree-active-agent': 'worktree is in use by a running agent',
'worktree-agent-liveness-unknown': 'agent liveness unknown',
'worktree-human-claim': 'worktree is a claimed session',
'remove-failed': 'worktree removal failed and the checkout is still present'
};
const worktreeHoldReason = (reason) => WORKTREE_HOLD_REASONS[reason] || reason || 'checked out in a worktree';
async function prepareRemoteRetirement(dir, defaultBranch) {
// A remote name resolves differently for fetch and push (and can change
// while cleanup awaits). Require one identical endpoint and use its captured
// URL for every read/write. Equivalent-looking aliases need explicit review.
const [fetchUrls, pushUrls] = await Promise.all([
execGitSafe(['remote', 'get-url', '--all', 'origin'], dir),
execGitSafe(['remote', 'get-url', '--push', '--all', 'origin'], dir),
]);
const fetchEndpoints = fetchUrls.stdout.trim().split(/\r?\n/).filter(Boolean);
const pushEndpoints = pushUrls.stdout.trim().split(/\r?\n/).filter(Boolean);
if (fetchUrls.exitCode !== 0 || pushUrls.exitCode !== 0
|| fetchEndpoints.length !== 1 || pushEndpoints.length !== 1
|| fetchEndpoints[0] !== pushEndpoints[0]) {
return { reason: 'fetch and push must identify one identical remote endpoint' };
}
const remoteUrl = fetchEndpoints[0];
// origin/HEAD and a caller's remembered default can outlive a forge default
// change. Establish the advertised default before any refresh or retirement.
const advertised = await execGitSafe(['ls-remote', '--symref', '--', remoteUrl, 'HEAD'], dir);
const symrefs = advertised.stdout.split(/\r?\n/).filter(line => line.startsWith('ref: '));
const defaultMatch = symrefs.length === 1 ? /^ref: (refs\/heads\/.+)\tHEAD$/.exec(symrefs[0]) : null;
if (advertised.exitCode !== 0 || !defaultMatch) return { reason: 'default-branch-unverified' };
if (defaultMatch[1] !== `refs/heads/${defaultBranch}`) return { reason: 'default-branch-changed' };
// A stale local default or an unsuccessful fetch never authorizes deletion.
const fetched = await execGitSafe(['fetch', '--prune', '--', remoteUrl, '+refs/heads/*:refs/remotes/origin/*'], dir, { ignoreExitCode: true });
if (fetched.exitCode !== 0) return { reason: 'remote default could not be refreshed' };
const targetRef = `refs/heads/${defaultBranch}`;
const targetHead = await execGitSafe(['ls-remote', '--heads', '--', remoteUrl, targetRef], dir);
const targetMatch = /^([a-f0-9]{40}(?:[a-f0-9]{24})?)\t(.+)$/.exec(targetHead.stdout.trim());
const targetSha = targetMatch?.[1];
if (targetHead.exitCode !== 0 || targetMatch?.[2] !== targetRef
|| (await execGitSafe(['rev-parse', '--verify', `${targetSha}^{commit}`], dir)).exitCode !== 0) {
return { reason: 'remote default head unavailable' };
}
return { remoteUrl, targetSha, defaultBranch };
}
// Fresh local refs, upstream aliases and actual holders all retain the remote
// recovery ref. Re-read immediately before the leased push, inside the same
// ownership fence used to register managed claims.
async function remoteRetirementLocalHold(dir, name) {
const [refs, trees] = await Promise.all([
execGitSafe(['for-each-ref', '--format=%(refname:short)%09%(upstream:short)', 'refs/heads/'], dir),
listWorktrees(dir).catch(() => null),
]);
if (refs.exitCode !== 0 || !Array.isArray(trees)) return 'local ownership unavailable';
if (refs.stdout.split(/\r?\n/).some(line => {
const [branch, upstream] = line.split('\t');
return branch === name || upstream === `origin/${name}`;
})) return 'local branch or upstream still exists';
if (trees.some(tree => tree.branch === `refs/heads/${name}` || tree.branch === name)) return 'checked out in a worktree';
return null;
}
async function retireMergedRemoteHead(dir, name, context, { excludeBranches } = {}) {
const { withClaimOwnershipLock, readClaimOwnershipAgents } = await import('./cosClaimOwnershipState.js');
const { claimCheckoutOwnerReason } = await import('../lib/claimContinuation.js');
const { readBranchCompletionHold } = await import('./branchCompletionPolicy.js');
if (PROTECTED_BRANCHES.includes(name) || name === context.defaultBranch || name === 'HEAD') return { reason: 'protected branch' };
const ref = `refs/heads/${name}`;
if ((await execGitSafe(['check-ref-format', ref], dir)).exitCode !== 0) return { reason: 'invalid branch name' };
return withClaimOwnershipLock(async () => {
const hold = async tip => {
const exclusions = typeof excludeBranches === 'function' ? await excludeBranches() : excludeBranches;
if (exclusions?.has(name)) return 'used by an active agent';
const agents = await readClaimOwnershipAgents();
const owner = claimCheckoutOwnerReason({ branchName: name, holderPath: null, sourceWorkspace: dir, agents });
if (owner) return owner;
if (tip) {
const policy = await readBranchCompletionHold({ repoPath: dir, branch: name, tip, retirement: true });
if (policy) return policy;
}
return remoteRetirementLocalHold(dir, name);
};
const initialHold = await hold();
if (initialHold) return { reason: initialHold };
const head = await execGitSafe(['ls-remote', '--heads', '--', context.remoteUrl, ref], dir);
const match = /^([a-f0-9]{40}(?:[a-f0-9]{24})?)\t(.+)$/.exec(head.stdout.trim());
if (head.exitCode !== 0 || !match || match[2] !== ref) return { reason: 'head unavailable or already removed' };
if (!await hasBranchMergeEvidence(dir, match[1], context.targetSha)) return { reason: 'current head is not merged' };
const finalHold = await hold(match[1]);
if (finalHold) return { reason: finalHold };
const removed = await execGitSafe(['push', `--force-with-lease=${ref}:${match[1]}`, '--', context.remoteUrl, `:${ref}`], dir, { ignoreExitCode: true });
return removed.exitCode === 0 ? { deleted: true } : { reason: 'head changed or deletion failed', failed: true };
});
}
/** Retire only explicitly selected remote candidates, preserving any fresh local
* ownership. The candidate scan grants no deletion authority: endpoint, default,
* current head, merge proof and claim/completion gates are established here.
*/
export async function deleteMergedRemoteBranches(dir, names, { defaultBranch, excludeBranches } = {}) {
const selected = [...new Set(names)];
if (!selected.length) return { deleted: [], skipped: [] };
const base = defaultBranch || (await getRepoBranches(dir)).baseBranch || 'main';
const context = await prepareRemoteRetirement(dir, base);
if (context.reason) return { deleted: [], skipped: selected.map(branch => ({ branch, reason: context.reason })) };
const deleted = [];
const skipped = [];
for (const branch of selected) {
const result = await retireMergedRemoteHead(dir, branch, context, { excludeBranches });
if (result.deleted) deleted.push(branch);
else skipped.push({ branch, reason: result.reason });
}
return { deleted, skipped };
}
/**
* Delete all merged branches (local and remote) in one operation.
* Skips the `PROTECTED_BRANCHES` set (see `../lib/gitArgs.js`), the current branch,
* and any explicitly excluded branches.
*
* Shares the reconciler's fresh ownership, merge, archival and retirement gates.
* Local and remote deletion are pinned to observed heads. Retained work is
* returned with its specific reason; the UI's merged flag is never authority.
*
* @param {string} dir - Working directory
* @param {object} options
* @param {Set<string>} options.excludeBranches - Additional branches to protect (e.g., active agent branches)
* @param {Set<string>} [options.activeAgentIds] - CoS agent ids whose worktrees must survive. Anything
* but a Set (the default) reads as "liveness unknown" and holds every `agent-*` worktree.
* @returns {Promise<{deleted: Array<{name: string, local: string, remote: string, worktree?: string}>, skipped: string[], defaultBranch: string}>}
*/
export async function deleteMergedBranches(dir, { excludeBranches, activeAgentIds = null } = {}) {
const { cleanupMerged } = await import('./branchReconcile.js');
const { baseBranch } = await getRepoBranches(dir);
const defaultBranch = baseBranch || 'main';
const protectedSet = new Set([...PROTECTED_BRANCHES, defaultBranch]);
const skipped = [];
const records = new Map();
const context = await prepareRemoteRetirement(dir, defaultBranch);
if (context.reason) return { deleted: [], skipped: [`cleanup (${context.reason})`], defaultBranch };
const { resolveRetirementApp } = await import('./retirementAppScope.js');
const scope = await resolveRetirementApp(dir);
if (!scope.app) return { deleted: [], skipped: [`cleanup (${scope.reason})`], defaultBranch };
const { targetSha } = context;
const branches = await execGitSafe(['branch', '--format=%(refname:short)'], dir, { ignoreExitCode: true });
if (branches.exitCode !== 0) return { deleted: [], skipped: ['cleanup (local branches unavailable)'], defaultBranch };
const local = new Set(branches.stdout.trim().split('\n').filter(Boolean));
const remote = await execGitSafe(['branch', '-r', '--format=%(refname:short)'], dir, { ignoreExitCode: true });
if (remote.exitCode !== 0) return { deleted: [], skipped: ['cleanup (remote merge evidence unavailable)'], defaultBranch };
const remoteNames = remote.stdout.trim().split('\n').filter(ref => ref.startsWith('origin/')).map(ref => ref.slice(7));
const names = new Set([...local, ...remoteNames]);
for (const name of names) {
if (protectedSet.has(name) || name === 'HEAD') continue;
const exclusions = typeof excludeBranches === 'function' ? await excludeBranches() : excludeBranches;
if (exclusions?.has(name)) { skipped.push(`${name} (used by an active agent)`); continue; }
const record = { name, local: null, remote: null };
records.set(name, record);
if (local.has(name)) {
const retired = await cleanupMerged(scope.app.repoPath, targetSha, [{ branch: name }], {
activeAgentIds, appId: scope.app.id, forgeAccount: scope.app.forgeAccount ?? null,
});
if (retired.cleaned.includes(name)) record.local = 'deleted';
else {
for (const hold of retired.skipped) skipped.push(`${name} (local: ${worktreeHoldReason(hold.reason)}${hold.detail ? `: ${hold.detail}` : ''})`);
// Retention is a whole-branch outcome. In particular, archive failure
// must leave both the checkout and its remote recovery ref intact.
continue;
}
}
if (!remoteNames.includes(name)) continue;
const removed = await retireMergedRemoteHead(dir, name, context, { excludeBranches });
if (removed.deleted) record.remote = 'deleted';
else {
if (removed.failed) record.remote = 'failed';
skipped.push(`${name} (remote: ${removed.reason})`);
}
}
return { deleted: [...records.values()].filter(row => row.local === 'deleted' || row.remote === 'deleted'), skipped, defaultBranch };
}
/**
* Get comprehensive git info
*/
export async function getGitInfo(dir) {
const [isGit, branch, status, commits, diffStats, remote, repoBranches] = await Promise.all([
isRepo(dir),
getBranch(dir).catch(() => null),
getStatus(dir).catch(() => ({ clean: true, files: [] })),
getCommits(dir, 5).catch(() => []),
getDiffStats(dir).catch(() => ({ files: 0, insertions: 0, deletions: 0 })),
getRemote(dir).catch(() => null),
getRepoBranches(dir).catch(() => ({ baseBranch: null, devBranch: null }))
]);
const originComparison = branch && branch !== 'HEAD'
? await execGit(['rev-list', '--left-right', '--count', `HEAD...refs/remotes/origin/${branch}`], dir)
.then(({ stdout }) => {
const [ahead, behind] = stdout.trim().split(/\s+/).map(Number);
return Number.isFinite(ahead) && Number.isFinite(behind) ? { ahead, behind } : null;
}).catch(() => null)
: null;
return {
isRepo: isGit,
branch,
status,
recentCommits: commits,
diffStats,
remote,
originComparison,
baseBranch: repoBranches.baseBranch,
devBranch: repoBranches.devBranch,
hasChangelog: hasChangelogDir(dir)
};
}