agent-merge-broker 0.3.0

package/dist/validation.js

@@ -0,0 +1,75 @@
+import { resolveShell, runShell } from "./process.js";
+import { matchesAny } from "./patterns.js";
+import { ValidationError } from "./errors.js";
+const OUTPUT_LIMIT_BYTES = 64 * 1_024;
+function truncateOutput(value) {
+    if (Buffer.byteLength(value, "utf8") <= OUTPUT_LIMIT_BYTES)
+        return value;
+    const head = value.slice(0, 48 * 1_024);
+    const tail = value.slice(-16 * 1_024);
+    return `${head}\n... output truncated by Merge Broker ...\n${tail}`;
+}
+function renderCommand(command, taskId, files, shell) {
+    return command
+        .replaceAll("{taskId}", shell.quote(taskId ?? ""))
+        .replaceAll("{files}", files.map(shell.quote).join(" "));
+}
+/**
+ * A validator command is repository-trusted, but a lease token is a worker credential that no
+ * validator needs. Passing it through would hand every configured command the ability to submit or
+ * cancel on that worker's behalf.
+ */
+function validatorEnvironment(overrides) {
+    const { MERGE_BROKER_TOKEN: _token, ...inherited } = process.env;
+    return { ...inherited, ...overrides };
+}
+export async function runValidators(options) {
+    const shell = resolveShell(options.shell);
+    const results = [];
+    for (const validator of options.validators) {
+        if (options.scope === "focused" &&
+            validator.paths &&
+            validator.paths.length > 0 &&
+            !options.files.some((file) => matchesAny(file, validator.paths ?? []))) {
+            continue;
+        }
+        const command = renderCommand(validator.command, options.taskId, options.files, shell);
+        const startedAt = new Date();
+        const result = await runShell(command, {
+            cwd: options.cwd,
+            allowFailure: true,
+            timeoutMs: (validator.timeoutSeconds ?? 900) * 1_000,
+            shell,
+            env: {
+                ...validatorEnvironment(validator.env),
+                MERGE_BROKER_TASK_ID: options.taskId ?? "",
+                MERGE_BROKER_FILES: options.files.join("\n"),
+                MERGE_BROKER_BASE_SHA: options.baseSha,
+                MERGE_BROKER_HEAD_SHA: options.headSha,
+                MERGE_BROKER_BATCH_ID: options.batchId,
+            },
+        });
+        const finishedAt = new Date();
+        const validation = {
+            name: validator.name,
+            command,
+            scope: options.scope,
+            ...(options.taskId ? { taskId: options.taskId } : {}),
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            exitCode: result.exitCode,
+            stdout: truncateOutput(result.stdout),
+            stderr: truncateOutput(result.stderr),
+        };
+        results.push(validation);
+        if (result.exitCode !== 0) {
+            throw new ValidationError(`Validator \"${validator.name}\" failed.`, {
+                validation,
+                completedValidations: results,
+            });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/verify.d.ts

@@ -0,0 +1,40 @@
+import type { GitRepository } from "./git.js";
+import type { BatchProvenance } from "./types.js";
+export interface VerifyProvenanceOptions {
+    repo: GitRepository;
+    /** The pull request's head branch, which must be a broker integration branch. */
+    branch: string;
+    headSha: string;
+    /** The current tip of the target branch. */
+    baseSha: string;
+    baseBranch: string;
+    branchPrefix?: string;
+    provenanceDirectory?: string;
+}
+export interface ProvenanceVerification {
+    batchId: string;
+    manifestPath: string;
+    manifest: BatchProvenance;
+    /** The commit that introduced the manifest; the integrated work is its parent. */
+    provenanceSha: string;
+    parentSha: string;
+    taskIds: string[];
+}
+/**
+ * Reads verification policy from the configuration as it exists on the base branch. The checked-out
+ * tree belongs to the change being verified, so trusting its configuration would let a pull request
+ * widen the rules it is about to be judged by.
+ */
+export declare function policyFromBase(repo: GitRepository, baseSha: string): Promise<{
+    baseBranch?: string;
+    branchPrefix?: string;
+    provenanceDirectory?: string;
+}>;
+export declare function batchIdFromBranch(branch: string, prefix: string): string;
+/**
+ * Proves that a pull request is an unaltered broker batch: assembled on real base history, carrying
+ * every commit its receipts claim, changing exactly the files those receipts account for, and
+ * validated. Reads nothing but Git, so it works on any forge and before any dependency is installed.
+ */
+export declare function verifyProvenance(options: VerifyProvenanceOptions): Promise<ProvenanceVerification>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAIhE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAC1B,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBvF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYxE;AA8CD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA8GxG"}

package/dist/verify.js

@@ -0,0 +1,177 @@
+import { BrokerError } from "./errors.js";
+import { provenancePath } from "./provenance.js";
+const MAX_BRANCH_UPDATE_MERGES = 50;
+function invalid(message, details) {
+    return new BrokerError("PROVENANCE_INVALID", message, details);
+}
+/**
+ * Reads verification policy from the configuration as it exists on the base branch. The checked-out
+ * tree belongs to the change being verified, so trusting its configuration would let a pull request
+ * widen the rules it is about to be judged by.
+ */
+export async function policyFromBase(repo, baseSha) {
+    const shown = await repo.git(["show", `${baseSha}:.merge-broker/config.json`], repo.root, true);
+    if (shown.exitCode !== 0)
+        return {};
+    try {
+        const config = JSON.parse(shown.stdout);
+        return {
+            ...(typeof config.baseBranch === "string" ? { baseBranch: config.baseBranch } : {}),
+            ...(typeof config.integration?.branchPrefix === "string"
+                ? { branchPrefix: config.integration.branchPrefix }
+                : {}),
+            ...(typeof config.integration?.provenance?.directory === "string"
+                ? { provenanceDirectory: config.integration.provenance.directory }
+                : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function batchIdFromBranch(branch, prefix) {
+    if (!branch.startsWith(prefix) || branch.length === prefix.length) {
+        throw invalid(`Expected a ${prefix}<batch-id> branch, received ${branch}. Work reaches the base branch through the broker, not directly.`, { branch, prefix });
+    }
+    const batchId = branch.slice(prefix.length);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u.test(batchId)) {
+        throw invalid(`Unsafe batch id in branch ${branch}.`, { branch });
+    }
+    return batchId;
+}
+async function isAncestor(repo, ancestor, descendant) {
+    const result = await repo.git(["merge-base", "--is-ancestor", ancestor, descendant], repo.root, true);
+    return result.exitCode === 0;
+}
+/**
+ * Finds the commit that introduced the manifest, stepping over the merges GitHub creates when a
+ * protected base requires branches to be up to date. Such a merge is accepted only when its merged
+ * side is already contained in the base and it changed nothing the base did not: anything else is a
+ * commit somebody pushed onto the branch after the broker assembled it.
+ */
+async function findProvenanceCommit(repo, headSha, baseSha) {
+    let current = headSha;
+    for (let depth = 0; depth < MAX_BRANCH_UPDATE_MERGES; depth += 1) {
+        const listed = await repo.git(["rev-list", "--parents", "-n", "1", current]);
+        const parents = listed.stdout.trim().split(/\s+/u).slice(1);
+        if (parents.length < 2)
+            return current;
+        if (parents.length > 2)
+            throw invalid(`Octopus merge ${current} is not a recognised branch update.`);
+        const [firstParent, secondParent] = parents;
+        if (!(await isAncestor(repo, secondParent, baseSha))) {
+            throw invalid(`Merge ${current} brings in ${secondParent}, which is not part of ${baseSha}. Only base-branch updates may be added to an integration branch.`);
+        }
+        const conflictEdits = (await repo.git(["diff", "--name-only", firstParent, current])).stdout
+            .split("\n")
+            .filter(Boolean);
+        const baseChanges = new Set((await repo.git(["diff", "--name-only", `${firstParent}...${secondParent}`])).stdout
+            .split("\n")
+            .filter(Boolean));
+        const unexplained = conflictEdits.filter((file) => !baseChanges.has(file));
+        if (unexplained.length > 0) {
+            throw invalid(`Branch update ${current} changed files the base branch did not: ${unexplained.join(", ")}.`, {
+                files: unexplained,
+            });
+        }
+        current = firstParent;
+    }
+    throw invalid("Integration branch has too many merge commits to verify.");
+}
+/**
+ * Proves that a pull request is an unaltered broker batch: assembled on real base history, carrying
+ * every commit its receipts claim, changing exactly the files those receipts account for, and
+ * validated. Reads nothing but Git, so it works on any forge and before any dependency is installed.
+ */
+export async function verifyProvenance(options) {
+    const { repo, branch, headSha, baseSha, baseBranch, branchPrefix = "merge-broker/", provenanceDirectory = ".merge-broker/attestations", } = options;
+    const batchId = batchIdFromBranch(branch, branchPrefix);
+    const manifestPath = provenancePath(provenanceDirectory, batchId);
+    const shown = await repo.git(["show", `${headSha}:${manifestPath}`], repo.root, true);
+    if (shown.exitCode !== 0) {
+        throw invalid(`Integration branch ${branch} does not contain ${manifestPath}.`, { manifestPath });
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(shown.stdout);
+    }
+    catch (error) {
+        throw invalid(`${manifestPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (manifest.version !== 1 || manifest.generator !== "agent-merge-broker") {
+        throw invalid(`Unsupported provenance manifest in ${manifestPath}.`);
+    }
+    if (manifest.batchId !== batchId) {
+        throw invalid(`Manifest batch ${manifest.batchId} does not match branch ${batchId}.`);
+    }
+    if (manifest.baseBranch !== baseBranch) {
+        throw invalid(`Batch targets ${manifest.baseBranch}, not ${baseBranch}.`);
+    }
+    // The batch must sit on real base history, but not necessarily on its current tip. Requiring
+    // equality would deadlock every batch: the base advances between integration and this check, and
+    // no amount of re-running makes a recorded base match a moving target.
+    if (manifest.baseSha !== baseSha && !(await isAncestor(repo, manifest.baseSha, baseSha))) {
+        throw invalid(`Batch was assembled on ${manifest.baseSha}, which is not an ancestor of ${baseBranch} at ${baseSha}. Re-integrate the batch.`);
+    }
+    const provenanceSha = await findProvenanceCommit(repo, headSha, baseSha);
+    const parentSha = (await repo.git(["rev-parse", `${provenanceSha}^`])).stdout.trim();
+    if (manifest.integratedHeadSha !== parentSha) {
+        throw invalid("The manifest is not the final provenance-only commit on this branch.", {
+            recorded: manifest.integratedHeadSha,
+            actual: parentSha,
+        });
+    }
+    const changedByManifest = (await repo.git(["diff-tree", "--no-commit-id", "--name-only", "-r", provenanceSha])).stdout
+        .split("\n")
+        .filter(Boolean);
+    if (changedByManifest.length !== 1 || changedByManifest[0] !== manifestPath) {
+        throw invalid("The final broker commit must change only its provenance manifest.", {
+            changed: changedByManifest,
+        });
+    }
+    if (!(await isAncestor(repo, manifest.baseSha, parentSha))) {
+        throw invalid("Integrated head does not descend from the recorded base.");
+    }
+    if (!Array.isArray(manifest.tasks) || manifest.tasks.length === 0) {
+        throw invalid("Manifest contains no tasks.");
+    }
+    const taskIds = manifest.tasks.map((task) => task.id);
+    if (JSON.stringify(taskIds) !== JSON.stringify(manifest.taskIds)) {
+        throw invalid("Manifest taskIds do not match its task records.");
+    }
+    // Compared against the base the manifest records, not the current tip: a later unrelated commit on
+    // the base branch would otherwise look like an unaccounted change.
+    const claimedPaths = [...new Set(manifest.tasks.flatMap((task) => task.actualPaths ?? []))].sort();
+    const integratedPaths = [
+        ...new Set((await repo.git(["diff", "--name-only", `${manifest.baseSha}..${parentSha}`])).stdout
+            .split("\n")
+            .filter(Boolean)),
+    ].sort();
+    if (JSON.stringify(claimedPaths) !== JSON.stringify(integratedPaths)) {
+        throw invalid("Manifest paths do not match the integrated diff.", {
+            claimed: claimedPaths,
+            integrated: integratedPaths,
+        });
+    }
+    // Squashing rewrites the batch into one commit and drops the cherry-pick trail, so submitted
+    // commits are only traceable when history was preserved. Manifests written before this field
+    // existed always preserved it.
+    if ((manifest.history ?? "preserve") === "preserve") {
+        const history = (await repo.git(["log", "--format=%B", `${manifest.baseSha}..${parentSha}`])).stdout;
+        for (const task of manifest.tasks) {
+            if (!Array.isArray(task.commits) || task.commits.length === 0) {
+                throw invalid(`Task ${task.id} records no submitted commits.`);
+            }
+            for (const commit of task.commits) {
+                if (!history.includes(`cherry picked from commit ${commit}`)) {
+                    throw invalid(`Integrated history is missing submitted commit ${commit} from task ${task.id}.`);
+                }
+            }
+        }
+    }
+    if (!Array.isArray(manifest.validations) || manifest.validations.some((item) => item.exitCode !== 0)) {
+        throw invalid("Manifest records a failed validation.");
+    }
+    return { batchId, manifestPath, manifest, provenanceSha, parentSha, taskIds };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,144 @@
+# Architecture
+
+## Product boundary
+
+Agent Merge Broker sits between code-producing workers and the repository's protected integration workflow. Workers own implementation and focused commits. The broker owns ordering, batching, validation, and publication. GitHub or another forge remains the review, policy, and deployment boundary.
+
+The core depends on Git rather than a particular agent SDK. CLI JSON output and the exported Node API are the initial adapter surfaces.
+
+## Invariants
+
+1. A worker submits immutable commit IDs, never an uncommitted filesystem snapshot.
+2. Broker operations never merge into or rewrite the configured base branch.
+3. Integration happens in a dedicated disposable worktree based on a resolved base SHA.
+4. The retained branch is created only after every configured validator succeeds.
+5. A task is `merged` only after reconciliation or an explicit operator completion.
+6. State changes are atomic and serialized across linked Git worktrees.
+7. The lease token itself is never persisted; only its SHA-256 digest is stored.
+
+## Portable and runtime state
+
+Portable repository policy is committed under `.merge-broker/`.
+
+Runtime state is stored at:
+
+```text
+$(git rev-parse --git-common-dir)/merge-broker/
+├── state.json
+├── audit.jsonl
+├── receipts/<task-id>.json
+├── batches/<batch-id>.json
+├── state.lock/
+├── integration.lock/
+├── archive/
+└── worktrees/<batch-id>/
+```
+
+JSON state writes use a temporary sibling followed by an atomic rename. Lock acquisition uses atomic directory creation. Short state mutations and long integration transactions use separate locks so status reads and heartbeats do not need to hold the integration lock.
+
+## Retention
+
+Active state is a working set, not a historical record. Because `state.json` is rewritten in full on every transaction, an unbounded history makes every heartbeat progressively more expensive. `prune` moves completed tasks and batches into `archive/`, and the audit stream rotates into the same directory once the active file grows large. Archived material is never deleted.
+
+Two records are deliberately not prunable. A completed task that a retained task still declares as a dependency stays, because `dependencyReady` cannot distinguish a pruned dependency from one that has never merged and would block the dependent forever. A batch stays while any of its tasks does, so a retained task never points at a batch that no longer exists.
+
+Audit reads are tolerant by design: they scan a bounded tail and skip records that fail to parse. A crash between writing and flushing leaves a truncated line, which is exactly the moment the audit trail matters most.
+
+## Lock recovery
+
+A lock owner records its process ID, hostname, and creation time. A holder on this machine whose process is gone is provably abandoned and is reclaimed after a short grace period. A holder on another machine cannot be probed — the state directory is shared, process IDs are not — so it waits out the full stale window rather than risking two integrations at once. `unlock` exposes that same decision to an operator, and `--force` is the deliberate override for a holder that cannot be proven dead.
+
+## Task lifecycle
+
+```text
+registered → claimed → submitted → integrating → batched → published → merged
+                 ↑          ↑ │          │                     │
+                 │          │ │          │                     │ pull request closed
+                 │          └─┼──────────┴─────────────────────┘ or batch-mate failed
+                 └──── retry ←┴─ failed
+```
+
+- `registered`: metadata exists but no active worker lease is required.
+- `claimed`: an agent holds an expiring lease.
+- `submitted`: immutable commits and their actual changed paths were recorded.
+- `integrating`: selected by the process holding the integration lock.
+- `batched`: validation passed and a local integration branch exists.
+- `published`: the remote branch or PR was created.
+- `merged`: the result reached the base workflow and dependencies may proceed.
+
+Cancellation is allowed only before batching. After correction, `task submit` can replace the receipt or `task retry` can requeue the existing receipt.
+
+A failed attempt is attributed as narrowly as the evidence allows. A cherry-pick conflict or a focused validation failure is attributable to one task: that task moves to `failed` with error evidence and its batch-mates return to `submitted`, so an unrelated agent's work is not held hostage. An authoritative validation failure indicts the entire batch and moves every selected task to `failed`, which prevents a polling broker from repeating the same broken batch.
+
+A published batch whose pull request is closed without merging becomes `closed` rather than remaining `published`. Its tasks return to `submitted`, because a closed pull request means the work was rejected, not completed. `integration.maxAttempts` bounds how many times a task may be re-queued automatically before it is left `failed` for a human.
+
+## Scheduling
+
+Submitted tasks are sorted by:
+
+1. descending priority;
+2. ascending submission time;
+3. lexical task ID.
+
+The scheduler walks this list repeatedly so a parent selected in the current batch can unblock a child on the next pass. It rejects or defers candidates that exceed batch limits, conflict on an actual file, share a configured serialized resource, or depend on work that is neither in the batch nor `merged`.
+
+This is a deterministic weighted greedy independent-set heuristic. Finding an optimal maximum non-conflicting set is not a project guarantee.
+
+Expected path globs coordinate editing leases. Actual paths are derived from Git commits and drive integration batching. Expected scopes are conservative because two arbitrary glob languages cannot always be proven disjoint cheaply.
+
+## Transaction
+
+For a selected batch the broker:
+
+1. Resolves the configured integration `baseRef` to a specific SHA while retaining `baseBranch` as the forge target.
+2. Marks selected tasks `integrating` under the state lock.
+3. Adds a detached Git worktree at that SHA.
+4. Cherry-picks each receipt commit with `-x` in dependency order.
+5. Runs applicable focused validators after each task, in a fixed non-login shell.
+6. Runs all authoritative validators over the complete batch.
+7. Optionally squashes the batch while preserving task IDs in the message.
+8. Optionally commits a provenance manifest whose parent is the integrated task head.
+9. Creates a uniquely named local branch at the resulting head.
+10. Removes the disposable worktree.
+11. Optionally pushes the branch and opens one GitHub PR.
+
+A failed cherry-pick is aborted. No retained branch is created after a validation failure. Configurable failed-worktree retention exists for diagnosis, but defaults off because worktrees can contain build products and secrets.
+
+## Publication and reconciliation
+
+Publication supports three modes:
+
+- `none`: retain a local branch only.
+- `branch`: push one branch.
+- `pull-request`: push and invoke `gh pr create`.
+
+When provenance is enabled, the final generated commit records the base SHA,
+integrated parent, task receipts, paths, and completed broker validators. A
+remote workflow can validate this structure before dependency installation and
+then either trust broker-authoritative validation or run the single
+authoritative suite itself.
+
+PR reconciliation queries GitHub for merged state. Branch reconciliation fetches the configured base and checks that the batch head is an ancestor. Squash and rebase workflows may require the explicit `batch complete` escape hatch because the local batch head can disappear from final ancestry.
+
+## Remote verification
+
+`verify-provenance` is the read-only inverse of integration: given a branch, its head, and the base,
+it re-derives what the broker must have done and rejects anything else. It uses only Git, so it runs
+on any forge, in any language ecosystem, before dependencies are installed — which is what makes it
+cheap enough to require on every pull request.
+
+It is deliberately tolerant of one thing: the merges a forge creates when a protected base requires
+branches to be up to date. Such a merge is accepted only when its merged side is already contained
+in the base and it changed nothing the base did not; the manifest commit is then located behind it.
+Every other commit added to an integration branch fails verification.
+
+Squashed batches cannot be traced commit by commit, because squashing discards the cherry-pick
+trail. The manifest records which mode produced it so a verifier knows which guarantees apply.
+
+## Failure isolation
+
+The first failing cherry-pick identifies a commit and task. Focused validation identifies a task-scoped failure. An authoritative failure identifies the complete batch but may represent an interaction between otherwise valid tasks. Version 0.1 deliberately stops and marks the bounded batch failed rather than automatically guessing a resolution. Operators can requeue the unchanged receipt explicitly. Automatic delta debugging can be layered on without weakening the transaction invariant.
+
+## Future adapters
+
+Adapters should translate their native task system into the protocol rather than receive Git administration privileges. Natural additions are MCP, GitHub Actions, Codex, Claude Code, and generic webhook adapters. The core state machine must remain usable without them.

package/docs/PROTOCOL.md

@@ -0,0 +1,127 @@
+# Worker and adapter protocol
+
+## Contract
+
+A worker needs only five capabilities:
+
+1. Claim an ID and expected path scope.
+2. Maintain an expiring lease while editing.
+3. Create one or more focused Git commits.
+4. Submit those commit IDs with the lease token.
+5. Stop performing Git administration after submission.
+
+All CLI commands support `--json`. Successful commands write one JSON value to stdout and exit zero. Errors write a stable code, message, and optional details to stderr and exit nonzero.
+
+## Claim
+
+```bash
+merge-broker --json task claim TASK-123 \
+  --holder adapter/session-456 \
+  --agent codex \
+  --base main \
+  --path 'src/billing/**' \
+  --depends-on TASK-100 \
+  --priority 20
+```
+
+The response contains a one-time `token`. Adapters should hold it in process memory or an appropriate secret store. The persisted state contains only a digest.
+
+## Heartbeat
+
+Heartbeat before the lease expiry shown in the claim response:
+
+```bash
+MERGE_BROKER_TOKEN=... merge-broker --json task heartbeat TASK-123
+```
+
+An expired lease can be claimed by another worker. A former holder must not continue editing after losing the lease.
+
+## Extend scope
+
+When a discovered dependency expands the task, extend the active lease with
+the same token before editing the additional path:
+
+```bash
+MERGE_BROKER_TOKEN=... merge-broker --json task extend TASK-123 \
+  --path 'src/shared/contract.ts'
+```
+
+The broker rechecks active and serialized-resource conflicts before accepting
+the larger scope.
+
+## Submit
+
+```bash
+MERGE_BROKER_TOKEN=... merge-broker --json task submit TASK-123 \
+  --commit a1b2c3d \
+  --commit d4e5f6a
+```
+
+Commit order is significant. The broker resolves every revision to a full immutable commit ID and computes actual paths from Git rather than trusting the caller.
+
+The receipt written under Git's common directory conforms to [`../schemas/receipt.schema.json`](../schemas/receipt.schema.json). It contains no lease credential.
+
+## Published batch provenance
+
+With `integration.provenance.enabled`, the broker's final integration commit
+adds one JSON manifest under the configured repository-relative directory. Its
+parent is the assembled task head. The record binds the branch to its base,
+task IDs, submitted commits, changed paths, dependencies, and any broker-side
+validators. It conforms to
+[`../schemas/provenance.schema.json`](../schemas/provenance.schema.json).
+
+Remote policy should verify the branch prefix, manifest path, batch ID, base
+SHA, final-commit parent, and one-file provenance commit before spending time
+on dependency installation or authoritative CI.
+
+## Path semantics
+
+Paths are repository-relative and use forward slashes. Globs use picomatch semantics. Prefer the smallest scope that covers expected work:
+
+```text
+src/billing/**
+test/billing/**
+prisma/schema.prisma
+```
+
+Avoid `**/*` unless the task genuinely owns the repository. A committed file outside the expected scope is rejected by default.
+
+## Dependencies
+
+Dependencies refer to broker task IDs. With `requireDependencies` enabled, every referenced task must exist before submission. A dependency is schedulable when it is selected earlier in the same batch or has reached `merged` status.
+
+Repository adapters should distinguish `baseRef`, the Git revision used to build transactions, from `baseBranch`, the forge target. For repositories with a passive local checkout, use `baseRef: "origin/main"` and `baseBranch: "main"`.
+
+Published or prepared work is not treated as merged. This prevents a child from being integrated against a base that does not contain its parent.
+
+## Stable error categories
+
+Adapters should primarily branch on these codes:
+
+- `LEASE_CONFLICT`, `LEASE_EXPIRED`, `LEASE_TOKEN`
+- `UNEXPECTED_PATHS`
+- `INVALID_TASK`, `UNKNOWN_TASK`, `UNKNOWN_DEPENDENCY`
+- `UNKNOWN_COMMIT`, `DUPLICATE_COMMIT`, `EMPTY_COMMIT`, `MERGE_COMMIT`
+- `CHERRY_PICK_CONFLICT`
+- `VALIDATION_FAILED`
+- `EMPTY_BATCH`
+- `LOCK_TIMEOUT`, `LOCK_HELD`
+- `PUBLISH_DISABLED`, `PUBLISH_FAILED`, `AUTO_MERGE_FAILED`
+- `PROVENANCE_INVALID`
+- `HOOKS_PATH_CONFLICT`
+
+Additional codes may be introduced. Adapters must display unknown errors rather than treating them as success.
+
+## Programmatic use
+
+The package exports `MergeBroker`, repository/configuration types, state types, and error classes:
+
+```ts
+import { MergeBroker } from "agent-merge-broker";
+
+const broker = await MergeBroker.open("/path/to/worktree");
+const plan = await broker.plan();
+const result = await broker.integrate({ dryRun: true });
+```
+
+Programmatic callers share the same filesystem locks and state machine as CLI callers.

package/docs/RELEASING.md

@@ -0,0 +1,23 @@
+# Releasing
+
+The package name `agent-merge-broker` was unclaimed on npm when the project was initialized. Registry availability is not reserved until the first publication.
+
+## First release setup
+
+1. Create the public GitHub repository and update package metadata if its owner differs from `WeSpitfire`.
+2. Confirm the package name and ownership with `npm view agent-merge-broker`.
+3. Configure npm trusted publishing for the GitHub repository and the `release.yml` workflow, or add an appropriately scoped `NPM_TOKEN` and adjust the workflow.
+4. Protect `main` and require the CI workflow.
+5. Add a private vulnerability-reporting contact to `docs/SECURITY.md`.
+
+## Release procedure
+
+1. Update `CHANGELOG.md` and remove the `Unreleased` marker for the target version.
+2. Update `package.json` with `npm version <major|minor|patch> --no-git-tag-version`.
+3. Run `npm run verify` and `npm pack --dry-run`.
+4. Commit the release metadata and merge it through the normal protected workflow.
+5. Create a GitHub release tagged `v<version>`.
+
+Publishing the GitHub release invokes the release workflow, repeats verification, checks that the tag equals the package version, and publishes with npm provenance.
+
+Do not reuse or move a published version tag. If a release is incorrect, deprecate it and publish a corrected patch version.