@bridge4dev/runner 0.11.0 → 0.22.1

package/dist/gitops.js

@@ -8,6 +8,12 @@ const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
 const MERGE_TIMEOUT_MS = 60_000;
 const DIFF_CAP_BYTES = 200_000;
+/**
+ * git's own name for «nothing», and the only thing a repository without a
+ * single commit can be diffed against. Constant in every git repository ever
+ * made — it is the SHA-1 of the empty tree object.
+ */
+const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 /**
  * Global git switches every call in this module needs.
  *
@@ -31,12 +37,85 @@ async function git(cwd, ...args) {
     });
     return stdout.replace(/\n$/, '');
 }
-/** Pathspec magic characters — refused outright, belt to the flag's braces. */
-const PATHSPEC_MAGIC = /[*?[\]]|^:/;
+/**
+ * Pathspec magic, as far as it can still exist.
+ *
+ * `--literal-pathspecs` is on for every call in this file, which turns `*`,
+ * `?`, `[…]` and the `:(glob)` prefix into ordinary characters of a file name.
+ * That is why only the LEADING colon is refused here: it is the one form that
+ * could still be read as magic if the flag were ever dropped, and no path in a
+ * `git status` listing begins with one.
+ *
+ * The wider check this replaces (QA-110 M2) refused every name containing a
+ * bracket — which meant a Next.js dynamic route (`app/[slug]/page.tsx`, and
+ * there is one in this very repository) could not be staged, discarded or even
+ * diffed. A rule that blocks a legal file name is not a security control; it is
+ * a feature that does not work on a Tuesday.
+ */
+const PATHSPEC_MAGIC = /^:/;
+/**
+ * The stricter rule, kept for HISTORY reads only.
+ *
+ * Relaxing the working-tree check (above) is safe because those paths are
+ * checked against a `git status` listing that named them, and because
+ * `--literal-pathspecs` makes the characters ordinary. A history read has
+ * neither guard: it hands a path straight to `git show <sha> -- <path>` for a
+ * commit the caller chose. There a wildcard has no legitimate use, nobody is
+ * staging a Next.js route out of a 2019 commit, and the cost of being wrong is
+ * the whole commit printed into a browser (QA-105 MAJOR-1).
+ */
+const HISTORY_PATHSPEC_MAGIC = /[*?[\]]|^:/;
 function shortError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return maskString(message).slice(0, 500);
 }
+/**
+ * Put the workspace checkout back exactly as we found it.
+ *
+ * `reset --merge` is the polite form and needs a MERGE_HEAD, which
+ * `merge-recursive` never writes — so it can decline and leave the failed merge
+ * staged. The hard reset behind it is safe only because every caller verifies
+ * `status --porcelain` is empty before touching anything: there is nothing of
+ * the user's to lose, only our own half-finished merge.
+ */
+async function restoreCleanWorkspace(workspacePath, untrackedBefore) {
+    await git(workspacePath, 'reset', '--merge').catch(() => undefined);
+    const dirty = await git(workspacePath, 'status', '--porcelain').catch(() => '');
+    if (!dirty)
+        return;
+    // Tracked files go back to HEAD. `reset --hard` only rewrites what git
+    // tracks, so nobody's untracked work is at risk from this line.
+    await git(workspacePath, 'reset', '--hard', 'HEAD').catch(() => undefined);
+    // And then ONLY what this merge itself created.
+    //
+    // This used to be `git clean -fd`, justified by «every caller verified the
+    // tree was clean first, so there is nothing of the user's to lose». That
+    // reasoning is a snapshot pretending to be a lock. The project folder is
+    // shared — a person and their terminal agents write into it continuously —
+    // so between the check and the cleanup new untracked files appear, and
+    // `clean -fd` deleted them. On 2026-07-28 it destroyed a session's planning
+    // documents on a live project: hundreds of lines that existed nowhere else.
+    //
+    // A merge can leave untracked files behind (a file the branch adds, dropped
+    // in before the conflict), so something has to go. The list captured before
+    // the merge is what makes «ours» answerable: delete a path only if it was
+    // not there when we started.
+    const after = await git(workspacePath, 'status', '--porcelain').catch(() => '');
+    for (const path of porcelainPaths(after)) {
+        if (untrackedBefore.has(path))
+            continue;
+        await git(workspacePath, 'clean', '-fd', '--', path).catch(() => undefined);
+    }
+}
+/** Paths git does not track right now — the set a failed merge must not touch. */
+async function untrackedPaths(workspacePath) {
+    const raw = await git(workspacePath, 'status', '--porcelain').catch(() => '');
+    return new Set(porcelainPaths(raw));
+}
+/** `git merge-recursive` reports a conflict by exiting 1, quietly. */
+function exitedWithConflict(error) {
+    return error?.code === 1;
+}
 /**
  * True only for a genuine content conflict. `git merge --squash` also exits
  * non-zero for a dirty index, a refused overwrite or a failing hook — those
@@ -48,12 +127,125 @@ function isMergeConflict(error) {
     return /CONFLICT \(|Automatic merge failed|fix conflicts/i.test(output);
 }
 /**
- * The base the session will be applied onto: the branch the workspace repo is
- * currently on (its HEAD commit is what merge-base is computed against). If
- * the workspace somehow sits on the session branch itself, fall back to
- * main/master.
+ * The seven pairs that mean «git stopped, a human has to choose».
+ *
+ * Spelled out rather than guessed at with «either column is U», because `DD`
+ * and `AA` are conflicts without a single U in them, and treating those as an
+ * ordinary staged change would offer a Discard button that git refuses.
+ */
+const CONFLICT_PAIRS = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
+export function isConflictedEntry(entry) {
+    return CONFLICT_PAIRS.has(`${entry.index}${entry.worktree}`);
+}
+export function isStagedEntry(entry) {
+    return !isConflictedEntry(entry) && entry.index !== ' ' && entry.index !== '?';
+}
+export function isUnstagedEntry(entry) {
+    return !isConflictedEntry(entry) && entry.worktree !== ' ';
+}
+/** How many blocking paths travel to the panel; the count is always exact. */
+const WORKSPACE_DIRTY_SAMPLE = 20;
+/**
+ * Read the porcelain lines of the project folder into paths.
+ *
+ * Shared by the status call and by every guard, so «is it dirty» has exactly
+ * one answer in this file. Rename entries (`R  old -> new`) contribute the new
+ * path, matching how the worktree file list already reads them.
+ */
+function porcelainPaths(porcelain) {
+    return porcelain
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+        const raw = line.slice(3);
+        return raw.includes(' -> ') ? (raw.split(' -> ')[1] ?? raw) : raw;
+    });
+}
+/** How many working-tree entries travel to the panel; the count is exact. */
+const MAX_WORKING_ENTRIES = 1_000;
+/**
+ * `git status --porcelain=v1 -z`, parsed.
+ *
+ * NUL-separated and not line-separated on purpose: a file name may legally
+ * contain a newline, and with `core.quotePath=false` — which we set globally so
+ * Cyrillic paths stay readable — git no longer escapes it. Splitting that output
+ * on `\n` invents two entries out of one file, and the second one is a path that
+ * exists nowhere. `-z` is the only format that cannot be misread.
+ *
+ * A rename or a copy carries its ORIGINAL path as its own NUL-terminated token
+ * right after the entry, so the loop consumes two tokens for those.
+ */
+export function parsePorcelainZ(raw) {
+    const tokens = raw.split('\0');
+    const entries = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        // "XY path" — anything shorter is the trailing empty token, not an entry.
+        if (!token || token.length < 4)
+            continue;
+        const index = token.charAt(0);
+        const worktree = token.charAt(1);
+        const filePath = token.slice(3);
+        let origPath;
+        if (index === 'R' || index === 'C' || worktree === 'R' || worktree === 'C') {
+            i += 1;
+            origPath = tokens[i] || undefined;
+        }
+        if (!filePath)
+            continue;
+        entries.push({ path: filePath, index, worktree, ...(origPath ? { origPath } : {}) });
+    }
+    return entries;
+}
+/**
+ * The top of the checkout `cwd` belongs to.
+ *
+ * Every path in this file's source-control half is repo-root-relative, because
+ * that is what `git status --porcelain` prints and therefore what the panel
+ * sends back. Handing those to a `git add` that runs one directory deeper would
+ * stage the wrong files — or nothing at all — so all of them stand at the root.
+ */
+async function repoRoot(cwd) {
+    const top = await git(cwd, 'rev-parse', '--show-toplevel').catch(() => null);
+    return top || cwd;
+}
+/** Is a merge (or a pull that became one) waiting for a human right now? */
+async function hasMergeInProgress(root) {
+    const gitDir = await git(root, 'rev-parse', '--absolute-git-dir').catch(() => null);
+    if (!gitDir)
+        return false;
+    return fs.existsSync(path.join(gitDir, 'MERGE_HEAD'));
+}
+/** The paths git is waiting on, by name. */
+async function conflictedPaths(root) {
+    const raw = await git(root, 'diff', '--name-only', '--diff-filter=U', '-z').catch(() => '');
+    return raw.split('\0').filter(Boolean).slice(0, MAX_WORKING_ENTRIES);
+}
+/**
+ * The base the session forked from — and will be applied onto.
+ *
+ * Session 13 made this a RECORDED decision. Before, it was recomputed on every
+ * call as «whatever branch the project folder happens to be on», so checking a
+ * different branch out on the server silently moved the target of «Apply» for
+ * every session of that project. When the API supplies the base it was pinned
+ * with, that wins; the old guess stays as the fallback for sessions created
+ * before the column existed.
+ *
+ * A pinned base that no longer exists is reported rather than silently swapped:
+ * the caller has to be able to say «the branch you forked from is gone».
  */
