mikser-io-git 2.1.0 → 2.3.0

package/README.md

@@ -37,6 +37,59 @@ mikser's API and MCP endpoints can write to **any registered collection**, not j
 
 **This is meant for a deployment target this plugin (and mikser) exclusively manages — not a developer's actively-edited local checkout.** Bootstrap checks out and holds the write branch for the ENTIRE working folder, not just the collections in `paths`. Point this at a developer's own local clone of the project and it will switch their currently-checked-out branch out from under them — same risk that existed before, just now at the scope of the whole project directory instead of one subfolder. A server deployment where nobody manually runs `git` in that checkout is the intended shape.
 
+## Undo (MCP only)
+
+An agent's request is one **change set**: however many files it wrote, committed
+together, stamped with a `Mikser-Change-Set` trailer and the agent's own summary
+as the subject. `mikser_changes` lists them; `mikser_undo` takes one back.
+
+```
+mikser_changes                     → recent change sets, newest first
+mikser_undo({ id, dryRun: true })  → what it would do, touching nothing
+mikser_undo({ id, dryRun: false }) → apply it
+```
+
+**Only agent writes are undoable.** API writes and human edits are committed
+too — the durable log never drops anything — but into unattributed sweep
+commits with no trailer, and the trailer is the permission boundary. Those
+callers have git; an undo they could reach would be an undo able to remove work
+it never made.
+
+**It removes a contribution, it does not restore a snapshot.** Documents added
+through the API since, and edits made by hand, are kept. The undo lands as an
+ordinary forward commit, so history is never rewritten, the deploy branch is
+never force-pushed, and the undo is itself an undoable change set.
+
+Two independent things stop an undo, and they need different answers:
+
+| | means |
+| --- | --- |
+| `conflict` | a later change edited the same content — it cannot be applied automatically, and no `force` overrides it |
+| `dangling` | something added since references what this undo would REMOVE |
+
+The second is the dangerous one. Git applies it perfectly cleanly and the site
+breaks anyway, because the new document points at a layout that no longer
+exists — so the check runs against the engine's reference index rather than
+against the patch. `force: true` proceeds regardless; nothing bypasses a
+conflict.
+
+A dry run and a refusal never touch the working folder. The patch is tested
+with `git apply --check` against a copy in the system temp dir, because a
+half-applied revert in a deployed checkout means the build stops — an undo that
+takes the site down is worse than the change it was undoing.
+
+### Why the commit scope matters
+
+Staging by folder is what the durable-log sweep does, and it is wrong for a
+change set. If an agent edits one document while a second is created through
+the API a moment later, a folder-scoped `git add` puts both in the agent's
+commit — and undoing the agent then deletes the API's document. Change-set
+commits stage exactly the paths that set wrote, so the commit's contents match
+its label.
+
+Requires the `mcp` plugin. Without it the tools are not registered and the
+plugin behaves exactly as before.
+
 ## Install
 
 ```bash
@@ -193,15 +246,28 @@ Both forges have *some* direct-merge concept, but they're not the same feature a
 
 Pull requests, by contrast, are nearly identical between the two — `POST .../pulls { title, head, base }` creates one on both GitHub and Gitea. And a PR gives you something the direct-merge endpoints don't: a real conflict surface. A `/merges` 409 is a status code with nowhere to look; a conflicted PR is a page that names the exact files in conflict and offers to resolve them in the forge's own UI. That's a better fit for "leave it open, let a human resolve it" than either forge's direct-merge shortcut.
 
+## Requirements
+
+- **git 2.31 or newer** on the machine running mikser. The auth token is
+  delivered to git through `GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_n` /
+  `GIT_CONFIG_VALUE_n`, which older git ignores — it would fall back to
+  unauthenticated access and fail against a private repo. 2.31 shipped in
+  March 2021; `git --version` if unsure.
+- No runtime npm dependencies. Everything goes through the `git` binary.
+
 ## Security
 
-- **The auth token is never written to disk.** It's passed as a one-off `http.extraheader` on the specific git command that needs it (`clone`/`fetch`/`push`), never embedded in the remote URL — an embedded `https://token@host/...` remote persists into `.git/config` in plaintext and leaks into `git remote -v` output and any log line that happens to echo the remote.
+- **The auth token is never written to disk, and never appears in the process's arguments.** It's passed as a one-off `http.extraheader` for the specific git command that needs it (`clone`/`fetch`/`push`/`ls-remote`), delivered through the environment (`GIT_CONFIG_COUNT` / `GIT_CONFIG_KEY_0` / `GIT_CONFIG_VALUE_0`, git 2.31+) rather than as a `-c` argument, and never embedded in the remote URL.
+
+  Three places a credential can leak, and what each avoids: an embedded `https://token@host/...` remote persists into `.git/config` in plaintext and shows up in `git remote -v` and any log line echoing the remote; a `-c http.extraheader=...` argument lands in the process's argument list, which is world-readable on Linux (`/proc/<pid>/cmdline` is `-r--r--r--`, while `/proc/<pid>/environ` is `-r--------`) and can surface in an `err.stderr` a caller then logs; the environment form has neither property and the same one-command lifetime. Note that base64 here is encoding, not encryption — it is the HTTP Basic wire format, so keeping it out of world-readable places is the whole protection.
 - **Every git invocation goes through `execFile` with an argv array — never a shell string.** Commit messages are built from a file count, not raw content, but nothing here ever risks passing arbitrary content through a shell regardless.
