agent-merge-broker 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 PowerHouse Exteriors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,352 @@
+# Agent Merge Broker
+
+**Four agents just finished at the same time. Who merges first?**
+
+Agent Merge Broker answers that so your agents never have to. Workers commit their work and stop. The broker decides what can safely go together, cherry-picks it into a disposable worktree, runs your test suite against the combination, and lands one validated branch or pull request.
+
+No agent pushes. No agent rebases. No agent quietly clobbers another agent's `package-lock.json`.
+
+## The problem
+
+Put four coding agents on one repository and the bottleneck stops being code. It becomes Git.
+
+Two agents edit the same file and find out at merge time. A third rebases onto a branch that moved twenty minutes ago. Everyone regenerates the lockfile. CI runs four times to test four things that were never once tested *together*. And the pull request that has been sitting there since lunch is now so far behind `main` that nothing can merge it at all.
+
+The work is parallel. Integration is not. Every worker doing its own integration turns a coordination problem into a coordination disaster.
+
+## Try it in one minute
+
+```bash
+git clone https://github.com/WeSpitfire/agent-merge-broker
+cd agent-merge-broker && npm install && npm run build && npm run example
+```
+
+Two workers race on a throwaway repository, a third gets turned away for claiming ground someone else already leased, and four commits land as one validated branch. No forge, no network, no credentials.
+
+It is also this project's acceptance test in CI — so if the demo ever stops telling the truth, the build goes red.
+
+## How it works
+
+One integration authority; implementation stays distributed:
+
+- Expiring, cross-worktree leases prevent predictable collisions before editing.
+- Commit receipts separate implementation from integration authority.
+- A deterministic conflict/dependency scheduler forms bounded batches.
+- Every batch is tested through real cherry-picks in a disposable worktree.
+- Focused checks run after each task and authoritative checks run over the batch.
+- Successful work becomes one local branch, remote branch, or GitHub pull request.
+- Published branches can carry a committed provenance manifest for fast remote policy checks.
+- Tasks are dependency-complete only after their batch is actually merged.
+- An append-only audit stream records lifecycle decisions and validation results.
+
+It is deliberately **not** an agent framework and **not** a replacement for protected branches. Codex, Claude, Cursor, custom agents, CI jobs, and humans all speak the same small commit-receipt protocol, and your forge keeps the final say on what merges.
+
+## Status
+
+`0.3.0` is the first public release. It contains the local broker core, the GitHub CLI publishing adapter with auto-merge, and the remote provenance verifier.
+
+The on-disk state, receipt, and provenance formats are versioned, but compatibility is not guaranteed until `1.0.0`. Expect format migrations before then.
+
+## Requirements
+
+- Node.js 20.12 or newer
+- Git 2.31 or newer with worktree support
+- GitHub CLI only when `publish.mode` is `pull-request`
+
+Linux and macOS are the supported platforms and are covered by CI. Windows runs as an informational
+CI job: shell selection and command quoting differ there and are not yet supported.
+
+## Install
+
+Install it as a development tool:
+
+```bash
+npm install --save-dev agent-merge-broker
+npx merge-broker init --base main --base-ref origin/main
+```
+
+To work on the broker itself, clone this repository and link the CLI:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+`init` writes two portable files into the application:
+
+- `.merge-broker/config.json` — repository policy and commands
+- `.merge-broker/agent-instructions.md` — a reusable worker contract
+
+Runtime state, receipt records, manifests, locks, and integration worktrees live under Git's common directory. Every linked worktree therefore sees the same broker state, while runtime artifacts do not pollute commits.
+
+## Quick start
+
+Initialize an existing Git repository and edit its generated configuration:
+
+```bash
+merge-broker init --base main --base-ref origin/main --remote origin
+merge-broker doctor
+```
+
+An orchestrator or worker claims a narrowly scoped task:
+
+```bash
+merge-broker task claim CRM-142 \
+  --holder codex/customer-page \
+  --path 'src/customers/**' \
+  --path 'test/customers/**'
+```
+
+The broker keeps the lease token beside its own state, readable only by the user who claimed the
+task, so nothing in the worker has to carry a credential:
+
+```bash
+merge-broker task heartbeat CRM-142
+```
+
+Pass `--token`, `--token-file`, or `MERGE_BROKER_TOKEN` when the worker runs somewhere else, or
+claim with `--no-store-token` to handle custody yourself.
+
+The worker commits its change and submits a receipt. It does not merge or push:
+
+```bash
+git commit -m 'Add customer search filters'
+merge-broker task submit CRM-142 --since-base
+```
+
+`--since-base` submits the linear commits made after the base the broker handed out, skipping any
+whose change is already upstream. Pass explicit `--commit` revisions instead when a worker wants to
+hand over only part of its branch.
+
+The integration owner can inspect and verify the next batch before retaining anything:
+
+```bash
+merge-broker plan
+merge-broker integrate --dry-run
+merge-broker integrate
+```
+
+With publishing enabled in the configuration:
+
+```bash
+merge-broker integrate --publish
+merge-broker batch sync <batch-id>
+```
+
+`batch sync` checks the GitHub PR when available. For branch-only publication it fetches the configured base and verifies ancestry. `batch complete` exists as an explicit manual escape hatch for squash/rebase workflows that cannot be reconciled automatically.
+
+## See it work
+
+```bash
+npm run build
+sh examples/two-agents/run.sh
+```
+
+[`examples/two-agents`](examples/two-agents/) builds a throwaway repository, runs two workers in
+parallel worktrees, refuses a third worker that tries to claim an area already leased, and assembles
+four commits into one validated branch. No forge, no network, no credentials.
+
+## Enforcing the broker
+
+Nothing above prevents a worker from pushing its own branch and opening a pull request. Two optional
+guards close that gap.
+
+A local guard refuses direct pushes of implementation branches:
+
+```bash
+merge-broker install-hooks
+```
+
+This sets `core.hooksPath`, so it refuses to run when the repository already has hooks that would
+stop working, and `--uninstall` puts everything back. `MERGE_BROKER_ALLOW_DIRECT_PUSH=1` is the
+deliberate emergency bypass.
+
+A remote gate proves a pull request really is an unaltered broker batch. It reads only Git, so it
+can run before any dependency is installed and reject bypassed work for almost nothing:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    ref: ${{ github.event.pull_request.head.sha }}
+    fetch-depth: 0
+- uses: WeSpitfire/agent-merge-broker/verify@v1
+```
+
+The check confirms that the branch is a broker integration branch, that its manifest was assembled
+on real base history, that the final commit changes nothing but that manifest, that the integrated
+diff matches exactly the paths the receipts account for, that every submitted commit is present, and
+that all recorded validations passed. It accepts the "update branch" merges a protected base
+produces, and rejects a merge that brings in anything the base does not already contain.
+
+Verification policy is read from the configuration committed on the *base* branch, never from the
+change under review.
+
+## Automatic merging
+
+With `publish.mode` set to `pull-request` and `publish.autoMerge` enabled, the broker enables GitHub auto-merge on each published batch. GitHub lands the pull request once required status checks pass and updates the branch when the base branch requires it. The broker never pushes to the base branch itself, so branch protection remains the authority on what may merge.
+
+Two configuration combinations cannot work and are rejected at load time rather than stalling silently:
+
+- `autoMerge` with `draft`, because GitHub refuses to merge a draft pull request
+- `autoMerge` with `publish.mode` set to `branch`, because there is no pull request to merge
+
+Auto-merge requires the setting to be enabled on the GitHub repository. Configurations written before this feature existed default to `autoMerge: false`, so upgrading never starts landing work on its own.
+
+Running `merge-broker serve --publish` closes the loop: each cycle reconciles published batches, integrates the next batch, and publishes it for auto-merge.
+
+## Failure recovery
+
+Integration failures are attributed as narrowly as the evidence allows:
+
+- A cherry-pick conflict or focused validation failure fails only the responsible task. Its batch-mates return to the queue and are re-planned, so one bad commit cannot stall unrelated agents.
+- An authoritative validation failure indicts the whole batch, because no single task can be blamed. Those tasks stay `failed` until `task retry`.
+- A pull request closed without merging moves the batch to `closed` and returns its tasks to the queue. Leaving such a batch `published` strands the work and reads like success.
+
+`integration.maxAttempts` bounds automatic re-queueing so a task that never integrates eventually stops consuming CI capacity and waits for a human. `task retry` resets that budget.
+
+A process that dies mid-integration leaves its lock behind. A holder on this machine is reclaimed automatically once its process is gone, but a holder on another machine cannot be probed at all and would otherwise block integration for the full stale window. `merge-broker unlock` reports lock state and releases a lock whose owner is provably gone; `--force` overrides that check and should follow confirming that no integration is running.
+
+## Housekeeping
+
+`state.json` is rewritten in full on every transaction, including heartbeats, so completed work should not accumulate in it forever:
+
+```bash
+merge-broker prune --older-than 30 --dry-run
+merge-broker prune --older-than 30
+```
+
+Retired tasks and batches move to `<state>/archive/`, and the audit stream rotates into the same place once the active file grows large. Nothing is deleted. A completed task is kept in active state for as long as any retained task still declares it as a dependency, because the scheduler cannot distinguish a pruned dependency from one that has never merged.
+
+## Configuration
+
+The generated `.merge-broker/config.json` is intentionally explicit and reviewable. `baseBranch` is the forge/PR target, while `baseRef` is the Git revision used to construct a batch; repositories that keep a passive local `main` should use `origin/main`:
+
+```json
+{
+  "version": 1,
+  "baseBranch": "main",
+  "baseRef": "origin/main",
+  "remote": "origin",
+  "stateDirectory": "merge-broker",
+  "leases": {
+    "ttlSeconds": 1800,
+    "lockTimeoutSeconds": 15,
+    "serializedPatterns": ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"]
+  },
+  "policies": {
+    "unexpectedPaths": "error",
+    "requireCleanWorktree": false,
+    "requireDependencies": true
+  },
+  "scheduling": {
+    "maxTasks": 6,
+    "maxCommits": 12,
+    "maxWaitSeconds": 600,
+    "allowPathOverlap": false
+  },
+  "integration": {
+    "branchPrefix": "merge-broker/",
+    "history": "preserve",
+    "keepFailedWorktrees": false,
+    "refreshBase": true,
+    "maxAttempts": 3,
+    "provenance": {
+      "enabled": true,
+      "directory": ".merge-broker/attestations"
+    }
+  },
+  "validation": {
+    "shell": "/bin/sh",
+    "focused": [
+      {
+        "name": "related tests",
+        "paths": ["src/**", "test/**"],
+        "command": "npm test -- {files}",
+        "timeoutSeconds": 900
+      }
+    ],
+    "authoritative": [
+      { "name": "test", "command": "npm test", "timeoutSeconds": 1800 },
+      { "name": "build", "command": "npm run build", "timeoutSeconds": 1800 }
+    ]
+  },
+  "publish": {
+    "mode": "pull-request",
+    "draft": false,
+    "autoMerge": true,
+    "mergeMethod": "squash",
+    "labels": ["integration-batch"],
+    "titleTemplate": "Integration batch {batchId}"
+  }
+}
+```
+
+Validator commands run inside the isolated integration worktree, under `/bin/sh` unless
+`validation.shell` names another interpreter. The shell is deliberately fixed and is never a login
+shell: an integration decision must not depend on whose machine assembled the batch. The environment
+is inherited from the process that invoked the broker, minus `MERGE_BROKER_TOKEN`, so PATH and
+toolchain managers work while worker credentials stay out of repository-defined commands.
+
+Validators receive these environment variables:
+
+- `MERGE_BROKER_TASK_ID`
+- `MERGE_BROKER_FILES`, newline-separated
+- `MERGE_BROKER_BASE_SHA`
+- `MERGE_BROKER_HEAD_SHA`
+- `MERGE_BROKER_BATCH_ID`
+
+Commands may also use the shell-safe placeholders `{taskId}` and `{files}`. Validator output retained in state is capped to prevent unbounded growth.
+
+The JSON schemas in [`schemas/`](schemas/) can be used by editors, adapters, and independent receipt producers.
+
+### One authoritative CI pass
+
+Repositories that make GitHub the authoritative validator can leave broker
+authoritative validators empty, keep provenance enabled, and reject any PR
+without a valid broker manifest before installing dependencies. The full lint,
+type, test, and build suite then runs exactly once on the assembled broker PR.
+Task worktrees retain only fast changed-scope feedback, while deployment builds
+the already-checked revision without repeating the whole suite.
+
+## Command surface
+
+```text
+merge-broker init
+merge-broker doctor
+merge-broker install-hooks [--force] [--uninstall]
+merge-broker verify-provenance --branch <ref> --head <sha> --base <sha>
+merge-broker task register|claim|extend|heartbeat|submit|retry|release|cancel|show
+merge-broker status
+merge-broker plan
+merge-broker integrate [--dry-run] [--publish]
+merge-broker batch list|show|publish|sync|complete
+merge-broker audit
+merge-broker metrics
+merge-broker events
+merge-broker prune [--older-than <days>] [--dry-run]
+merge-broker unlock [state|integration] [--force]
+merge-broker serve [--publish] [--eager]
+```
+
+Every command accepts `--json` for adapters and `-C <directory>` for explicit repository discovery. Lease-aware commands also accept `MERGE_BROKER_TOKEN`.
+
+## Guarantees and limits
+
+Path overlap is a conservative coordination signal, not proof of semantic compatibility. Non-overlapping tasks can still break contracts. For this reason, the disposable worktree and authoritative validation—not the scheduler—are the final integration decision.
+
+The scheduler uses a deterministic weighted greedy heuristic. It does not claim to solve the NP-hard maximum independent set problem optimally. Batches are deliberately capped because very large batches reduce CI traffic but increase failure blast radius.
+
+Configuration is trusted repository code: validator commands can execute arbitrary shell commands. Review configuration changes with the same care as CI workflows. See [`docs/SECURITY.md`](docs/SECURITY.md).
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — invariants, state model, scheduling, and transactions
+- [`docs/PROTOCOL.md`](docs/PROTOCOL.md) — lifecycle and adapter contract
+- [`docs/SECURITY.md`](docs/SECURITY.md) — trust boundaries and hardening
+- [`docs/RELEASING.md`](docs/RELEASING.md) — registry and release procedure
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — development and pull requests
+
+## License
+
+Apache License 2.0. See [`LICENSE`](LICENSE).

package/dist/broker.d.ts

@@ -0,0 +1,110 @@
+import { GitRepository } from "./git.js";
+import { StateStore, type LockStatus } from "./store.js";
+import { type HookInstallation } from "./hooks.js";
+import type { BatchRecord, BrokerConfig, BrokerState, IntegrationOptions, IntegrationResult, PruneOptions, PruneResult, SchedulePlan, TaskRecord } from "./types.js";
+export interface RegisterTaskInput {
+    id: string;
+    title?: string;
+    agent?: string;
+    base?: string;
+    expectedPaths?: string[];
+    dependsOn?: string[];
+    priority?: number;
+    worktree?: string;
+}
+export interface ClaimTaskInput extends RegisterTaskInput {
+    holder: string;
+    /** Set false to keep the token out of broker state entirely and handle custody elsewhere. */
+    storeToken?: boolean;
+    /** Write the token here instead of the default location inside the broker state directory. */
+    tokenFile?: string;
+}
+export declare class MergeBroker {
+    readonly repo: GitRepository;
+    readonly config: BrokerConfig;
+    readonly store: StateStore;
+    private constructor();
+    static open(cwd?: string): Promise<MergeBroker>;
+    static initialize(cwd?: string, options?: {
+        baseBranch?: string;
+        baseRef?: string;
+        remote?: string;
+        force?: boolean;
+    }): Promise<{
+        repoRoot: string;
+        configPath: string;
+        created: boolean;
+    }>;
+    registerTask(input: RegisterTaskInput): Promise<TaskRecord>;
+    claimTask(input: ClaimTaskInput): Promise<{
+        task: TaskRecord;
+        token: string;
+        tokenPath?: string;
+    }>;
+    heartbeat(taskId: string, token: string): Promise<TaskRecord>;
+    extendTask(taskId: string, expectedPaths: string[], token: string): Promise<TaskRecord>;
+    releaseTask(taskId: string, token?: string, options?: {
+        force?: boolean;
+    }): Promise<TaskRecord>;
+    cancelTask(taskId: string, token?: string, options?: {
+        force?: boolean;
+    }): Promise<TaskRecord>;
+    retryTask(taskId: string, token?: string): Promise<TaskRecord>;
+    submitTask(taskId: string, commits: string[], token: string, options?: {
+        sinceBase?: boolean;
+    }): Promise<{
+        task: TaskRecord;
+        receiptPath: string;
+    }>;
+    state(): Promise<BrokerState>;
+    task(taskId: string): Promise<TaskRecord>;
+    plan(options?: {
+        taskIds?: string[];
+        maxTasks?: number;
+    }): Promise<SchedulePlan>;
+    integrate(options?: IntegrationOptions): Promise<IntegrationResult>;
+    publishBatch(id: string): Promise<BatchRecord>;
+    syncBatch(id: string): Promise<BatchRecord>;
+    syncPublishedBatches(): Promise<{
+        synced: BatchRecord[];
+        closed: BatchRecord[];
+        unchanged: BatchRecord[];
+        errors: Array<{
+            batchId: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * Records that a published batch will never merge and returns its tasks to the queue, so the work
+     * is re-planned against a fresh base instead of being silently lost.
+     */
+    closeBatch(id: string, reason: string): Promise<BatchRecord>;
+    markBatchMerged(id: string, mergedAt?: string, mergeCommitSha?: string): Promise<BatchRecord>;
+    auditWorktrees(): Promise<{
+        worktrees: Array<{
+            path: string;
+            branch?: string;
+            registeredTaskIds: string[];
+            clean: boolean;
+        }>;
+        staleLeases: string[];
+        unregisteredWorktrees: string[];
+    }>;
+    /**
+     * Retires completed records so `state.json` stops growing without bound. The file is rewritten in
+     * full on every transaction, including heartbeats, so an unbounded history makes routine
+     * operations progressively slower.
+     */
+    prune(options?: PruneOptions): Promise<PruneResult>;
+    installHooks(options?: {
+        force?: boolean;
+        uninstall?: boolean;
+    }): Promise<HookInstallation>;
+    inspectLocks(): Promise<LockStatus[]>;
+    releaseLock(name: string, options?: {
+        force?: boolean;
+    }): Promise<LockStatus>;
+    metrics(): Promise<Record<string, unknown>>;
+    doctor(): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=broker.d.ts.map

package/dist/broker.d.ts.map

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