-async function resolveBase(workspacePath, sessionBranch) {
+async function resolveBase(workspacePath, sessionBranch, pinnedBase) {
+    const safePinned = pinnedBase ? sanitizeBranch(pinnedBase) : null;
+    if (safePinned && safePinned !== sessionBranch) {
+        if (await branchExists(workspacePath, safePinned)) {
+            return { baseBranch: safePinned, baseRef: safePinned, pinned: true, baseMissing: false };
+        }
+        const guessed = await guessBase(workspacePath, sessionBranch);
+        return { ...guessed, pinned: false, baseMissing: true };
+    }
+    return { ...(await guessBase(workspacePath, sessionBranch)), pinned: false, baseMissing: false };
+}
+async function guessBase(workspacePath, sessionBranch) {
     const current = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
     if (current !== sessionBranch && current !== 'HEAD') {
         return { baseBranch: current, baseRef: current };
@@ -67,20 +259,130 @@ async function resolveBase(workspacePath, sessionBranch) {
     }
     throw new Error(`Cannot determine the base branch (workspace is on ${current})`);
 }
+/** How far apart two refs are, in one call: `[behind, ahead]`. */
+async function aheadBehind(cwd, baseRef, branchRef) {
+    const raw = await git(cwd, 'rev-list', '--left-right', '--count', `${baseRef}...${branchRef}`).catch(() => null);
+    if (raw === null)
+        return null;
+    const [behind, ahead] = raw.split(/\s+/).map((value) => Number(value));
+    if (!Number.isFinite(ahead) || !Number.isFinite(behind))
+        return null;
+    return { ahead: ahead ?? 0, behind: behind ?? 0 };
+}
+/**
+ * Commits on `branchRef` that are not reachable from `sinceSha` — and, when
+ * `excludeRef` is given, not reachable from the base either.
+ *
+ * Both options exist because of «Update from base» (QA-107). It merges the base
+ * INTO the session branch, so every commit the base contributed is newer than
+ * the last apply's `sinceSha`: without `excludeRef` the panel announced «12
+ * commits not in main» about main's own commits, and without `noMerges` it
+ * announced «1 commit» about the merge commit that brought them — bookkeeping,
+ * not work.
+ */
+async function countSince(cwd, sinceSha, branchRef, options = {}) {
+    if (!isCommitSha(sinceSha))
+        return null;
+    const raw = await git(cwd, 'rev-list', '--count', ...(options.noMerges ? ['--no-merges'] : []), `${sinceSha}..${branchRef}`, ...(options.excludeRef ? ['--not', options.excludeRef] : [])).catch(() => null);
+    if (raw === null)
+        return null;
+    const count = Number(raw);
+    return Number.isFinite(count) ? count : null;
+}
 /** Merge-base of the session worktree against the workspace's base branch. */
 async function mergeBase(worktreePath, baseRef) {
     return git(worktreePath, 'merge-base', 'HEAD', baseRef);
 }
-export async function gitStatus(worktreePath, workspacePath, sessionBranch) {
-    const { baseBranch, baseRef } = await resolveBase(workspacePath, sessionBranch);
-    const base = await mergeBase(worktreePath, baseRef);
+/**
+ * Statuses currently being computed, keyed by the question being asked (#114).
+ *
+ * `git_status` is not one command — it fans out to roughly fifteen git
+ * processes, two of them full working-tree scans. While the agent is building,
+ * that can take longer than the dashboard's polling period, and every poll that
+ * arrives meanwhile used to start the whole fan-out AGAIN on a machine that was
+ * already the reason the first one was slow. The pile-up was self-sustaining:
+ * more polls made it slower, and slower made more polls overlap.
+ *
+ * So overlapping callers SHARE the answer that is already on its way. No cache
+ * and no TTL — the entry lives exactly as long as the in-flight promise, so a
+ * caller can never be handed a status that was true a moment ago rather than
+ * now.
+ */
+const statusInFlight = new Map();
+/**
+ * How many times each working tree has been WRITTEN to by this runner.
+ *
+ * A shared promise answers about the tree as it was when the scan STARTED, not
+ * when it was joined — so a read issued after a write could join a scan that
+ * began before it and report the pre-write world (QA-111 M2). Every Source
+ * Control action invalidates and refetches immediately, which is exactly that
+ * shape: press `+`, and the file does not move to Staged until the next poll.
+ *
+ * So a write bumps the generation, and the generation is part of the key. Reads
+ * issued after it cannot share a scan started before it. Bumped AFTER the write
+ * finishes, deliberately: a read that arrives mid-write has nothing newer to be
+ * given, and starting a second scan against a tree being modified only spends
+ * the machine we are trying to spare.
+ */
+const treeGeneration = new Map();
+/** Record that this working tree has changed under us. */
+function bumpTreeGeneration(worktreePath) {
+    treeGeneration.set(worktreePath, (treeGeneration.get(worktreePath) ?? 0) + 1);
+}
+export function gitStatus(input) {
+    // Everything that changes the ANSWER, plus the generation of each tree read.
+    //
+    // `appliedBranchSha` / `pushedSha` stay in the key even though they only feed
+    // two derived counts (`newCommits`, `aheadOfPushed`) computed at the very
+    // end. Dropping them would let callers that pass different journal facts
+    // share one result — and one of them would be handed the other's numbers.
+    // The cost is that `applyCommitMessage` and `withVerifiedTrailer`, which ask
+    // without them, do not share with the panel's poll (QA-111 m5): a real but
+    // occasional extra fan-out, taken knowingly over a wrong count.
+    const key = JSON.stringify([
+        input.worktreePath,
+        input.workspacePath,
+        input.sessionBranch,
+        input.baseBranch ?? '',
+        input.appliedBranchSha ?? '',
+        input.pushedSha ?? '',
+        input.direct === true,
+        treeGeneration.get(input.worktreePath) ?? 0,
+        treeGeneration.get(input.workspacePath) ?? 0,
+    ]);
+    const running = statusInFlight.get(key);
+    if (running)
+        return running;
+    const started = computeGitStatus(input).finally(() => {
+        // Only ever delete our own entry: a slow status settling after a newer one
+        // took its place must not evict the newer one.
+        if (statusInFlight.get(key) === started)
+            statusInFlight.delete(key);
+    });
+    statusInFlight.set(key, started);
+    return started;
+}
+async function computeGitStatus(input) {
+    const { worktreePath, workspacePath, sessionBranch } = input;
+    const resolved = input.direct
+        ? { baseBranch: sessionBranch, baseRef: 'HEAD', pinned: false, baseMissing: false }
+        : await resolveBase(workspacePath, sessionBranch, input.baseBranch);
+    const { baseBranch, baseRef, pinned, baseMissing } = resolved;
+    const base = input.direct
+        ? // A repository with no commits yet has no HEAD to diff against. The empty
+            // tree is what git itself compares a first commit to, and it keeps the
+            // whole call working instead of failing the panel on a fresh `git init`.
+            await git(worktreePath, 'rev-parse', 'HEAD').catch(() => EMPTY_TREE_SHA)
+        : await mergeBase(worktreePath, baseRef);
     // One diff of the working tree against the merge-base covers both committed
     // and uncommitted changes — exactly what «Применить» would bring to main.
+    // Each piece degrades on its own: an unborn HEAD makes the commit count
+    // impossible without making the file list impossible.
     const [numstatRaw, nameStatusRaw, porcelainRaw, commitCountRaw] = await Promise.all([
-        git(worktreePath, 'diff', '--numstat', '-M', base),
-        git(worktreePath, 'diff', '--name-status', '-M', base),
+        git(worktreePath, 'diff', '--numstat', '-M', base).catch(() => ''),
+        git(worktreePath, 'diff', '--name-status', '-M', base).catch(() => ''),
         git(worktreePath, 'status', '--porcelain'),
-        git(worktreePath, 'rev-list', '--count', `${base}..HEAD`),
+        git(worktreePath, 'rev-list', '--count', `${base}..HEAD`).catch(() => '0'),
     ]);
     const numstat = new Map();
     for (const line of numstatRaw.split('\n').filter(Boolean)) {
@@ -126,14 +428,108 @@ export async function gitStatus(worktreePath, workspacePath, sessionBranch) {
         }
     }
     files.sort((a, b) => a.path.localeCompare(b.path));
+    // In DIRECT mode the session works IN the project folder, so the two paths
+    // are the same directory and half the questions below are the same question
+    // asked twice — including a full working-tree scan, which is the expensive
+    // one. Reusing the answer roughly halves the cost of a status on exactly the
+    // sessions where it was slow enough to time out (#114).
+    const sameTree = worktreePath === workspacePath;
+    // Everything below is read-only bookkeeping for the Git panel. Each piece
+    // degrades to null on its own rather than failing the whole status: a repo
+    // with a missing base still has to render its file list.
+    const [branchSha, baseSha, worktreeBranch, distance, workspacePorcelain, workingRaw, upstreamRaw, remotesRaw, mergeInProgress, workspaceMergeInProgressRaw,] = await Promise.all([
+        git(worktreePath, 'rev-parse', 'HEAD').catch(() => null),
+        git(workspacePath, 'rev-parse', baseRef).catch(() => null),
+        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
+        input.direct ? Promise.resolve(null) : aheadBehind(worktreePath, baseRef, 'HEAD'),
+        // The apply guard, asked in advance — and already answered above whenever
+        // the project folder IS the working tree.
+        sameTree
+            ? Promise.resolve(porcelainRaw)
+            : git(workspacePath, 'status', '--porcelain').catch(() => null),
+        // Session 16: the Source Control view. `-uall` so a new folder lists its
+        // files rather than collapsing to `dir/` — the panel stages one path at a
+        // time and a directory entry is not a path anybody can act on.
+        git(worktreePath, 'status', '--porcelain=v1', '-z', '--untracked-files=all')
+            // A repository with tens of thousands of new files blows the 8MB buffer.
+            // The collapsed form still answers «is there anything here», which is
+            // better than a panel that cannot render at all.
+            .catch(() => git(worktreePath, 'status', '--porcelain=v1', '-z').catch(() => '')),
+        git(worktreePath, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').catch(() => null),
+        git(worktreePath, 'remote').catch(() => ''),
+        hasMergeInProgress(worktreePath),
+        // The project folder's own stopped merge. Different question from the one
+        // above whenever they are different folders — and the answer changes the
+        // advice a BRANCH session gets: you cannot «just commit» a conflicted tree
+        // (QA-110 m7). When they are the same folder it is the same answer.
+        sameTree ? Promise.resolve(false) : hasMergeInProgress(workspacePath),
+    ]);
+    const workspaceMergeInProgress = sameTree ? mergeInProgress : workspaceMergeInProgressRaw;
+    const workspaceDirtyPaths = porcelainPaths(workspacePorcelain ?? '');
+    // In DIRECT mode the branch is whatever the folder is on RIGHT NOW, not the
+    // name recorded when the session started. Somebody checking out another
+    // branch mid-session is a thing that happens — it is their folder — and the
+    // panel has to name the branch its Commit button would actually write to.
+    const branch = input.direct ? (worktreeBranch ?? sessionBranch) : sessionBranch;
+    const working = parsePorcelainZ(workingRaw);
+    const upstream = upstreamRaw ? sanitizeBranch(upstreamRaw) : null;
+    // Only worth a round trip when there IS an upstream — and it is read against
+    // the last fetch, so `behind` is «what the last Pull would have brought»,
+    // not «what the remote has right now». Nothing here talks to the network.
+    const upstreamDistance = upstream ? await aheadBehind(worktreePath, upstream, 'HEAD') : null;
+    // `null` means «we cannot know», and that is the honest answer whenever the
+    // caller did not tell us where the last apply stopped — a session applied
+    // before session 13, or applied through a runner too old to report the tip.
+    // Falling back to `ahead` was worse than saying nothing: a squash merge never
+    // makes the branch an ancestor of the base, so that number never drops to
+    // zero and the panel announced «4 commits not in main» about work that was
+    // already there (QA-107).
+    const newCommits = input.appliedBranchSha
+        ? await countSince(worktreePath, input.appliedBranchSha, 'HEAD', {
+            excludeRef: baseRef,
+            noMerges: true,
+        })
+        : null;
+    // Push sends everything, merges included — so this one counts them.
+    const aheadOfPushed = input.pushedSha
+        ? await countSince(worktreePath, input.pushedSha, 'HEAD')
+        : null;
     return {
-        branch: sessionBranch,
-        baseBranch,
+        branch,
+        baseBranch: input.direct ? branch : baseBranch,
         files,
         additions: files.reduce((sum, f) => sum + (f.additions ?? 0), 0),
         deletions: files.reduce((sum, f) => sum + (f.deletions ?? 0), 0),
         agentCommits: Number(commitCountRaw) || 0,
         uncommittedFiles: uncommittedPaths.size,
+        branchSha,
+        baseSha,
+        forkSha: base,
+        ahead: distance?.ahead ?? null,
+        behind: distance?.behind ?? null,
+        newCommits,
+        aheadOfPushed,
+        worktreeBranch,
+        // Drift is only meaningful against a base we were TOLD to expect. Without a
+        // pinned base the folder's branch IS the base by definition, so nothing can
+        // have drifted (pre-session-13 sessions keep the old behaviour exactly).
+        drifted: pinned && worktreeBranch !== null && worktreeBranch !== baseBranch,
+        baseMissing,
+        workspaceDirty: workspacePorcelain === null ? null : workspaceDirtyPaths.length > 0,
+        workspaceMergeInProgress,
+        workspaceDirtyFiles: workspaceDirtyPaths.slice(0, WORKSPACE_DIRTY_SAMPLE),
+        workspaceDirtyCount: workspaceDirtyPaths.length,
+        working: working.slice(0, MAX_WORKING_ENTRIES),
+        workingCount: working.length,
+        workingTruncated: working.length > MAX_WORKING_ENTRIES,
+        stagedCount: working.filter(isStagedEntry).length,
+        unstagedCount: working.filter(isUnstagedEntry).length,
+        conflictedCount: working.filter(isConflictedEntry).length,
+        mergeInProgress,
+        upstream,
+        aheadUpstream: upstreamDistance?.ahead ?? null,
+        behindUpstream: upstreamDistance?.behind ?? null,
+        remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
     };
 }
 /**
@@ -239,16 +635,32 @@ function capDiff(diff) {
     const truncated = masked.length > DIFF_CAP_BYTES;
     return { diff: truncated ? masked.slice(0, DIFF_CAP_BYTES) : masked, truncated };
 }
-export async function gitDiff(worktreePath, workspacePath, sessionBranch, filePath) {
+export async function gitDiff(worktreePath, workspacePath, sessionBranch, filePath, baseBranch, mode = 'base') {
     const relPath = safeDiffPath(worktreePath, filePath);
-    const { baseRef } = await resolveBase(workspacePath, sessionBranch);
+    if (mode === 'staged') {
+        return capDiff(await git(worktreePath, 'diff', '--cached', '-M', '--', relPath));
+    }
+    if (mode === 'worktree') {
+        const unstaged = await git(worktreePath, 'diff', '-M', '--', relPath);
+        if (unstaged)
+            return capDiff(unstaged);
+        return untrackedDiff(worktreePath, relPath);
+    }
+    const { baseRef } = await resolveBase(workspacePath, sessionBranch, baseBranch);
     const base = await mergeBase(worktreePath, baseRef);
     const diff = await git(worktreePath, 'diff', '-M', base, '--', relPath);
     if (diff)
         return capDiff(diff);
-    // No diff against the base. The /dev/null fallback shows file CONTENT, so
-    // it is allowed only for genuinely UNTRACKED files (status `??`) — never
-    // for unchanged tracked files and never for gitignored ones (QA-98 F1).
+    return untrackedDiff(worktreePath, relPath);
+}
+/**
+ * The content of a file git does not track yet, shown as an all-additions diff.
+ *
+ * Gated on the status letter and nothing else: this path prints file CONTENT
+ * verbatim, so it is allowed only for genuinely UNTRACKED files (`??`) — never
+ * for an unchanged tracked file and never for a gitignored one (QA-98 F1).
+ */
+async function untrackedDiff(worktreePath, relPath) {
     const porcelain = await git(worktreePath, 'status', '--porcelain', '--', relPath);
     if (!porcelain.startsWith('??'))
         return { diff: '', truncated: false };
@@ -257,55 +669,586 @@ export async function gitDiff(worktreePath, workspacePath, sessionBranch, filePa
         .catch((error) => error?.code === 1 && typeof error.stdout === 'string' ? error.stdout : '');
     return capDiff(fallback);
 }
-export async function gitCommit(worktreePath, message) {
-    const porcelain = await git(worktreePath, 'status', '--porcelain');
-    if (!porcelain)
+/**
+ * The whole diff of the branch against its base — masked, never header-checked.
+ *
+ * Deliberately separate from `gitDiff`: that one REFUSES a diff containing a
+ * protected file, which is right for a panel showing one file at a time and
+ * wrong here, where the answer would be «no commit message at all, because the
+ * branch happens to touch `.env.example`». The caller strips protected files
+ * instead of losing the diff, and says how many it dropped.
+ */
+export async function gitBranchDiff(input) {
+    const { baseRef } = await resolveBase(input.workspacePath, input.sessionBranch, input.baseBranch);
+    const base = await mergeBase(input.worktreePath, baseRef);
+    const raw = await tooLargeAware(git(input.worktreePath, 'diff', '-M', base)).catch(() => '');
+    const masked = maskString(raw);
+    const cap = input.maxBytes ?? DIFF_CAP_BYTES;
+    return masked.length > cap
+        ? { diff: masked.slice(0, cap), truncated: true }
+        : { diff: masked, truncated: false };
+}
+/**
+ * Commit — either the index, or everything, and the caller says which.
+ *
+ * `all: true` is the historical behaviour and still the default for the agent's
+ * own auto-commit: `git add -A` then commit, because an agent has no index to
+ * curate. `all: false` is what the Source Control panel sends, and it is the
+ * whole point of session 16 — a person who staged three files out of nine gets
+ * a commit with three files in it, exactly as `git commit` has always worked.
+ *
+ * A merge that stopped on a conflict commits with no `-m` message of ours?
+ * No: the message is still the user's, and `git commit` finishing a merge is
+ * how a merge is finished. The only thing we check is that nothing is still
+ * conflicted, because git would refuse anyway and its refusal is unreadable.
+ */
+async function gitCommitImpl(worktreePath, message, options = {}) {
+    const all = options.all !== false;
+    const root = await repoRoot(worktreePath);
+    const porcelain = await git(root, 'status', '--porcelain=v1', '-z', '--untracked-files=all');
+    const entries = parsePorcelainZ(porcelain);
+    // A merge still needs its commit even when the resolution left the tree
+    // identical to HEAD — every conflict resolved «take ours». Without this the
+    // panel would answer «nothing to commit» to the one press that finishes the
+    // merge, and `MERGE_HEAD` would sit there forever.
+    const finishingMerge = await hasMergeInProgress(root);
+    if (entries.length === 0 && !finishingMerge) {
         return { committed: false, reason: 'nothing-to-commit' };
-    await git(worktreePath, 'add', '-A');
-    await git(worktreePath, 'commit', '-m', message);
-    return { committed: true, sha: await git(worktreePath, 'rev-parse', 'HEAD') };
+    }
+    const conflicted = entries.filter(isConflictedEntry);
+    if (conflicted.length > 0) {
+        return {
+            committed: false,
+            reason: `unresolved-conflicts: ${conflicted
+                .slice(0, 5)
+                .map((entry) => entry.path)
+                .join(', ')}`,
+        };
+    }
+    if (all) {
+        await git(root, 'add', '-A');
+    }
+    else if (!entries.some(isStagedEntry) && !finishingMerge) {
+        // Nothing staged and we were told not to stage: `git commit` would either
+        // fail or, mid-merge, commit an empty change. Say which of the two states
+        // this is instead.
+        return { committed: false, reason: 'nothing-staged' };
+    }
+    await git(root, 'commit', '-m', message);
+    return { committed: true, sha: await git(root, 'rev-parse', 'HEAD') };
+}
+// ─── Source control (session 16: git is git) ─────────────────────────
+//
+// Stage, unstage, discard, pull — the four verbs the Git panel was missing, and
+// the reason «Set aside»/stash existed at all. A stash was our way of saying
+// «your uncommitted work is in the way and you have no shell here»; with these
+// the work is no longer in anybody's way, because the person can just commit it.
+//
+// Every one of them stands at the repository ROOT and takes paths exactly as
+// `git status --porcelain` printed them, which is exactly what the panel sends
+// back. Every one of them passes those paths after a `--`, with
+// `--literal-pathspecs` on, having first refused anything absolute, anything
+// containing `..`, anything with pathspec magic in it and anything that resolves
+// — symlinks followed — outside the checkout.
+/** A ceiling on one request. The panel selects files, not file systems. */
+const MAX_PATHSPECS = 500;
+/** argv has a length limit; git is called in batches under it. */
+const PATHSPEC_BATCH = 100;
+/**
+ * The deepest ancestor of `target` that actually exists, fully resolved.
+ *
+ * A path being discarded may not exist any more (that is often WHY it is being
+ * discarded), so `realpathSync` on it throws — and a check that throws is a
+ * check that got skipped. Walking up to something real still catches the case
+ * that matters: a symlinked directory pointing out of the repository.
+ */
+function realAncestor(target) {
+    let current = target;
+    for (let depth = 0; depth < 64; depth += 1) {
+        try {
+            return fs.realpathSync(current);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+    }
+    return target;
+}
+/**
+ * Paths from the browser, turned into pathspecs git may be handed.
+ *
+ * Deliberately NOT filtered by the secret denylist. That list exists to stop a
+ * `.env` being READ into a diff and shipped to a browser; staging or discarding
+ * one reads nothing and reveals nothing, and refusing it would mean a file the
+ * user's own `git status` shows has a row in the panel with every button dead.
+ * What git ignores stays ignored — it never appears in the status this list is
+ * built from, so nothing here can reach it.
+ */
+function safeRepoPaths(root, raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error('No paths were given');
+    }
+    if (raw.length > MAX_PATHSPECS) {
+        throw new Error(`Too many paths in one request (max ${MAX_PATHSPECS})`);
+    }
+    const realRoot = realAncestor(root);
+    const out = [];
+    for (const value of raw) {
+        if (typeof value !== 'string' || value.length === 0 || value.length > 1_000) {
+            throw new Error('Every path must be a non-empty string');
+        }
+        if (path.isAbsolute(value) || value.split(/[\\/]/).includes('..')) {
+            throw new Error(`Path must be relative to the repository: ${value}`);
+        }
+        if (PATHSPEC_MAGIC.test(value)) {
+            throw new Error(`Path must name a file, not a pattern: ${value}`);
+        }
+        const resolved = path.resolve(root, value);
+        const rel = path.relative(root, resolved);
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Path escapes the repository: ${value}`);
+        }
+        if (rel.split(path.sep).includes('.git')) {
+            throw new Error('Paths inside .git are not files anybody stages');
+        }
+        const realRel = path.relative(realRoot, realAncestor(resolved));
+        if (realRel.startsWith('..') || path.isAbsolute(realRel)) {
+            throw new Error(`Path escapes the repository: ${value}`);
+        }
+        out.push(rel.split(path.sep).join('/'));
+    }
+    return out;
+}
+/** Run one git command per batch of pathspecs, so argv never overflows. */
+async function gitPerBatch(root, args, paths) {
+    for (let i = 0; i < paths.length; i += PATHSPEC_BATCH) {
+        await git(root, ...args, '--', ...paths.slice(i, i + PATHSPEC_BATCH));
+    }
+}
+/** Counts after the fact, read from git rather than predicted. */
+async function stageCounts(root) {
+    const entries = parsePorcelainZ(await git(root, 'status', '--porcelain=v1', '-z', '--untracked-files=all').catch(() => ''));
+    return {
+        staged: entries.filter(isStagedEntry).length,
+        unstaged: entries.filter(isUnstagedEntry).length,
+    };
+}
+/**
+ * `git add` — the `+` next to a file, and the `+` next to the group header.
+ *
+ * `-A` rather than a bare `add` so a DELETED file is staged as a deletion: `git
+ * add file.txt` on a path that no longer exists is an error in older git and a
+ * no-op in the reader's head, and «I staged the deletion and it did not stage»
+ * is the kind of quiet wrong answer this whole session is about removing.
+ */
+async function gitStageImpl(input) {
+    const root = await repoRoot(input.worktreePath);
+    if (input.all) {
+        await git(root, 'add', '-A', '--', '.');
+        return { paths: 0, ...(await stageCounts(root)) };
+    }
+    const paths = safeRepoPaths(root, input.paths);
+    await gitPerBatch(root, ['add', '-A'], paths);
+    return { paths: paths.length, ...(await stageCounts(root)) };
 }
-export async function applySession(workspacePath, worktreePath, sessionBranch, message) {
+/**
+ * `git restore --staged` — the `−` that takes a file back out of the index.
+ *
+ * Two fallbacks, both real: `git restore` needs git 2.23, and a repository
+ * whose first commit has not happened yet has no HEAD to restore from, so the
+ * index entry has to be removed instead of rewritten.
+ */
+async function gitUnstageImpl(input) {
+    const root = await repoRoot(input.worktreePath);
+    const paths = input.all ? ['.'] : safeRepoPaths(root, input.paths);
+    const unborn = await git(root, 'rev-parse', '--verify', '--quiet', 'HEAD')
+        .then(() => false)
+        .catch(() => true);
+    if (unborn) {
+        await gitPerBatch(root, ['rm', '--cached', '-r', '--force', '--ignore-unmatch', '-q'], paths);
+    }
+    else {
+        try {
+            await gitPerBatch(root, ['restore', '--staged'], paths);
+        }
+        catch {
+            await gitPerBatch(root, ['reset', '-q', 'HEAD'], paths);
+        }
+    }
+    return { paths: input.all ? 0 : paths.length, ...(await stageCounts(root)) };
+}
+/**
+ * `git checkout -- <file>` and `rm <untracked>` — the ↺ next to a row.
+ *
+ * The one destructive button in the panel, so it is built to destroy only what
+ * it can name. It reads the status FIRST and acts per entry:
+ *
+ *  - tracked  → `git restore --worktree`, which puts the file back to what the
+ *    INDEX holds, not to HEAD. That is what VS Code's «Discard Changes» does,
+ *    and it is the difference between losing today's edit and losing the
+ *    carefully staged version of it as well.
+ *  - untracked → the file is removed. Only ever a path git reported as `??`,
+ *    which is why a `.gitignore`d file can never reach this line: ignored files
+ *    are not in the status at all. There is no `-x` anywhere in this file.
+ *  - conflicted → skipped and reported. `git restore` refuses these, and doing
+ *    it the forceful way would silently pick a side of somebody's merge.
+ *
+ * This replaces the `git clean -fd` that destroyed a live project's planning
+ * documents on 2026-07-28: `clean` deletes what it FINDS, this deletes what it
+ * was told, and the two are only the same in a folder nobody else is using.
+ */
+async function gitDiscardImpl(input) {
+    const root = await repoRoot(input.worktreePath);
+    const raw = await git(root, 'status', '--porcelain=v1', '-z', '--untracked-files=all').catch((error) => {
+        // Deliberately fatal rather than defaulted to «nothing»: an empty status
+        // here would make «discard all» a no-op reported as success, and the next
+        // press would be somebody pressing it harder.
+        throw new Error(`Could not read the working tree: ${shortError(error)}`);
+    });
+    const entries = parsePorcelainZ(raw);
+    const byPath = new Map(entries.map((entry) => [entry.path, entry]));
+    // Explicit paths are validated up front and a bad one is FATAL: the caller
+    // asked for something illegal and must hear so. `all` is different — the list
+    // is git's own, and one entry we decline to touch (a symlink pointing out of
+    // the tree) must not cost the other forty their discard (QA-110 m6).
+    const wanted = input.all
+        ? entries.filter(isUnstagedEntry).map((entry) => entry.path)
+        : safeRepoPaths(root, input.paths);
+    const skipped = [];
+    const restore = [];
+    const remove = [];
+    for (const target of wanted) {
+        const entry = byPath.get(target);
+        // Not in the status: already clean, or a path that only ever existed in the
+        // browser's stale copy of it. Either way there is nothing to discard, and
+        // deleting an unlisted path on request is exactly the mistake being fixed.
+        if (!entry)
+            continue;
+        if (isConflictedEntry(entry)) {
+            skipped.push(target);
+            continue;
+        }
+        if (entry.index === '?')
+            remove.push(target);
+        else if (entry.worktree !== ' ')
+            restore.push(target);
+    }
+    // Everything that is going to be deleted is resolved and checked HERE, before
+    // a single file is touched (QA-110 M3). The validation used to run inside the
+    // delete loop, so a bad path in position four aborted the request after
+    // positions one to three had already been restored and unlinked — a partial
+    // destruction reported to the browser as one flat «could not discard».
+    const targets = [];
+    for (const target of remove) {
+        let safe;
+        try {
+            [safe] = safeRepoPaths(root, [target]);
+        }
+        catch (error) {
+            // Only reachable for `all`, where the paths came from git rather than
+            // from the caller — the explicit branch already threw above.
+            if (!input.all)
+                throw error;
+            skipped.push(target);
+            continue;
+        }
+        if (!safe)
+            continue;
+        targets.push({ path: target, resolved: path.resolve(root, safe) });
+    }
+    // And a nested repository is left alone, the way `git clean` leaves one alone
+    // (QA-110 B1). `git status -uall` reports a checkout inside the tree as ONE
+    // untracked directory, so a recursive delete would take its `.git` and every
+    // commit in it — work that exists nowhere else and that nobody asked about.
+    const nested = targets.filter((t) => fs.existsSync(path.join(t.resolved, '.git')));
+    for (const t of nested)
+        skipped.push(t.path);
+    const deletable = targets.filter((t) => !nested.includes(t));
+    if (restore.length > 0) {
+        try {
+            await gitPerBatch(root, ['restore', '--worktree'], restore);
+        }
+        catch {
+            await gitPerBatch(root, ['checkout', '--'], restore);
+        }
+    }
+    let deleted = 0;
+    for (const target of deletable) {
+        try {
+            fs.rmSync(target.resolved, { recursive: true, force: true });
+            deleted += 1;
+        }
+        catch {
+            skipped.push(target.path);
+        }
+    }
+    return { restored: restore.length, deleted, skipped };
+}
+/**
+ * `git pull` — fetch, then fast-forward, then merge if it has to.
+ *
+ * Deliberately NOT `--ff-only` forever: a branch with local commits and an
+ * upstream that moved is the normal state of any shared branch, and refusing it
+ * would mean the button works until the first day it matters. So it does what
+ * `git pull` does, including leaving a conflict in the tree — which the panel
+ * then draws as «Merge Changes», the way an editor does, instead of hiding the
+ * state and inventing a rollback nobody asked for.
+ *
+ * Credentials are the user's own and are never seen here; the environment is
+ * hardened the same way `gitPush` hardens it, so a missing one FAILS rather
+ * than hanging on a prompt no headless process can answer.
+ */
+async function gitPullImpl(input) {
+    const root = await repoRoot(input.worktreePath);
+    if (await hasMergeInProgress(root)) {
+        return {
+            pulled: false,
+            error: 'A merge is already in progress here — finish it or abort it first',
+        };
+    }
+    const upstreamRaw = await git(root, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').catch(() => null);
+    const upstream = upstreamRaw ? sanitizeBranch(upstreamRaw) : null;
+    if (!upstream) {
+        return {
+            pulled: false,
+            error: 'This branch has no upstream branch yet — press Push once and it will get one',
+        };
+    }
+    const remote = upstream.split('/')[0] ?? '';
+    const remotes = await git(root, 'remote')
+        .then((raw) => raw.split('\n').filter(Boolean))
+        .catch(() => []);
+    if (!remotes.includes(remote)) {
+        return { pulled: false, upstream, error: `This repository has no remote named ${remote}` };
+    }
+    try {
+        await execFileAsync('git', [...GIT_GLOBAL_ARGS, 'fetch', '--prune', remote], {
+            cwd: root,
+            timeout: PUSH_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+            env: await networkGitEnv(root),
+        });
+    }
+    catch (error) {
+        return { pulled: false, upstream, remote, error: pushError(error) };
+    }
+    const distance = await aheadBehind(root, upstream, 'HEAD');
+    if (distance && distance.behind === 0) {
+        return {
+            pulled: true,
+            alreadyUpToDate: true,
+            upstream,
+            remote,
+            ahead: distance.ahead,
+            behind: 0,
+            ...(await headSha(root)),
+        };
+    }
+    const fastForwarded = await mergeWithTimeout(root, ['merge', '--ff-only', upstream])
+        .then(() => true)
+        .catch(() => false);
+    if (fastForwarded) {
+        return {
+            pulled: true,
+            fastForward: true,
+            upstream,
+            remote,
+            ...(await headSha(root)),
+            ...(await upstreamDistanceOf(root, upstream)),
+        };
+    }
+    try {
+        await mergeWithTimeout(root, ['merge', '--no-edit', upstream]);
+    }
+    catch (error) {
+        if (isMergeConflict(error) || (await hasMergeInProgress(root))) {
+            return {
+                pulled: false,
+                conflict: true,
+                conflictPaths: await conflictedPaths(root),
+                upstream,
+                remote,
+            };
+        }
+        return { pulled: false, upstream, remote, error: shortError(error) };
+    }
+    return {
+        pulled: true,
+        fastForward: false,
+        upstream,
+        remote,
+        ...(await headSha(root)),
+        ...(await upstreamDistanceOf(root, upstream)),
+    };
+}
+async function headSha(root) {
+    const sha = await git(root, 'rev-parse', 'HEAD').catch(() => null);
+    return sha ? { commitSha: sha } : {};
+}
+async function upstreamDistanceOf(root, upstream) {
+    const distance = await aheadBehind(root, upstream, 'HEAD');
+    return distance ? { ahead: distance.ahead, behind: distance.behind } : {};
+}
+/** A merge is allowed to take longer than a status call. */
+async function mergeWithTimeout(root, args) {
+    const { stdout } = await execFileAsync('git', [...GIT_GLOBAL_ARGS, ...args], {
+        cwd: root,
+        timeout: MERGE_TIMEOUT_MS,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return stdout;
+}
+/**
+ * `git merge --abort` — the way back out of a pull that conflicted.
+ *
+ * Without it a failed pull is a dead end reachable by pressing one button, and
+ * the only exit is a shell on a server the person pressing may not have. It
+ * restores the tree to the commit the merge started from; work committed before
+ * the pull is untouched, because the merge never rewrote it.
+ */
+async function gitMergeAbortImpl(worktreePath) {
+    const root = await repoRoot(worktreePath);
+    if (!(await hasMergeInProgress(root)))
+        return { aborted: false, reason: 'no-merge' };
+    try {
+        await mergeWithTimeout(root, ['merge', '--abort']);
+        return { aborted: true };
+    }
+    catch (error) {
+        return { aborted: false, reason: shortError(error) };
+    }
+}
+/** The one sentence both guards use, so the two cannot drift apart. */
+const WORKSPACE_DIRTY_MESSAGE = 'The workspace working copy has uncommitted changes — commit or stash them on the server first';
+async function applySessionImpl(input) {
+    const { workspacePath, worktreePath, sessionBranch, message } = input;
     const workspaceDirty = await git(workspacePath, 'status', '--porcelain');
     if (workspaceDirty) {
+        const paths = porcelainPaths(workspaceDirty);
         return {
             applied: false,
-            error: 'The workspace working copy has uncommitted changes — commit or stash them on the server first',
+            workspaceDirty: true,
+            workspaceDirtyFiles: paths.slice(0, WORKSPACE_DIRTY_SAMPLE),
+            workspaceDirtyCount: paths.length,
+            // «Commit it and try again» is not advice a conflicted tree can follow.
+            workspaceMergeInProgress: await hasMergeInProgress(workspacePath),
+            error: WORKSPACE_DIRTY_MESSAGE,
         };
     }
     const workspaceBranch = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD');
     if (workspaceBranch === sessionBranch) {
         return { applied: false, error: 'The workspace is checked out on the session branch itself' };
     }
+    // The drift guard, and the reason it comes before anything is written: the
+    // merge below lands in whatever branch the folder is on. Checking a feature
+    // branch out on the server used to redirect «Apply» for every session of the
+    // project without a word.
+    const expectedBase = input.expectedBase ? sanitizeBranch(input.expectedBase) : null;
+    if (expectedBase && expectedBase !== workspaceBranch) {
+        return { applied: false, drifted: true, workspaceBranch, baseBranch: expectedBase };
+    }
     // Fold whatever the agent left uncommitted into the branch first, so
     // «Применить» always takes exactly what the user reviewed.
     const worktreeDirty = await git(worktreePath, 'status', '--porcelain');
     if (worktreeDirty) {
         await git(worktreePath, 'add', '-A');
-        await git(worktreePath, 'commit', '-m', 'chore(devbridge): изменения сессии перед применением');
+        await git(worktreePath, 'commit', '-m', 'chore(devbridge): session changes before apply');
+    }
+    const branchSha = await git(workspacePath, 'rev-parse', sessionBranch);
+    const baseShaBefore = await git(workspacePath, 'rev-parse', 'HEAD');
+    // Captured BEFORE anything is written, so a failed merge can tell its own
+    // leftovers from somebody's work that appeared meanwhile.
+    const untrackedBefore = await untrackedPaths(workspacePath);
+    // How much NEW work there is. After a first apply the branch is still «ahead»
+    // of the base — a squash merge is not a merge as far as git is concerned — so
+    // counting from the fork point would keep claiming work that already landed.
+    const repeat = Boolean(input.sinceSha && isCommitSha(input.sinceSha));
+    const sinceCount = repeat
+        ? await countSince(workspacePath, input.sinceSha ?? '', sessionBranch, {
+            excludeRef: 'HEAD',
+            noMerges: true,
+        })
+        : null;
+    if (sinceCount === 0) {
+        return {
+            applied: false,
+            noChanges: true,
+            branchSha,
+            baseShaBefore,
+            baseBranch: workspaceBranch,
+        };
+    }
+    if (!repeat) {
+        const base = await git(workspacePath, 'merge-base', 'HEAD', sessionBranch);
+        const commits = Number(await git(workspacePath, 'rev-list', '--count', `${base}..${sessionBranch}`));
+        if (!commits) {
+            return {
+                applied: false,
+                noChanges: true,
+                branchSha,
+                baseShaBefore,
+                baseBranch: workspaceBranch,
+            };
+        }
     }
-    const base = await git(workspacePath, 'merge-base', 'HEAD', sessionBranch);
-    const commits = Number(await git(workspacePath, 'rev-list', '--count', `${base}..${sessionBranch}`));
-    if (!commits)
-        return { applied: false, error: 'The session branch has no changes to apply' };
     try {
-        await execFileAsync('git', [...GIT_GLOBAL_ARGS, 'merge', '--squash', sessionBranch], {
-            cwd: workspacePath,
-            timeout: MERGE_TIMEOUT_MS,
-            maxBuffer: 8 * 1024 * 1024,
-        });
+        if (repeat) {
+            // A REPEAT apply is a three-way merge whose base is the branch tip the
+            // PREVIOUS apply swallowed — not the fork point.
+            //
+            // `merge --squash` would use the fork point, because a squash merge never
+            // makes the branch an ancestor of the base. From the fork point's view,
+            // anything the base changed after the first apply looks like «only the
+            // branch changed», so git takes the branch's version with no conflict —
+            // silently undoing work somebody did on the base in between. Verified
+            // with real git: main deliberately reverting a line, then a second apply,
+            // put the line straight back without a word (QA-107).
+            //
+            // `merge-recursive <base> -- <ours> <theirs>` is the plumbing for exactly
+            // this: it merges into the index and working tree and exits 1 on
+            // conflict. Available in every git this project has ever supported.
+            await execFileAsync('git', [...GIT_GLOBAL_ARGS, 'merge-recursive', input.sinceSha ?? '', '--', 'HEAD', sessionBranch], { cwd: workspacePath, timeout: MERGE_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 });
+        }
+        else {
+            await execFileAsync('git', [...GIT_GLOBAL_ARGS, 'merge', '--squash', sessionBranch], {
+                cwd: workspacePath,
+                timeout: MERGE_TIMEOUT_MS,
+                maxBuffer: 8 * 1024 * 1024,
+            });
+        }
     }
     catch (error) {
-        // Restore a pristine workspace either way.
-        await git(workspacePath, 'reset', '--merge').catch(() => undefined);
+        // Restore a pristine workspace either way. `merge-recursive` leaves no
+        // MERGE_HEAD, so `reset --merge` can decline — fall back to a hard reset,
+        // which is safe precisely because the tree was verified clean above.
+        await restoreCleanWorkspace(workspacePath, untrackedBefore);
         // Only a real content conflict is worth handing back to the agent — a
         // dirty index or a failing hook would send it on a pointless rebase
-        // errand (QA-99 MINOR-7).
-        if (isMergeConflict(error)) {
-            return { applied: false, conflict: true, baseBranch: workspaceBranch };
+        // errand (QA-99 MINOR-7). `merge-recursive` exits 1 for a conflict and
+        // says so in its own words, which `isMergeConflict` already recognises.
+        if (isMergeConflict(error) || (repeat && exitedWithConflict(error))) {
+            return { applied: false, conflict: true, baseBranch: workspaceBranch, branchSha };
         }
         return { applied: false, error: `Merge failed: ${shortError(error)}` };
     }
+    // A repeated apply whose new commits only touch things the base already has
+    // (a revert-and-redo, a whitespace round trip) stages nothing. That is
+    // «nothing to apply», not a failure — and it has to be caught here, because
+    // `git commit` would otherwise fail with a message about the index.
+    const stillDirty = await git(workspacePath, 'status', '--porcelain');
+    if (!stillDirty) {
+        await restoreCleanWorkspace(workspacePath, untrackedBefore);
+        return {
+            applied: false,
+            noChanges: true,
+            branchSha,
+            baseShaBefore,
+            baseBranch: workspaceBranch,
+        };
+    }
     try {
         await git(workspacePath, 'commit', '-m', message);
     }
@@ -313,11 +1256,250 @@ export async function applySession(workspacePath, worktreePath, sessionBranch, m
         await git(workspacePath, 'reset', '--merge').catch(() => undefined);
         return { applied: false, error: `Commit failed: ${shortError(error)}` };
     }
-    return { applied: true, commitSha: await git(workspacePath, 'rev-parse', 'HEAD') };
+    return {
+        applied: true,
+        commitSha: await git(workspacePath, 'rev-parse', 'HEAD'),
+        branchSha,
+        baseShaBefore,
+        baseBranch: workspaceBranch,
+    };
 }
-const LOG_FORMAT = '%H%x00%P%x00%an%x00%aI%x00%D%x00%s';
-const SHOW_META_FORMAT = '%H%x00%P%x00%an%x00%ae%x00%aI%x00%D%x00%s%x00%b';
-const MAX_LOG_LIMIT = 200;
+/**
+ * Bring the base branch into the session branch — merge, never rebase.
+ *
+ * Rebase is the tempting one and it is the wrong one: it rewrites commits the
+ * History tab has already shown a human, and «the commit you were looking at no
+ * longer exists» is not a trade worth a linear graph.
+ *
+ * Runs inside the session worktree, so the project folder is never touched.
+ */
+async function updateFromBaseImpl(input) {
+    const { workspacePath, worktreePath, sessionBranch } = input;
+    const { baseBranch, baseRef, baseMissing } = await resolveBase(workspacePath, sessionBranch, input.baseBranch);
+    if (baseMissing) {
+        return { updated: false, baseBranch, error: `Branch ${input.baseBranch} no longer exists` };
+    }
+    assertRefArgument(baseRef);
+    const dirty = await git(worktreePath, 'status', '--porcelain');
+    if (dirty) {
+        return {
+            updated: false,
+            baseBranch,
+            error: 'The session has uncommitted changes — commit them first, then update from the base branch',
+        };
+    }
+    const behindRaw = await git(worktreePath, 'rev-list', '--count', `HEAD..${baseRef}`).catch(() => null);
+    if (behindRaw !== null && Number(behindRaw) === 0) {
+        return { updated: true, alreadyUpToDate: true, baseBranch };
+    }
+    try {
+        await execFileAsync('git', [...GIT_GLOBAL_ARGS, 'merge', '--no-edit', baseRef], {
+            cwd: worktreePath,
+            timeout: MERGE_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+    }
+    catch (error) {
+        // The conflicting paths only exist between the failure and the abort —
+        // read them first or they are gone.
+        const conflicted = await git(worktreePath, 'diff', '--name-only', '--diff-filter=U').catch(() => '');
+        const conflictPaths = conflicted
+            .split('\n')
+            .filter(Boolean)
+            .slice(0, 100)
+            .map((entry) => entry.slice(0, 500));
+        await git(worktreePath, 'merge', '--abort').catch(() => undefined);
+        // «The merge was aborted and the working tree is clean» is a promise the
+        // agent acts on — so check it rather than assume it. An abort can itself
+        // fail (a lock left by a crashed git, a read-only file), and telling the
+        // agent to go resolve conflicts in a tree that is still mid-merge sends it
+        // into a state it cannot get out of (QA-107).
+        const leftDirty = await git(worktreePath, 'status', '--porcelain').catch(() => '');
+        if (leftDirty) {
+            return {
+                updated: false,
+                baseBranch,
+                error: 'The merge conflicted and could not be undone — the session worktree is still mid-merge. Run `git merge --abort` in it on the server.',
+            };
+        }
+        if (isMergeConflict(error) || conflictPaths.length > 0) {
+            return { updated: false, conflict: true, conflictPaths, baseBranch };
+        }
+        return { updated: false, baseBranch, error: `Merge failed: ${shortError(error)}` };
+    }
+    return {
+        updated: true,
+        commitSha: await git(worktreePath, 'rev-parse', 'HEAD'),
+        baseBranch,
+    };
+}
+const MAX_BRANCHES = 200;
+/**
+ * Every local branch, with the one fact the user cannot see anywhere else:
+ * whether it is already checked out in another worktree. Git refuses to check
+ * one branch out twice, so «continue this branch» has to know before it starts,
+ * not after the worktree command fails.
+ */
+export async function gitBranches(workspacePath) {
+    const [rawBranches, rawWorktrees, currentBranch, remotesRaw] = await Promise.all([
+        git(workspacePath, 'for-each-ref', `--count=${MAX_BRANCHES + 1}`, '--sort=-committerdate', '--format=%(refname:short)%00%(objectname)%00%(committerdate:iso-strict)%00%(subject)', 'refs/heads/'),
+        git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => ''),
+        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
+        git(workspacePath, 'remote').catch(() => ''),
+    ]);
+    // `worktree list --porcelain` emits stanzas: `worktree <path>` … `branch <ref>`.
+    const checkedOut = new Map();
+    let currentWorktree = null;
+    for (const line of rawWorktrees.split('\n')) {
+        if (line.startsWith('worktree '))
+            currentWorktree = line.slice('worktree '.length).trim();
+        else if (line.startsWith('branch ') && currentWorktree) {
+            const ref = line.slice('branch '.length).trim();
+            checkedOut.set(ref.replace(/^refs\/heads\//, ''), currentWorktree);
+        }
+    }
+    const lines = rawBranches.split('\n').filter(Boolean);
+    const truncated = lines.length > MAX_BRANCHES;
+    const branches = [];
+    for (const line of lines.slice(0, MAX_BRANCHES)) {
+        const [name, sha, date, ...subjectParts] = line.split('\0');
+        if (!name || !sha)
+            continue;
+        branches.push({
+            name: name.slice(0, 200),
+            sha,
+            subject: maskString(subjectParts.join('\0')).slice(0, 300),
+            date: (date ?? '').slice(0, 40),
+            checkedOutIn: checkedOut.get(name) ?? null,
+            merged: false,
+        });
+    }
+    // «Already merged» is answered against the folder's own HEAD — the branch the
+    // user would be merging into. One batched call: `--merged` on for-each-ref.
+    const mergedRaw = await git(workspacePath, 'for-each-ref', '--merged', 'HEAD', '--format=%(refname:short)', 'refs/heads/').catch(() => '');
+    const mergedSet = new Set(mergedRaw.split('\n').filter(Boolean));
+    for (const branch of branches)
+        branch.merged = mergedSet.has(branch.name);
+    return {
+        branches,
+        currentBranch: currentBranch === 'HEAD' ? null : currentBranch,
+        currentSha: await git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+        remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
+        truncated,
+    };
+}
+/** Push is the first thing DevBridge does that leaves the machine. */
+const PUSH_TIMEOUT_MS = 120_000;
+/**
+ * Send exactly one branch to exactly one existing remote.
+ *
+ * The argument vector is built here, in code, from two validated values — never
+ * from a string the caller composed. There is no `--force`, no user refspec and
+ * no way to name a different branch: an outgoing write to somebody else's
+ * repository is an incident when it goes wrong, not a defect.
+ *
+ * Credentials are the user's own (ssh agent or a git credential helper on their
+ * machine). We never see them — and we make sure git fails instead of hanging
+ * on a prompt when they are missing.
+ */
+/**
+ * The environment for the two commands that reach the network.
+ *
+ * A repo that configures its own ssh command (a deploy key, a jump host) has
+ * done so on purpose, and GIT_SSH_COMMAND outranks `core.sshCommand` — so
+ * overriding it unconditionally would break exactly the setups that need it.
+ * Batch mode is only there to make a missing credential FAIL rather than hang
+ * on a prompt nobody can answer; when the repo has its own command we settle
+ * for GIT_TERMINAL_PROMPT and let it be (QA-107).
+ */
+async function networkGitEnv(cwd) {
+    const ownSshCommand = await git(cwd, 'config', '--get', 'core.sshCommand').catch(() => '');
+    return {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_ASKPASS: '',
+        SSH_ASKPASS: '',
+        ...(ownSshCommand ? {} : { GIT_SSH_COMMAND: 'ssh -oBatchMode=yes' }),
+    };
+}
+async function gitPushImpl(input) {
+    const branch = sanitizeBranch(input.branch);
+    if (!branch)
+        return { pushed: false, error: 'Invalid branch name' };
+    const remotes = await git(input.workspacePath, 'remote')
+        .then((raw) => raw.split('\n').filter(Boolean))
+        .catch(() => []);
+    if (remotes.length === 0) {
+        return { pushed: false, error: 'This repository has no remote configured' };
+    }
+    // Membership in the repo's own list, not a pattern match: the value reaches
+    // an argv slot, and «origin» being a legal name says nothing about it existing.
+    if (!remotes.includes(input.remote)) {
+        return {
+            pushed: false,
+            error: `This repository has no remote named ${input.remote} (it has: ${remotes.join(', ')})`,
+        };
+    }
+    if (!(await branchExists(input.workspacePath, branch))) {
+        return { pushed: false, error: `Branch ${branch} no longer exists in this repository` };
+    }
+    const commitSha = await git(input.workspacePath, 'rev-parse', branch);
+    // Session 16: the first push of a branch also sets its upstream, so the very
+    // next Pull has something to pull FROM. Without this the panel offered Pull
+    // on a branch that could only ever answer «no upstream» — a button that is
+    // wrong exactly once, on the day somebody first tries it.
+    const hasUpstream = await git(input.workspacePath, 'config', '--get', `branch.${branch}.merge`)
+        .then((value) => Boolean(value))
+        .catch(() => false);
+    try {
+        const { stdout, stderr } = await execFileAsync('git', [
+            ...GIT_GLOBAL_ARGS,
+            'push',
+            ...(hasUpstream ? [] : ['--set-upstream']),
+            input.remote,
+            `refs/heads/${branch}:refs/heads/${branch}`,
+        ], {
+            cwd: input.workspacePath,
+            timeout: PUSH_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+            env: await networkGitEnv(input.workspacePath),
+        });
+        const output = `${stdout}${stderr}`;
+        return {
+            pushed: true,
+            remote: input.remote,
+            branch,
+            commitSha,
+            alreadyUpToDate: /Everything up-to-date/i.test(output),
+            ...(hasUpstream ? {} : { upstreamSet: true }),
+        };
+    }
+    catch (error) {
+        // Git's own words, masked — an auth failure has to be readable or the user
+        // cannot fix it on their side.
+        return { pushed: false, remote: input.remote, branch, error: pushError(error) };
+    }
+}
+function pushError(error) {
+    const stderr = String(error?.stderr ?? '');
+    const message = error instanceof Error ? error.message : String(error);
+    return maskString(stderr.trim() || message).slice(0, 1_000);
+}
+/**
+ * ⚠️ Both formats are parsed POSITIONALLY, in two different functions. Adding a
+ * placeholder here without moving the matching destructure below silently
+ * shifts every later field — the subject becomes the decoration and nobody
+ * notices until a user reads it. Change format and parse in one edit.
+ */
+const LOG_FORMAT = '%H%x00%P%x00%an%x00%aI%x00%cn%x00%cI%x00%D%x00%s';
+const SHOW_META_FORMAT = '%H%x00%P%x00%an%x00%ae%x00%aI%x00%cn%x00%ce%x00%cI%x00%D%x00%s%x00%b';
+/**
+ * Session 14 raised this from 200 for the repository graph, where one page is a
+ * whole screen of a busy `main`. It is bounded by two things above it, and both
+ * were raised in the same breath: the API's own `max(limit)` and the 512 KB WS
+ * frame — 500 commits of ~250 bytes each is ~125 KB, comfortably inside it.
+ */
+const MAX_LOG_LIMIT = 500;
 const MAX_COMMIT_FILES = 500;
 const SUBJECT_CAP = 500;
 const BODY_CAP = 4_000;
@@ -356,7 +1538,7 @@ function safeHistoryPath(filePath) {
     if (path.isAbsolute(normalized) || normalized.split('/').includes('..')) {
         throw new Error('Diff path must be relative to the repository');
     }
-    if (PATHSPEC_MAGIC.test(normalized)) {
+    if (HISTORY_PATHSPEC_MAGIC.test(normalized)) {
         throw new Error('Diff path must name one file, not a pattern');
     }
     // `.`, `./` and a trailing slash all name a directory, and a directory
@@ -372,15 +1554,188 @@ function safeHistoryPath(filePath) {
     }
     return normalized;
 }
-function parseRefs(decoration) {
-    return decoration
-        .split(',')
-        .map((entry) => entry.trim())
-        .filter(Boolean)
-        .map((entry) => (entry.startsWith('HEAD -> ') ? entry.slice('HEAD -> '.length) : entry))
-        .filter((entry) => entry !== 'HEAD')
-        .slice(0, 10)
-        .map((entry) => entry.slice(0, 200));
+/**
+ * Ten was too few the moment the graph started showing a live `main`, where a
+ * release commit routinely carries a tag, a remote and two branches.
+ */
+const MAX_REFS_PER_COMMIT = 24;
+/**
+ * `%D` gives a comma-separated decoration: `HEAD -> main, origin/main, tag: v1.2`.
+ *
+ * Session 14 turns that into typed refs. The `tag: ` prefix used to survive into
+ * the badge, `HEAD` was dropped entirely (so «this is what the folder is on» was
+ * unsayable), and a remote-tracking branch looked exactly like a local one.
+ *
+ * The remote test is «the first segment is a configured remote», not «it has a
+ * slash»: `feature/login` has a slash and is local, and a repo with a remote
+ * called `feature` would otherwise mislabel it.
+ */
+function parseRefs(decoration, remotes = new Set()) {
+    const refs = [];
+    // git separates decorations with «, » — a bare comma is a LEGAL character
+    // inside a ref name, and splitting on it drew one branch as two badges whose
+    // names resolve to nothing (session 15).
+    for (const raw of decoration.split(', ')) {
+        let entry = raw.trim();
+        if (!entry)
+            continue;
+        let isHead = false;
+        if (entry.startsWith('HEAD -> ')) {
+            isHead = true;
+            entry = entry.slice('HEAD -> '.length).trim();
+        }
+        // A detached HEAD decorates as a bare `HEAD` with nothing to point at.
+        if (entry === 'HEAD')
+            continue;
+        let type = 'head';
+        if (entry.startsWith('tag: ')) {
+            type = 'tag';
+            entry = entry.slice('tag: '.length).trim();
+        }
+        else if (remotes.has(entry.split('/')[0] ?? '')) {
+            type = 'remote';
+        }
+        if (!entry)
+            continue;
+        refs.push({ name: entry.slice(0, 200), type, isHead });
+        if (refs.length >= MAX_REFS_PER_COMMIT)
+            break;
+    }
+    return refs;
+}
+/** Remotes configured in this repository — needed to type a decoration. */
+async function remoteNames(workspacePath) {
+    const raw = await git(workspacePath, 'remote').catch(() => '');
+    return new Set(raw.split('\n').filter(Boolean).slice(0, 50));
+}
+/**
+ * How many refs a caller may name explicitly.
+ *
+ * Bounded because the visibility check below walks this list one
+ * `merge-base --is-ancestor` at a time, and an unbounded list would be a way to
+ * make the runner do arbitrary work per commit opened.
+ */
+const MAX_SELECTED_REFS = 32;
+/**
+ * Names git treats as refs but which are NOT branches, remotes or tags.
+ *
+ * The reason this list exists at all: `ORIG_HEAD` is what `reset --hard` writes
+ * before it moves, and `refs/stash` holds whatever `git stash` took away — so
+ * naming one of them in the selector would make exactly the commits QA-105 is
+ * about reachable again, through the front door. `sanitizeBranch` accepts them
+ * happily; they look like ordinary names.
+ *
+ * Matched case-insensitively on the whole value and on its first segment, so
+ * `ORIG_HEAD`, `orig_head` and `ORIG_HEAD^{commit}`-shaped variants all fail.
+ */
+const PSEUDO_REFS = new Set([
+    'HEAD',
+    'ORIG_HEAD',
+    'FETCH_HEAD',
+    'MERGE_HEAD',
+    'CHERRY_PICK_HEAD',
+    'REVERT_HEAD',
+    'BISECT_HEAD',
+    'REBASE_HEAD',
+    'AUTO_MERGE',
+    'stash',
+]);
+/**
+ * Everything a ref name must satisfy before it becomes a git argument.
+ *
+ * The same class of check branch names go through (`sanitizeBranch`), because
+ * that is exactly what these are: `main`, `origin/main`, `v1.2.0`. A leading
+ * dash would be an option, `..` a range, and neither belongs in an argv slot
+ * built from a query string.
+ *
+ * Plus the pseudo-refs above, which are the hole this check exists to close.
+ */
+export function sanitizeRefName(value) {
+    if (typeof value !== 'string')
+        return null;
+    const safe = sanitizeBranch(value);
+    if (!safe)
+        return null;
+    // A fully-qualified name may only name one of the three namespaces this
+    // product shows. The check used to STRIP those three and then look for a
+    // pseudo-ref in what was left, so anything else under `refs/` skipped the
+    // denylist by being spelled out: `refs/stash` (what «Set aside» writes),
+    // `refs/ORIG_HEAD` (what `reset --hard` writes), `refs/notes/*`, and
+    // `refs/original/*` — where `filter-branch` keeps the history somebody
+    // rewrote precisely to get rid of. Every one of them is QA-105 through the
+    // front door, and session 15 gave the first of them real content to leak.
+    if (safe.startsWith('refs/') && !/^refs\/(heads|remotes|tags)\//.test(safe))
+        return null;
+    const withoutNamespace = safe.replace(/^refs\/(heads|remotes|tags)\//, '');
+    const first = withoutNamespace.split('/')[0] ?? '';
+    if (PSEUDO_REFS.has(withoutNamespace.toUpperCase()) || PSEUDO_REFS.has(withoutNamespace)) {
+        return null;
+    }
+    if (PSEUDO_REFS.has(first.toUpperCase()) || PSEUDO_REFS.has(first))
+        return null;
+    return safe;
+}
+function resolveRefScope(selector, always) {
+    const named = (selector.refs ?? [])
+        .map(sanitizeRefName)
+        .filter((ref) => ref !== null);
+    const refs = [...new Set([...always, ...named])].slice(0, MAX_SELECTED_REFS);
+    const namespaces = [];
+    const namespacePaths = [];
+    const add = (flag, path) => {
+        namespaces.push(flag);
+        namespacePaths.push(path);
+    };
+    // NOT `--all`: that also walks refs/stash and refs/notes, which are not
+    // history anybody asked to see.
+    if (selector.all)
+        add('--branches', 'refs/heads');
+    if (selector.all || selector.includeRemotes)
+        add('--remotes', 'refs/remotes');
+    if (selector.all || selector.includeTags)
+        add('--tags', 'refs/tags');
+    return { refs, namespaces, namespacePaths };
+}
+/**
+ * Is `sha` reachable from anything this request was allowed to walk?
+ *
+ * Named refs first and in order, because the caller puts its own branch at the
+ * front and that is the answer nine times out of ten. The namespace sweep is
+ * one call and only runs when the named refs came up empty.
+ */
+async function reachableFromScope(workspacePath, sha, scope) {
+    // Belt to the pseudo-ref braces: a name only authorises a read if it really
+    // is a branch, a remote-tracking branch or a tag. `rev-parse` resolves
+    // anything git calls a ref — including the ones a reset leaves behind — so
+    // the namespace is checked explicitly rather than inferred from the name.
+    const real = await realRefNames(workspacePath, scope.refs);
+    for (const ref of scope.refs.filter((name) => real.has(name))) {
+        const reachable = await git(workspacePath, 'merge-base', '--is-ancestor', sha, assertRefArgument(ref))
+            .then(() => true)
+            .catch(() => false);
+        if (reachable)
+            return true;
+    }
+    if (scope.namespacePaths.length === 0)
+        return false;
+    const hit = await git(workspacePath, 'for-each-ref', '--count=1', `--contains=${sha}`, '--format=%(refname)', ...scope.namespacePaths).catch(() => '');
+    return hit.trim().length > 0;
+}
+/**
+ * Which of these names actually live under refs/heads, refs/remotes or
+ * refs/tags — one `for-each-ref`, whatever the list length.
+ */
+async function realRefNames(workspacePath, names) {
+    if (names.length === 0)
+        return new Set();
+    const raw = await git(workspacePath, 'for-each-ref', '--format=%(refname:short)', 'refs/heads', 'refs/remotes', 'refs/tags').catch(() => '');
+    const existing = new Set(raw.split('\n').filter(Boolean));
+    // `%(refname:short)` prints `main`, `origin/main`, `v1.2.0` — so a caller
+    // that spelled a ref out in full (`refs/heads/main`, which `sanitizeRefName`
+    // accepts) has to be compared on the same footing, or a real branch is
+    // rejected for being over-specified (session 15). Only the three namespaces
+    // this product shows are strippable, which is exactly the allowlist.
+    return new Set(names.filter((name) => existing.has(name) || existing.has(name.replace(/^refs\/(heads|remotes|tags)\//, ''))));
 }
 /**
  * `--numstat` names a rename as `old => new` (or `dir/{old => new}/file`),
@@ -404,38 +1759,98 @@ async function branchExists(workspacePath, ref) {
         .catch(() => false);
 }
 export async function gitLog(input) {
-    const branch = requireSessionBranch(input.branch);
-    const { baseBranch, baseRef } = await resolveBase(input.workspacePath, branch);
-    assertRefArgument(baseRef);
-    if (!(await branchExists(input.workspacePath, branch))) {
-        throw new Error(`Branch ${branch} no longer exists in this repository`);
+    const sessionBranch = input.branch ? requireSessionBranch(input.branch) : null;
+    const selectorOnly = sessionBranch === null;
+    // Without a session there is no base to resolve and no fork point to mark —
+    // the repository graph stands on the refs it was asked for and nothing else.
+    const base = selectorOnly
+        ? null
+        : await resolveBase(input.workspacePath, sessionBranch, input.baseBranch);
+    if (base)
+        assertRefArgument(base.baseRef);
+    if (sessionBranch && !(await branchExists(input.workspacePath, sessionBranch))) {
+        throw new Error(`Branch ${sessionBranch} no longer exists in this repository`);
     }
     // Between the BRANCH and the base — not between the workspace's HEAD and the
     // base, which is what `mergeBase()` computes for the Changes panel from
     // inside the worktree. A base branch that is gone (or a repo with a single
     // commit) leaves the marker missing, not the whole panel failing.
-    const base = await git(input.workspacePath, 'merge-base', branch, baseRef).catch(() => null);
+    const forkPoint = sessionBranch && base
+        ? await git(input.workspacePath, 'merge-base', sessionBranch, base.baseRef).catch(() => null)
+        : null;
     const limit = Math.min(Math.max(Math.trunc(input.limit ?? 50), 1), MAX_LOG_LIMIT);
     const skip = Math.min(Math.max(Math.trunc(input.skip ?? 0), 0), 100_000);
     const scope = input.scope ?? 'all';
-    // `branch --not baseRef` is exactly `base..branch`, but it does not depend on
-    // merge-base succeeding: a repository where the two histories never met would
-    // otherwise silently fall back to the WHOLE branch while the UI still said
-    // «only what the agent committed» (QA-105).
-    const range = scope === 'session'
-        ? [branch, '--not', baseRef]
-        : scope === 'branch'
-            ? [branch]
-            : [branch, baseRef];
+    // Session 11's three scopes stay exactly as they were when a session branch
+    // is given AND the caller named no refs of its own — every existing caller
+    // lands here and nothing about it changed.
+    const usesSelector = selectorOnly ||
+        Boolean(input.all || input.includeRemotes || input.includeTags || input.refs?.length);
+    let range;
+    let scopeRefs;
+    if (usesSelector) {
+        // The session's own branch and base are always in the picture: the graph is
+        // reached from a session, and hiding the branch you came from would be a
+        // strange thing for it to do.
+        const always = [
+            ...(sessionBranch ? [sessionBranch] : []),
+            ...(base?.baseRef ? [base.baseRef] : []),
+        ];
+        const scope = resolveRefScope(input, always);
+        // The SAME list the commit read will accept, not a wider one (session 15).
+        //
+        // `resolveRefScope` promises the two halves «can never disagree about what
+        // this request was allowed to see», and only the read kept the promise:
+        // `reachableFromScope` filters through `realRefNames` (a live entry under
+        // refs/heads, refs/remotes or refs/tags), while the walk fed `scope.refs`
+        // straight into argv. So the log listed commits whose detail view then
+        // refused to open.
+        const walkable = await realRefNames(input.workspacePath, scope.refs);
+        range = [
+            ...scope.refs.filter((ref) => walkable.has(ref)).map(assertRefArgument),
+            ...scope.namespaces,
+        ];
+        scopeRefs = [...scope.refs, ...scope.namespacePaths];
+        // A selector that resolved to nothing at all would make `git log` walk HEAD
+        // by default — the one outcome that is neither what was asked for nor safe
+        // to guess at.
+        if (range.length === 0) {
+            return {
+                branch: sessionBranch ?? '',
+                baseBranch: base?.baseBranch ?? '',
+                mergeBase: forkPoint,
+                commits: [],
+                hasMore: false,
+                scopeRefs: [],
+                nextSkip: 0,
+            };
+        }
+    }
+    else {
+        const baseRef = base?.baseRef ?? '';
+        // `branch --not baseRef` is exactly `base..branch`, but it does not depend
+        // on merge-base succeeding: a repository where the two histories never met
+        // would otherwise silently fall back to the WHOLE branch while the UI still
+        // said «only what the agent committed» (QA-105).
+        range =
+            scope === 'session'
+                ? [sessionBranch, '--not', baseRef]
+                : scope === 'branch'
+                    ? [sessionBranch]
+                    : [sessionBranch, baseRef];
+        scopeRefs = scope === 'branch' ? [sessionBranch] : [sessionBranch, baseRef];
+    }
     // `--topo-order` is not cosmetic: the lane layout on the dashboard assumes a
     // parent never appears before its child, and the default (date order) breaks
     // exactly that on branches committed out of order.
-    const raw = await git(input.workspacePath, 'log', '--topo-order', `--max-count=${limit + 1}`, `--skip=${skip}`, `--format=${LOG_FORMAT}`, ...range, '--');
+    const raw = await git(input.workspacePath, 'log', '--topo-order', `--max-count=${limit + 1}`, ...(skip > 0 ? [`--skip=${skip}`] : []), `--format=${LOG_FORMAT}`, ...range, '--');
+    const remotes = await remoteNames(input.workspacePath);
     const lines = raw.split('\n').filter((line) => line.length > 0);
     const hasMore = lines.length > limit;
     const commits = [];
     for (const line of lines.slice(0, limit)) {
-        const [sha, parents, author, date, decoration, subject] = line.split('\0');
+        // ⚠️ Positional — mirrors LOG_FORMAT exactly.
+        const [sha, parents, author, date, committer, committerDate, decoration, subject] = line.split('\0');
         if (!sha)
             continue;
         commits.push({
@@ -443,11 +1858,123 @@ export async function gitLog(input) {
             parents: parseParents(parents ?? ''),
             author: maskString(author ?? '').slice(0, 200),
             date: (date ?? '').slice(0, 40),
+            committer: maskString(committer ?? '').slice(0, 200),
+            committerDate: (committerDate ?? '').slice(0, 40),
             subject: maskString(subject ?? '').slice(0, SUBJECT_CAP),
-            refs: parseRefs(decoration ?? ''),
+            refs: parseRefs(decoration ?? '', remotes),
+        });
+    }
+    return {
+        branch: sessionBranch ?? '',
+        baseBranch: base?.baseBranch ?? '',
+        mergeBase: forkPoint,
+        commits,
+        hasMore,
+        scopeRefs,
+        // The offset the next page starts at. Computed here so a client cannot get
+        // it wrong, and so a page that returned fewer commits than it asked for
+        // still advances correctly.
+        nextSkip: hasMore ? skip + commits.length : 0,
+    };
+}
+const MAX_REFS = 500;
+/**
+ * Every ref worth drawing, with the two facts a picker cannot get anywhere
+ * else: which worktree holds a branch, and what it tracks.
+ *
+ * One `for-each-ref` over the three namespaces rather than three calls — the
+ * type comes from the ref path, which is more reliable than guessing from the
+ * short name.
+ */
+export async function gitRefs(workspacePath) {
+    const [raw, rawWorktrees, currentBranch, currentSha, remotesRaw] = await Promise.all([
+        git(workspacePath, 'for-each-ref', `--count=${MAX_REFS + 1}`, '--sort=-committerdate', '--format=%(refname)%00%(objectname)%00%(committerdate:iso-strict)%00%(upstream:short)%00%(subject)', 'refs/heads', 'refs/remotes', 'refs/tags'),
+        git(workspacePath, 'worktree', 'list', '--porcelain').catch(() => ''),
+        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
+        git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+        git(workspacePath, 'remote').catch(() => ''),
+    ]);
+    const checkedOut = new Map();
+    let worktree = null;
+    for (const line of rawWorktrees.split('\n')) {
+        if (line.startsWith('worktree '))
+            worktree = line.slice('worktree '.length).trim();
+        else if (line.startsWith('branch ') && worktree) {
+            checkedOut.set(line
+                .slice('branch '.length)
+                .trim()
+                .replace(/^refs\/heads\//, ''), worktree);
+        }
+    }
+    const lines = raw.split('\n').filter(Boolean);
+    const truncated = lines.length > MAX_REFS;
+    const refs = [];
+    for (const line of lines.slice(0, MAX_REFS)) {
+        const [refname, sha, date, upstream, ...subjectParts] = line.split('\0');
+        if (!refname || !sha)
+            continue;
+        // `refs/remotes/origin/HEAD` is a symbolic pointer, not a branch — drawing
+        // it puts a duplicate of the default branch in every picker.
+        if (refname.endsWith('/HEAD'))
+            continue;
+        const type = refname.startsWith('refs/tags/')
+            ? 'tag'
+            : refname.startsWith('refs/remotes/')
+                ? 'remote'
+                : 'head';
+        const name = refname.replace(/^refs\/(heads|remotes|tags)\//, '');
+        refs.push({
+            name: name.slice(0, 200),
+            type,
+            isHead: type === 'head' && name === currentBranch,
+            sha,
+            subject: maskString(subjectParts.join('\0')).slice(0, 300),
+            date: (date ?? '').slice(0, 40),
+            upstream: upstream ? upstream.slice(0, 200) : null,
+            checkedOutIn: type === 'head' ? (checkedOut.get(name) ?? null) : null,
         });
     }
-    return { branch, baseBranch, mergeBase: base, commits, hasMore };
+    return {
+        refs,
+        currentBranch: currentBranch === 'HEAD' ? null : currentBranch,
+        currentSha,
+        remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
+        truncated,
+    };
+}
+/**
+ * The truth about the checkout everything is actually built from.
+ *
+ * The product used to collect exactly this during path validation and throw it
+ * away, which is why it could never answer «is the running build yours» — the
+ * question behind «how do I know docker was not rebuilt». Read-only.
+ */
+export async function workspaceState(workspacePath) {
+    const [branchRaw, sha, porcelain, upstreamRaw, remotesRaw, meta] = await Promise.all([
+        git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null),
+        git(workspacePath, 'rev-parse', 'HEAD').catch(() => null),
+        git(workspacePath, 'status', '--porcelain').catch(() => ''),
+        git(workspacePath, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').catch(() => null),
+        git(workspacePath, 'remote').catch(() => ''),
+        git(workspacePath, 'log', '-1', '--format=%s%x00%cI', 'HEAD', '--').catch(() => ''),
+    ]);
+    const branch = branchRaw === 'HEAD' ? null : branchRaw;
+    const upstream = upstreamRaw ? sanitizeBranch(upstreamRaw) : null;
+    const distance = upstream ? await aheadBehind(workspacePath, upstream, 'HEAD') : null;
+    const [subject, date] = meta.split('\0');
+    const dirtyLines = porcelain.split('\n').filter(Boolean);
+    return {
+        branch,
+        sha,
+        subject: maskString(subject ?? '').slice(0, SUBJECT_CAP),
+        date: (date ?? '').slice(0, 40),
+        dirty: dirtyLines.length > 0,
+        dirtyFiles: dirtyLines.length,
+        upstream,
+        ahead: distance?.ahead ?? null,
+        behind: distance?.behind ?? null,
+        remotes: remotesRaw.split('\n').filter(Boolean).slice(0, 20),
+    };
 }
 /**
  * A path in a commit must name a FILE. A directory pathspec matches everything
@@ -476,19 +2003,31 @@ async function assertPathIsBlob(workspacePath, sha, relPath) {
  * thrown away with `reset --hard`, which is still in the object store
  * (QA-105 security round).
  */
-async function assertCommitIsVisible(workspacePath, sha, branch) {
-    const safeBranch = sanitizeBranch(branch);
-    if (!safeBranch)
+async function assertCommitIsVisible(workspacePath, sha, branch, baseBranch, selector) {
+    const safeBranch = branch ? sanitizeBranch(branch) : null;
+    if (branch && !safeBranch)
         throw new Error('Invalid branch name');
-    const { baseRef } = await resolveBase(workspacePath, safeBranch);
-    for (const ref of [safeBranch, assertRefArgument(baseRef)]) {
-        const reachable = await git(workspacePath, 'merge-base', '--is-ancestor', sha, ref)
-            .then(() => true)
-            .catch(() => false);
-        if (reachable)
-            return;
+    const always = [];
+    if (safeBranch) {
+        always.push(safeBranch);
+        const { baseRef } = await resolveBase(workspacePath, safeBranch, baseBranch);
+        always.push(assertRefArgument(baseRef));
     }
-    throw new Error('That commit is not part of this session history');
+    // Session 14 widens this by exactly the refs the LOG was allowed to walk —
+    // no wider. Without a selector it stays the session's two refs, which is what
+    // closed the QA-105 hole: naming the sha of a commit thrown away with
+    // `reset --hard` used to read it straight out of the object store.
+    const scope = selector
+        ? resolveRefScope(selector, always)
+        : { refs: always, namespaces: [], namespacePaths: [] };
+    if (scope.refs.length === 0 && scope.namespacePaths.length === 0) {
+        throw new Error('That commit is not part of this history');
+    }
+    if (await reachableFromScope(workspacePath, sha, scope))
+        return;
+    throw new Error(safeBranch
+        ? 'That commit is not part of this session history'
+        : 'That commit is not reachable from any branch, remote or tag being shown');
 }
 /**
  * One commit: its metadata and the files it touched, or — when `filePath` is
@@ -499,11 +2038,17 @@ async function assertCommitIsVisible(workspacePath, sha, branch) {
  * parents, and the answer to "what did this merge bring onto my branch" comes
  * out empty. For an ordinary commit the flag changes nothing.
  */
-export async function gitShow(workspacePath, sha, filePath, branch) {
+export async function gitShow(workspacePath, sha, filePath, branch, baseBranch, selector) {
     if (!isCommitSha(sha))
         throw new Error('Invalid commit sha');
-    if (branch !== undefined)
-        await assertCommitIsVisible(workspacePath, sha, branch);
+    // A read with no visibility scope at all is refused rather than allowed: the
+    // workspace-level graph (session 14) has no session branch, and «no branch
+    // given» used to mean «skip the check», which would have handed that route
+    // every object in the repository.
+    if (branch === undefined && selector === undefined) {
+        throw new Error('A commit read must name the history it belongs to');
+    }
+    await assertCommitIsVisible(workspacePath, sha, branch, baseBranch, selector);
     if (filePath !== undefined) {
         const relPath = safeHistoryPath(filePath);
         await assertPathIsBlob(workspacePath, sha, relPath);
@@ -520,7 +2065,8 @@ export async function gitShow(workspacePath, sha, filePath, branch) {
         git(workspacePath, 'show', '--format=', '--numstat', '-M', '--diff-merges=first-parent', sha, '--'),
         git(workspacePath, 'show', '--format=', '--name-status', '-M', '--diff-merges=first-parent', sha, '--'),
     ]));
-    const [fullSha, parents, author, email, date, decoration, subject, ...bodyParts] = metaRaw.split('\0');
+    // ⚠️ Positional — mirrors SHOW_META_FORMAT exactly.
+    const [fullSha, parents, author, email, date, committer, committerEmail, committerDate, decoration, subject, ...bodyParts] = metaRaw.split('\0');
     if (!fullSha)
         throw new Error('Commit not found');
     const numstat = new Map();
@@ -560,24 +2106,59 @@ export async function gitShow(workspacePath, sha, filePath, branch) {
         author: maskString(author ?? '').slice(0, 200),
         authorEmail: maskString(email ?? '').slice(0, 200),
         date: (date ?? '').slice(0, 40),
+        committer: maskString(committer ?? '').slice(0, 200),
+        committerEmail: maskString(committerEmail ?? '').slice(0, 200),
+        committerDate: (committerDate ?? '').slice(0, 40),
         subject: maskString(subject ?? '').slice(0, SUBJECT_CAP),
         // The body may itself contain NULs' worth of sections — everything after
-        // the seventh separator belongs to it.
+        // the last named separator belongs to it.
         body: maskString(bodyParts.join('\0')).slice(0, BODY_CAP).trimEnd(),
-        refs: parseRefs(decoration ?? ''),
+        refs: parseRefs(decoration ?? '', await remoteNames(workspacePath)),
         files,
         truncated,
     };
 }
-export async function revertApply(workspacePath, commitSha) {
-    if (!/^[0-9a-f]{7,64}$/i.test(commitSha)) {
+async function revertApplyImpl(workspacePath, commitSha, expectedBase) {
+    if (!isCommitSha(commitSha)) {
         return { reverted: false, error: 'Invalid commit sha' };
     }
+    // The same drift guard «Apply» has (QA-107): a revert commit lands on
+    // whatever branch the project folder is on, and a folder that moved would
+    // take the revert with it. Reachability alone is not enough — a feature
+    // branch cut after the apply contains the commit too.
+    const safeBase = expectedBase ? sanitizeBranch(expectedBase) : null;
+    if (safeBase) {
+        const on = await git(workspacePath, 'rev-parse', '--abbrev-ref', 'HEAD').catch(() => null);
+        if (on !== safeBase) {
+            return {
+                reverted: false,
+                error: `The project folder is on ${on ?? 'another branch'}, but this work was applied to ${safeBase} — switch it back first`,
+            };
+        }
+    }
     const dirty = await git(workspacePath, 'status', '--porcelain');
     if (dirty) {
+        const paths = porcelainPaths(dirty);
         return {
             reverted: false,
-            error: 'The workspace working copy has uncommitted changes — commit or stash them on the server first',
+            workspaceDirty: true,
+            workspaceDirtyFiles: paths.slice(0, WORKSPACE_DIRTY_SAMPLE),
+            workspaceDirtyCount: paths.length,
+            error: WORKSPACE_DIRTY_MESSAGE,
+        };
+    }
+    // Until session 13 the sha was hard-wired to the session's own apply commit,
+    // so «which commit» was not a question. Now the API chooses it (undoing a
+    // revert reverts the REVERT), which makes the runner the last place that can
+    // check the choice is sane: only something already in the branch we are
+    // standing on may be taken back out of it.
+    const reachable = await git(workspacePath, 'merge-base', '--is-ancestor', commitSha, 'HEAD')
+        .then(() => true)
+        .catch(() => false);
+    if (!reachable) {
+        return {
+            reverted: false,
+            error: 'That commit is not in the branch the project folder is on',
         };
     }
     try {
@@ -593,4 +2174,44 @@ export async function revertApply(workspacePath, commitSha) {
     }
     return { reverted: true, revertSha: await git(workspacePath, 'rev-parse', 'HEAD') };
 }
+// ─── Writes bump the tree generation (QA-111 M2) ─────────────────────
+//
+// Wrappers rather than a line inside each body: every one of these has several
+// early returns and can throw, and «the tree may have changed» is true on all
+// of those paths — a conflicted pull leaves a modified tree, a refused discard
+// may have removed some paths before it stopped. Wrapping is the only shape
+// that cannot be forgotten on a branch added later.
+//
+// The bump happens AFTER the call settles: a read arriving mid-write has
+// nothing newer to be given, and starting a second scan against a tree being
+// modified only spends the machine this was written to spare.
+function afterWrite(fn, treeOf) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        finally {
+            for (const tree of treeOf(...args))
+                bumpTreeGeneration(tree);
+        }
+    };
+}
+export const gitCommit = afterWrite(gitCommitImpl, (worktreePath) => [worktreePath]);
+export const gitStage = afterWrite(gitStageImpl, (input) => [input.worktreePath]);
+export const gitUnstage = afterWrite(gitUnstageImpl, (input) => [input.worktreePath]);
+export const gitDiscard = afterWrite(gitDiscardImpl, (input) => [input.worktreePath]);
+export const gitPull = afterWrite(gitPullImpl, (input) => [input.worktreePath]);
+export const gitMergeAbort = afterWrite(gitMergeAbortImpl, (worktreePath) => [worktreePath]);
+// Apply and revert write to the PROJECT folder, and apply reads the session
+// worktree on the way — both trees are named so either panel refreshes true.
+export const applySession = afterWrite(applySessionImpl, (input) => [
+    input.workspacePath,
+    input.worktreePath,
+]);
+export const revertApply = afterWrite(revertApplyImpl, (workspacePath) => [workspacePath]);
+export const updateFromBase = afterWrite(updateFromBaseImpl, (input) => [
+    input.worktreePath,
+    input.workspacePath,
+]);
+export const gitPush = afterWrite(gitPushImpl, (input) => [input.workspacePath]);
 //# sourceMappingURL=gitops.js.map