+- **A timer body can never end the process.** Both schedulers here — the debounced sync pass and the inbound poll — run for the life of a watch server, and Node has treated an unhandled rejection as fatal since v15 while mikser installs no process-level handler. `pullInbound` returns a result shape for every outcome including a failed `fetch`, and both callbacks are wrapped besides: a transient remote failure must not take down the build and the site, least of all in a supervisor restart loop.
+- **Git operations are serialised per instance.** The sync pass and the inbound poll share one checkout; without a queue they overlap and lose to `index.lock`, or worse, commit while an inbound merge is in progress.
 - **The write branch is force-pushed only after a successful promotion**, using `--force-with-lease` (refuses if the remote moved unexpectedly since the last fetch) rather than a bare `--force`. This is safe specifically because `mikser`/`writeBranch` is a branch this plugin owns exclusively — nothing else's history is ever at risk on it.
 
 ## Verified end-to-end
 
-The unit suite (59 tests) covers every pure module directly, the forge adapters via an injected `fetchImpl` mock, and — critically for the working-folder-as-checkout model — the pathspec scope itself against a real temp git repo (`test/git.test.js`'s "pathspec scoping" suite: a config-file edit and a whole new out-of-scope directory are both proven invisible to a `paths`-scoped add, while an in-scope file commits normally). Beyond the unit suite, this has been run against **real GitHub repos and mikser's own example blog** — not just mocks:
+The unit suite (73 tests) covers every pure module directly, the forge adapters via an injected `fetchImpl` mock, and — critically for the working-folder-as-checkout model — the pathspec scope itself against a real temp git repo (`test/git.test.js`'s "pathspec scoping" suite: a config-file edit and a whole new out-of-scope directory are both proven invisible to a `paths`-scoped add, while an in-scope file commits normally). Beyond the unit suite, this has been run against **real GitHub repos and mikser's own example blog** — not just mocks:
 
 - **The "adopt an existing non-empty folder" recipe** (see [First connect](#first-connect--and-why-it-can-refuse-to-guess)), run by hand exactly as documented, against the real blog's working folder — `mikser.config.js`, `node_modules/`, `layouts/`, `documents/`, everything — and a fresh throwaway GitHub repo. `refuse` fired correctly on the very first connect attempt (confirming that's now the expected first-run path, not an edge case); the manual recipe attached history without touching a file; `git status` afterward showed exactly the expected divergence.
 - **The `paths` scope boundary, live, not just unit-tested.** With `paths: ['documents', 'layouts']` on that same checkout: a build with only a `mikser.config.js`/`LICENSE` edit produced **zero commits** — no `git: committed + pushed` line at all; a build with a real `layouts/` edit committed, pushed, and promoted normally. A fresh clone of the repo afterward showed the tree contained **only** `documents/`, `layouts/`, and the seed file — no `mikser.config.js`, no `node_modules`, nothing leaked from outside `paths`.

package/index.js

@@ -53,9 +53,27 @@ import { gatherFolderState, decideBootstrap, performClone, performVerify } from
 import { commitAndPushWriteBranch, promote } from './lib/sync.js'
 import { pullInbound } from './lib/inbound.js'
 import { reduceDebounce, IDLE_DEBOUNCE_STATE } from './lib/debounce.js'
+import { createGitQueue } from './lib/queue.js'
 
 const REANNOUNCE_MS = 30 * 60 * 1000   // re-log a still-open conflict at most every 30 min
 
+// Run a timer body so that nothing it does can end the process.
+//
+// Both schedulers here fire for the life of a watch server, and an async
+// callback that rejects is fatal — Node has treated an unhandled rejection
+// as process-ending since v15, and mikser core installs no handler. The
+// failure mode this prevents is a transient remote error taking down the
+// build AND the site, and looping under a supervisor.
+function withGuard(logger, what, fn) {
+    Promise.resolve()
+        .then(fn)
+        .catch(err => logger?.error('git: %s failed — %s', what, err?.stderr || err?.message || err))
+}
+
+
+import { pendingChangeSets, clearChangeSets } from 'mikser-io'
+import { registerUndoTools } from './lib/mcp.js'
+
 export function git(options = {}) {
     const {
         url, paths, forge, targetBranch, writeBranch,
@@ -69,6 +87,7 @@ export function git(options = {}) {
         // scopes this instance's reach within it.
         const folder = runtime.options.workingFolder
 
+        const enqueueGit = createGitQueue()
         let debounceState = IDLE_DEBOUNCE_STATE
         let timer = null
         let pollTimer = null
@@ -79,7 +98,17 @@ export function git(options = {}) {
         async function runSyncPass(logger) {
             debounceState = IDLE_DEBOUNCE_STATE
             try {
-                const { committed } = await commitAndPushWriteBranch(folder, { paths, writeBranch, message, author, token })
+                // Claimed sets are drained only once their paths are actually
+                // committed. A set whose commit throws stays pending and is
+                // retried next pass rather than silently losing attribution.
+                const claimed = pendingChangeSets()
+                const consumed = []
+                const { committed } = await commitAndPushWriteBranch(folder, {
+                    paths, writeBranch, message, author, token,
+                    changeSets: claimed,
+                    onCommitted: (id) => consumed.push(id),
+                })
+                clearChangeSets(consumed)
                 if (!committed) return
                 logger.info('git: committed + pushed to %s', writeBranch)
 
@@ -111,7 +140,7 @@ export function git(options = {}) {
         function scheduleFire(logger) {
             if (timer) clearTimeout(timer)
             const delay = Math.max(0, debounceState.fireAt - Date.now())
-            timer = setTimeout(() => runSyncPass(logger), delay)
+            timer = setTimeout(() => withGuard(logger, 'sync pass', () => enqueueGit(() => runSyncPass(logger))), delay)
             timer.unref?.()
         }
 
@@ -144,13 +173,33 @@ export function git(options = {}) {
                 targetBranch, forge,
             )
 
+            // Undo is an MCP-only surface. API and human writes are not
+            // attributed and are deliberately not undoable — those callers
+            // have git, and an undo they could reach would be an undo that
+            // could remove someone else's work.
+            if (runtime.options.mcp) {
+                registerUndoTools(runtime.options.mcp, {
+                    folder, writeBranch, runtime, useLogger,
+                    isInert: () => inert,
+                    sync: () => enqueueGit(() => runSyncPass(useLogger())),
+                })
+            }
+
             // Inbound polling — watch mode only; a one-shot build has no
             // "later" to pull into. Webhook delivery is not implemented
             // (see README); poll is the only supported inbound trigger.
             if (runtime.options.watch && pollIntervalMs > 0) {
-                pollTimer = setInterval(async () => {
+                pollTimer = setInterval(() => {
                     if (inert) return
-                    await pullInbound(folder, { writeBranch, targetBranch, token, logger })
+                    // Belt AND braces. pullInbound is written not to throw,
+                    // but a timer callback is the one place where being
+                    // wrong about that is fatal rather than noisy: Node has
+                    // treated an unhandled rejection as process-ending since
+                    // v15, and mikser installs no handler. Anything reaching
+                    // here is a bug worth logging, not worth killing the
+                    // build server for.
+                    withGuard(logger, 'inbound poll', () => enqueueGit(() =>
+                        pullInbound(folder, { writeBranch, targetBranch, token, logger })))
                 }, pollIntervalMs)
                 pollTimer.unref?.()
             }
@@ -180,7 +229,7 @@ export function git(options = {}) {
                     logger.warn('git: build had failures (%s) — not syncing', culprits.join(', '))
                     return
                 }
-                await runSyncPass(logger)
+                await enqueueGit(() => runSyncPass(logger))
                 return
             }
 

package/lib/changeset-commit.js

@@ -0,0 +1,59 @@
+// The trailer format that makes a commit undoable.
+//
+// Trailers rather than tags or notes: a tag per change set means thousands of
+// refs, and notes are not fetched by default so they vanish on the next clone.
+// Trailers are ordinary commit-message lines, they survive every normal git
+// operation, and `git log --grep` finds them.
+//
+// The change-set id is also the PERMISSION boundary, not only the grouping
+// key. Undo reverts commits carrying one and never touches the unattributed
+// sweep commits, so a human's hand edit or an API write cannot be removed by
+// an agent that did not make it.
+
+export const CHANGE_SET_TRAILER = 'Mikser-Change-Set'
+export const PRINCIPAL_TRAILER  = 'Mikser-Principal'
+export const UNDO_TRAILER       = 'Mikser-Undo-Of'
+
+export function changeSetTrailers(set) {
+    const lines = [`${CHANGE_SET_TRAILER}: ${set.id}`]
+    if (set.principal) lines.push(`${PRINCIPAL_TRAILER}: ${set.principal}`)
+    if (set.undoOf)    lines.push(`${UNDO_TRAILER}: ${set.undoOf}`)
+    return lines.join('\n')
+}
+
+// Parse `git log` output into change sets, newest first.
+//
+// One record per SET rather than per commit: a set can span several commits
+// when writes arrive across cycles, and undo has to remove all of them or it
+// removes half a request.
+export function parseChangeSetLog(raw) {
+    const sets = new Map()
+    for (const block of String(raw ?? '').split('\x1e').filter(b => b.trim())) {
+        const [sha, at, subject, ...bodyLines] = block.split('\x1f')
+        const body = bodyLines.join('\x1f')
+        const id = matchTrailer(body, CHANGE_SET_TRAILER)
+        if (!id) continue
+        let set = sets.get(id)
+        if (!set) {
+            set = {
+                id,
+                summary: subject?.trim() || null,
+                principal: matchTrailer(body, PRINCIPAL_TRAILER),
+                undoOf: matchTrailer(body, UNDO_TRAILER),
+                at: Number(at) * 1000,
+                commits: [],
+            }
+            sets.set(id, set)
+        }
+        // Log order is newest-first; a set's commits are recorded oldest-first
+        // so a revert can walk them newest-first without re-sorting.
+        set.commits.unshift(sha)
+        set.at = Math.max(set.at, Number(at) * 1000)
+    }
+    return [...sets.values()]
+}
+
+function matchTrailer(body, name) {
+    const m = new RegExp(`^${name}:\\s*(.+)$`, 'm').exec(body ?? '')
+    return m ? m[1].trim() : null
+}

package/lib/git.js

@@ -10,6 +10,9 @@
 
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
 
 const execFileAsync = promisify(execFile)
 
@@ -49,32 +52,49 @@ export async function remoteUrl(folder, remote = 'origin') {
     }
 }
 
-// Auth via a short-lived per-request header, never embedded in the
-// remote URL or written to .git/config — an embedded
-// `https://token@host/...` remote leaks the token into `git remote -v`
-// output and any log/error that echoes the URL. `http.extraheader` is
-// passed as a one-off `-c` flag on the specific command that needs it
-// (fetch/pull/push/clone), so it never persists to disk.
-function authArgs(token) {
-    if (!token) return []
+// Auth via a short-lived per-command header, never embedded in the remote
+// URL or written to .git/config — an embedded `https://token@host/...`
+// remote leaks the token into `git remote -v` output and any log or error
+// that echoes the URL.
+//
+// Delivered through the ENVIRONMENT rather than as a `-c` argument.
+// Same semantics, same one-command lifetime, same no-persistence — but a
+// process's arguments are world-readable and its environment is not:
+//
+//     -r--r--r--   /proc/<pid>/cmdline
+//     -r--------   /proc/<pid>/environ
+//
+// As a `-c http.extraheader=...` argument the base64 credential is
+// readable by any local user for as long as the git subprocess runs
+// (base64 is encoding, not encryption), and it can surface in an
+// `err.stderr` that a caller then logs. GIT_CONFIG_COUNT / _KEY_n /
+// _VALUE_n is git's own supported equivalent (2.31+) and keeps it out of
+// both places.
+function authEnv(token) {
+    if (!token) return undefined
     const b64 = Buffer.from(`x-access-token:${token}`).toString('base64')
-    return ['-c', `http.extraheader=AUTHORIZATION: basic ${b64}`]
+    return {
+        ...process.env,
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'http.extraheader',
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${b64}`,
+    }
 }
 
 export async function clone(url, folder, { branch, token } = {}) {
-    const args = [...authArgs(token), 'clone', ...(branch ? ['--branch', branch] : []), url, folder]
+    const args = ['clone', ...(branch ? ['--branch', branch] : []), url, folder]
     // clone's cwd doesn't matter (destination is a full path); run from
     // the parent so a not-yet-existing `folder` isn't required as cwd.
-    await run('.', args)
+    await run('.', args, { env: authEnv(token) })
 }
 
 export async function fetch(folder, { remote = 'origin', token } = {}) {
-    await run(folder, [...authArgs(token), 'fetch', remote])
+    await run(folder, ['fetch', remote], { env: authEnv(token) })
 }
 
 export async function push(folder, refspec, { remote = 'origin', token, force = false } = {}) {
-    const args = [...authArgs(token), 'push', ...(force ? ['--force-with-lease'] : []), remote, refspec]
-    await run(folder, args)
+    const args = ['push', ...(force ? ['--force-with-lease'] : []), remote, refspec]
+    await run(folder, args, { env: authEnv(token) })
 }
 
 // Non-fast-forward pushes throw with stderr containing "non-fast-forward"
@@ -127,6 +147,73 @@ export async function addAll(folder, paths) {
     await run(folder, ['add', '-A', ...pathspecArgs(paths)])
 }
 
+// Stage an explicit list of files — the change-set path. Distinct from
+// addAll's folder pathspec on purpose: this stages what a request wrote and
+// nothing that merely happened to be dirty beside it.
+//
+// `--` separates paths from revisions so a file named like a branch cannot be
+// reinterpreted, and `-A` keeps deletions staged as deletions.
+export async function addPaths(folder, files) {
+    if (!files?.length) return
+    await run(folder, ['add', '-A', '--', ...files])
+}
+
+// The reverse patch for a commit: the diff from it back to its parent.
+//
+// This is what makes a dry run possible at all. `git revert` has no
+// --dry-run, so the choice is to attempt it in the live working folder and
+// deal with a conflicted tree — which for a deployed site means the build
+// stops — or to compute the patch and ask `git apply --check` whether it
+// would land. The second never touches the tree.
+export async function reversePatch(folder, sha, files) {
+    const args = ['diff', '--binary', sha, `${sha}^`]
+    if (files?.length) args.push('--', ...files)
+    return await run(folder, args)
+}
+
+// Would this patch apply cleanly? Changes nothing either way.
+export async function patchApplies(folder, patch) {
+    if (!patch?.trim()) return true
+    return await withPatchFile(patch, async (file) => {
+        try {
+            await run(folder, ['apply', '--check', '--binary', file])
+            return true
+        } catch {
+            return false
+        }
+    })
+}
+
+export async function applyPatch(folder, patch) {
+    if (!patch?.trim()) return
+    await withPatchFile(patch, (file) => run(folder, ['apply', '--binary', file]))
+}
+
+// The patch goes to the system temp dir, never inside the repo: a stray file
+// in the working folder is one the plugin's own sweep would commit.
+async function withPatchFile(patch, fn) {
+    const dir = await mkdtemp(path.join(tmpdir(), 'mikser-git-patch-'))
+    const file = path.join(dir, 'undo.patch')
+    try {
+        await writeFile(file, patch.endsWith('\n') ? patch : `${patch}\n`, 'utf8')
+        return await fn(file)
+    } finally {
+        await rm(dir, { recursive: true, force: true })
+    }
+}
+
+// Commits carrying a change-set trailer, newest first, with unit separators
+// that cannot occur in a commit message.
+export async function logChangeSets(folder, { branch, limit = 50, id } = {}) {
+    const args = [
+        'log', branch ?? 'HEAD',
+        `--max-count=${Math.max(1, Math.min(limit, 500))}`,
+        '--format=%H%x1f%at%x1f%s%x1f%b%x1e',
+        '--grep', id ? `^Mikser-Change-Set: ${id}$` : '^Mikser-Change-Set: ',
+    ]
+    return await run(folder, args)
+}
+
 export async function commit(folder, message, { author } = {}) {
     const args = ['commit', '-m', message]
     if (author?.name)  args.push('--author', `${author.name} <${author.email ?? ''}>`)
@@ -164,7 +251,7 @@ export async function branchExistsLocal(folder, branch) {
 export async function branchExistsRemote(folder, branch, { remote = 'origin', token } = {}) {
     // ls-remote hits the network but needs no local ref state — safe
     // to call before any fetch has happened.
-    const out = await run(folder, [...authArgs(token), 'ls-remote', '--heads', remote, branch])
+    const out = await run(folder, ['ls-remote', '--heads', remote, branch], { env: authEnv(token) })
     return out.length > 0
 }
 

package/lib/inbound.js

@@ -23,14 +23,48 @@
 
 import * as git from './git.js'
 
+// Never throws. Every caller is a timer, and a timer callback that
+// rejects takes the whole process down: Node has treated an unhandled
+// rejection as fatal since v15, mikser installs no process-level handler,
+// and the poll runs every few minutes for the life of a watch server. A
+// network blip, a DNS failure or an expired token would kill the build and
+// the site, and under a supervisor it becomes a restart loop.
+//
+// So the outcome is always a returned shape. A fetch that fails is the same
+// class of event as a merge that conflicts — remote trouble, reported, try
+// again next tick — and it is reported the same way.
 export async function pullInbound(folder, { writeBranch, targetBranch, token, logger }) {
-    await git.fetch(folder, { token })
+    try {
+        await git.fetch(folder, { token })
+    } catch (err) {
+        // Nothing was touched: fetch writes only to remote-tracking refs,
+        // and a failed one leaves even those alone.
+        logger?.warn(
+            'git: inbound fetch failed — %s. Working folder untouched; retrying on the next poll.',
+            err.stderr || err.message,
+        )
+        return { merged: false, fetchFailed: true, reason: err.stderr || err.message }
+    }
 
     for (const ref of [writeBranch, targetBranch]) {
         try {
             await git.mergeBranch(folder, `origin/${ref}`)
         } catch (err) {
-            await git.abortMerge(folder)
+            // A failed abort would throw straight past this handler and
+            // become the fatal rejection the fetch guard above exists to
+            // prevent. Report it instead: the folder is then in a merge
+            // state a human has to look at, which is worth saying loudly.
+            try {
+                await git.abortMerge(folder)
+            } catch (abortErr) {
+                logger?.error(
+                    'git: inbound merge of origin/%s conflicted AND `git merge --abort` failed — %s. ' +
+                    'The working folder is mid-merge and may contain conflict markers; mikser will render them as content. '
+                    + 'Resolve manually before the next cycle.',
+                    ref, abortErr.stderr || abortErr.message,
+                )
+                return { merged: false, conflictedRef: ref, abortFailed: true, reason: abortErr.stderr || abortErr.message }
+            }
             logger?.error(
                 'git: inbound merge of origin/%s conflicted — aborted, working folder left untouched. ' +
                 'Resolve manually: cd <folder> && git merge origin/%s (or origin/%s) and fix the conflicts. %s',

package/lib/mcp.js

@@ -0,0 +1,141 @@
+// The undo surface, deliberately MCP-only.
+//
+// API and human writes are not attributed and are not undoable here. That is
+// the scope, not a limitation to fix later: those callers have git, and an
+// undo they could reach would be an undo able to remove work it never made.
+// The change-set trailer is the permission boundary — nothing without one is
+// reachable from these tools.
+
+import { z } from 'zod'
+import { recordChangeSetWrite } from 'mikser-io'
+
+import { listChangeSets, previewUndo } from './undo.js'
+import * as git from './git.js'
+
+const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] })
+const fail = (message) => ({ content: [{ type: 'text', text: message }], isError: true })
+
+export function registerUndoTools(mcp, { folder, writeBranch, runtime, useLogger, isInert, sync }) {
+    if (!mcp) return
+    const logger = useLogger?.()
+
+    mcp.simpleTool(
+        'mikser_changes',
+        'List recent change sets — the units of work an agent can undo. Each is one request, however many files '
+        + 'it wrote, with the summary given when it was made.\n\n'
+        + 'Only agent writes appear. Documents created through the API and files edited by hand are committed too, '
+        + 'but unattributed and deliberately not undoable from here — reverting them would remove work this tool '
+        + 'has no claim on.',
+        {
+            limit: z.number().int().positive().max(50).optional()
+                .describe('How many change sets to list, newest first. Default 20.'),
+        },
+        async ({ limit = 20 } = {}) => {
+            if (isInert?.()) return fail('git: plugin is inert after a bootstrap refusal — no history to read.')
+            try {
+                const sets = await listChangeSets(folder, { branch: writeBranch, limit })
+                return ok({
+                    count: sets.length,
+                    changes: sets.map(set => ({
+                        id: set.id,
+                        summary: set.summary,
+                        at: new Date(set.at).toISOString(),
+                        files: set.commits.length,
+                        ...(set.principal ? { by: set.principal } : {}),
+                        ...(set.undoOf ? { undoOf: set.undoOf } : {}),
+                    })),
+                    next: 'Pass an `id` to mikser_undo with dryRun first — it reports whether the undo applies '
+                        + 'cleanly and whether anything added since depends on what it would remove.',
+                })
+            } catch (err) {
+                logger?.error('git: mikser_changes failed — %s', err.stderr || err.message)
+                return fail(err.stderr || err.message)
+            }
+        },
+    )
+
+    mcp.simpleTool(
+        'mikser_undo',
+        'Take back one change set, keeping everything that happened after it.\n\n'
+        + 'This is not a restore to a previous state: documents added through the API since, and edits made by '
+        + 'hand, are kept. Only the named change set\'s contribution is removed, as an ordinary forward commit — '
+        + 'so history is never rewritten, the deploy branch never has to be force-pushed, and the undo is itself '
+        + 'an undoable change set.\n\n'
+        + 'ALWAYS dryRun first. Two independent things can stop an undo, and they need different answers: a later '
+        + 'edit to the same content makes it inapplicable (`conflict`), and a document added since that references '
+        + 'something this undo REMOVES makes it destructive (`dangling`). The second is the dangerous one — git '
+        + 'applies it cleanly and the site breaks anyway, which is why the reference graph is consulted rather '
+        + 'than just the patch.',
+        {
+            id:     z.string().describe('Change set id, from mikser_changes.'),
+            dryRun: z.boolean().optional().describe('Report what the undo would do and change nothing. Default true — pass false to actually apply it.'),
+            force:  z.boolean().optional().describe('Apply even when the undo would leave references dangling. Never bypasses a conflict, which cannot be applied at all.'),
+        },
+        async ({ id, dryRun = true, force = false } = {}) => {
+            if (isInert?.()) return fail('git: plugin is inert after a bootstrap refusal — refusing to touch the folder.')
+            if (!id) return fail('id is required')
+            try {
+                const preview = await previewUndo(folder, { id, branch: writeBranch, runtime })
+                if (!preview.ok) return ok(preview)
+
+                const { patch, ...report } = preview
+                if (dryRun) {
+                    return ok({
+                        ...report, dryRun: true,
+                        wouldApply: preview.applies && (!preview.dangling.length || force),
+                        next: preview.applies
+                            ? 'Call again with dryRun: false to apply.'
+                            : 'This one cannot be applied automatically. Say so plainly rather than trying '
+                                + 'variations — the content it touched has moved on.',
+                    })
+                }
+
+                // A patch that does not apply is refused outright. Attempting
+                // it would leave the working folder half-changed, and for a
+                // deployed site that means the build stops — an undo that
+                // takes the site down is worse than the change it undoes.
+                if (!preview.applies) {
+                    return ok({ ...report, ok: false, refused: 'conflict' })
+                }
+                if (preview.dangling.length && !force) {
+                    return ok({
+                        ...report, ok: false, refused: 'would-dangle',
+                        next: 'Pass force: true only if removing those references is intended.',
+                    })
+                }
+
+                await git.applyPatch(folder, patch)
+
+                // Recorded as its own change set so the commit carries a
+                // trailer and the undo can itself be undone.
+                const undoId = `undo-${id}-${preview.set.commits}-${Math.round(preview.set.at)}`
+                for (const rel of preview.touched) {
+                    recordChangeSetWrite({
+                        changeSet: undoId,
+                        summary: `Undo: ${preview.set.summary ?? id}`,
+                        principal: 'agent',
+                        undoOf: id,
+                        uri: `${runtime.options.workingFolder}/${rel}`,
+                    })
+                }
+
+                // The files are on disk now; the engine's watcher will pick
+                // them up. Nudging the sync pass means the undo reaches the
+                // remote without waiting for the next debounce window.
+                sync?.()
+
+                return ok({
+                    ok: true, undone: id, changeSet: undoId,
+                    summary: preview.set.summary,
+                    touched: preview.touched,
+                    removed: preview.removes,
+                    next: 'The files are back to their pre-change state and will rebuild on the next cycle. '
+                        + `Undo this undo with mikser_undo({ id: '${undoId}' }).`,
+                })
+            } catch (err) {
+                logger?.error('git: mikser_undo failed — %s', err.stderr || err.message)
+                return fail(err.stderr || err.message)
+            }
+        },
+    )
+}

package/lib/queue.js

@@ -0,0 +1,24 @@
+// One git operation at a time, per plugin instance.
+//
+// The sync pass and the inbound poll are independent timers — debounced
+// seconds after a green cycle, and every few minutes — over the SAME
+// checkout. Nothing stopped them overlapping, and git serialises through
+// `index.lock`: the loser fails with "Another git process seems to be
+// running", which surfaces as an intermittent sync failure that retries
+// and looks like nothing. The worse shape is a commit landing while an
+// inbound merge is in progress, which commits the merge rather than the
+// intended change.
+//
+// A promise chain rather than a lock: each caller waits for the previous
+// operation to settle, in order, and a rejection cannot break the chain
+// because the guard already turned every body into a resolved promise.
+export function createGitQueue() {
+    let tail = Promise.resolve()
+    return function enqueue(fn) {
+        const next = tail.then(fn, fn)
+        // Swallow here only — the caller's own guard reports. Without this
+        // the chain itself would carry an unhandled rejection.
+        tail = next.catch(() => {})
+        return next
+    }
+}