agent-merge-broker 0.3.0

package/docs/SECURITY.md

@@ -0,0 +1,57 @@
+# Security model
+
+## Trust boundary
+
+Agent Merge Broker is intended for trusted repositories and trusted integration hosts. The checked-in configuration is executable policy: validator commands run through the host shell inside an integration worktree. Reviewing a configuration change is as important as reviewing a CI workflow change.
+
+Do not run the broker automatically on untrusted fork configuration. A safe forge integration should load policy from the protected base branch, not from an incoming change.
+
+## Credentials
+
+- Lease tokens contain 192 bits of randomness and only SHA-256 digests are persisted in broker state.
+- By default the broker also keeps the token itself in `<state>/tokens/`, mode 0600, so callers do
+  not have to invent a credential store. This grants nothing new: anyone who can read that directory
+  can already edit broker state directly. It exists because the alternative in practice is a token
+  written into the working tree, where `git add` and validator commands can reach it. Claim with
+  `--no-store-token` to opt out, or `--token-file` to place it elsewhere.
+- Tokens may also be supplied through `MERGE_BROKER_TOKEN` or a process-level secret channel.
+- `MERGE_BROKER_TOKEN` is removed from the environment passed to validator commands. Configuration
+  is trusted to execute commands, but a validator has no need for a credential that can submit or
+  cancel work on a worker's behalf.
+- Do not place tokens in commits, task titles, validator commands, or logs.
+- Git and GitHub credentials remain owned by the host's normal credential helpers.
+- Validator stdout and stderr are retained locally and may contain accidental secrets. Output is capped, not redacted.
+
+Runtime state is stored inside Git's common directory and inherits its filesystem permissions. Anyone who can modify the repository's Git directory can modify broker state or audit records. The audit stream is append-only by convention, not cryptographically tamper-evident.
+
+## Git safety
+
+The broker does not force-push, reset the user's base worktree, merge into the base branch, or delete source branches. It creates uniquely named integration branches and temporary worktrees under its own state directory.
+
+Failed integration worktrees are removed by default. Enabling `keepFailedWorktrees` can retain source content, generated artifacts, and secrets written by validators; operators must clean these worktrees deliberately after diagnosis.
+
+Commit receipts are immutable IDs, but their objects can disappear after aggressive source-repository garbage collection if no ref retains them. Integrate or otherwise retain submitted commits before pruning unreachable branches.
+
+## Command construction
+
+Configuration is trusted. `{files}` and `{taskId}` placeholders are shell-quoted, and structured metadata is also supplied as environment variables. Prefer environment variables when composing complex commands.
+
+Validators run under a fixed interpreter — `/bin/sh` by default, or `validation.shell` — and never under a login shell. Sourcing an operator's personal profile would make an integration decision depend on whose machine assembled the batch, and would let a compromised dotfile influence what the broker reports as validated. Quoting follows the configured shell; POSIX shells are the supported and tested surface.
+
+Task and batch metadata must still be treated as untrusted display text by external dashboards. The bundled GitHub publisher constructs command arguments without a shell and sends PR content through stdin.
+
+## Enforcement boundaries
+
+`install-hooks` is a local convenience, not a security control: a pre-push hook is client-side and
+any worker can bypass it. It exists to make the intended path the easy one and to catch mistakes
+early.
+
+`verify-provenance` is the enforceable boundary, and only when the forge requires it on a protected
+branch. It reads verification policy from the configuration committed on the base branch, because
+the checked-out tree belongs to the change being judged. It proves that a head is an unaltered
+broker batch; it does not prove that the batch's contents are good, which is what the repository's
+own validation is for.
+
+## Reporting vulnerabilities
+
+Before a public security address is established, report vulnerabilities privately to the repository owner. Do not open a public issue containing exploitable details or credentials.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "agent-merge-broker",
+  "version": "0.3.0",
+  "description": "A transaction coordinator for parallel code-producing agents and humans.",
+  "type": "module",
+  "bin": {
+    "merge-broker": "dist/cli.js",
+    "amb": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "schemas",
+    "templates",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --test-reporter=spec dist/*.test.js",
+    "example": "sh examples/two-agents/run.sh",
+    "test:source": "tsx --test src/*.test.ts",
+    "verify": "npm run lint && npm run build && npm test",
+    "prepublishOnly": "npm run verify"
+  },
+  "engines": {
+    "node": ">=20.12"
+  },
+  "keywords": [
+    "ai-agents",
+    "git",
+    "merge-queue",
+    "worktree",
+    "ci",
+    "developer-tools"
+  ],
+  "author": "PowerHouse Exteriors",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WeSpitfire/agent-merge-broker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WeSpitfire/agent-merge-broker/issues"
+  },
+  "homepage": "https://github.com/WeSpitfire/agent-merge-broker#readme",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "picomatch": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/picomatch": "^4.0.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}

package/schemas/config.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WeSpitfire/agent-merge-broker/raw/main/schemas/config.schema.json",
+  "title": "Agent Merge Broker configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "baseBranch",
+    "baseRef",
+    "remote",
+    "stateDirectory",
+    "leases",
+    "policies",
+    "scheduling",
+    "integration",
+    "validation",
+    "publish"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "baseBranch": { "type": "string", "minLength": 1 },
+    "baseRef": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Git revision used for integration, such as origin/main; separate from the forge target branch."
+    },
+    "remote": { "type": "string", "minLength": 1 },
+    "stateDirectory": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Safe relative directory beneath Git's common directory; Git-reserved top-level names are rejected."
+    },
+    "leases": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ttlSeconds", "lockTimeoutSeconds", "serializedPatterns"],
+      "properties": {
+        "ttlSeconds": { "type": "integer", "minimum": 1 },
+        "lockTimeoutSeconds": { "type": "integer", "minimum": 1 },
+        "serializedPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+      }
+    },
+    "policies": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unexpectedPaths", "requireCleanWorktree", "requireDependencies"],
+      "properties": {
+        "unexpectedPaths": { "enum": ["error", "warn", "allow"] },
+        "requireCleanWorktree": { "type": "boolean" },
+        "requireDependencies": { "type": "boolean" }
+      }
+    },
+    "scheduling": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maxTasks", "maxCommits", "maxWaitSeconds", "allowPathOverlap"],
+      "properties": {
+        "maxTasks": { "type": "integer", "minimum": 1 },
+        "maxCommits": { "type": "integer", "minimum": 1 },
+        "maxWaitSeconds": { "type": "integer", "minimum": 1 },
+        "allowPathOverlap": { "type": "boolean" }
+      }
+    },
+    "integration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["branchPrefix", "history", "keepFailedWorktrees"],
+      "properties": {
+        "branchPrefix": { "type": "string", "minLength": 1 },
+        "history": { "enum": ["preserve", "squash"] },
+        "keepFailedWorktrees": { "type": "boolean" },
+        "refreshBase": {
+          "type": "boolean",
+          "description": "Fetch the remote base branch before cutting a batch so the branch is not born behind it.",
+          "default": true
+        },
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How many times a task may be automatically returned to the queue before it is left failed.",
+          "default": 3
+        },
+        "provenance": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["enabled", "directory"],
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "directory": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["focused", "authoritative"],
+      "properties": {
+        "shell": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Interpreter used to run validator commands. Defaults to /bin/sh, or ComSpec on Windows. Never a login shell: validation must not depend on personal dotfiles."
+        },
+        "focused": { "type": "array", "items": { "$ref": "#/$defs/validator" } },
+        "authoritative": { "type": "array", "items": { "$ref": "#/$defs/validator" } }
+      }
+    },
+    "publish": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "draft", "labels", "titleTemplate"],
+      "properties": {
+        "mode": { "enum": ["none", "branch", "pull-request"] },
+        "draft": { "type": "boolean" },
+        "autoMerge": {
+          "type": "boolean",
+          "description": "Ask GitHub to merge the pull request once required checks pass. Requires mode pull-request and draft false.",
+          "default": false
+        },
+        "mergeMethod": { "enum": ["squash", "merge", "rebase"], "default": "squash" },
+        "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "titleTemplate": { "type": "string", "minLength": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "autoMerge": { "const": true } }, "required": ["autoMerge"] },
+          "then": {
+            "properties": { "draft": { "const": false }, "mode": { "const": "pull-request" } }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "validator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "command"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "timeoutSeconds": { "type": "integer", "minimum": 1 },
+        "env": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/provenance.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WeSpitfire/agent-merge-broker/raw/main/schemas/provenance.schema.json",
+  "title": "Agent Merge Broker batch provenance",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generator", "batchId", "baseBranch", "baseSha", "integratedHeadSha", "taskIds", "tasks", "validations", "createdAt"],
+  "properties": {
+    "version": { "const": 1 },
+    "generator": { "const": "agent-merge-broker" },
+    "batchId": { "type": "string", "minLength": 1 },
+    "baseBranch": { "type": "string", "minLength": 1 },
+    "history": {
+      "enum": ["preserve", "squash"],
+      "description": "How the batch was assembled. Squashing drops the cherry-pick trail, so a verifier cannot trace submitted commits in the integrated history. Absent on manifests written before this field existed, which always preserved history.",
+      "default": "preserve"
+    },
+    "baseSha": { "$ref": "#/$defs/sha" },
+    "integratedHeadSha": { "$ref": "#/$defs/sha" },
+    "taskIds": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "commits", "actualPaths", "dependsOn"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "commits": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sha" } },
+          "actualPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "dependsOn": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+        }
+      }
+    },
+    "validations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "scope", "exitCode", "durationMs"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "scope": { "enum": ["focused", "authoritative"] },
+          "taskId": { "type": "string", "minLength": 1 },
+          "exitCode": { "const": 0 },
+          "durationMs": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" }
+  }
+}

package/schemas/receipt.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WeSpitfire/agent-merge-broker/raw/main/schemas/receipt.schema.json",
+  "title": "Agent Merge Broker commit receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "taskId",
+    "baseSha",
+    "commits",
+    "expectedPaths",
+    "actualPaths",
+    "dependsOn",
+    "submittedAt",
+    "warnings"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "taskId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:@/-]{0,127}$"
+    },
+    "agent": { "type": "string", "minLength": 1 },
+    "baseSha": { "$ref": "#/$defs/sha" },
+    "commits": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sha" } },
+    "expectedPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "actualPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "dependsOn": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "worktree": { "type": "string", "minLength": 1 },
+    "submittedAt": { "type": "string", "format": "date-time" },
+    "warnings": { "type": "array", "items": { "type": "string" } }
+  },
+  "$defs": {
+    "sha": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" }
+  }
+}

package/templates/AGENTS.snippet.md

@@ -0,0 +1,5 @@
+## Agent Merge Broker
+
+Before editing, every worker must claim a task with the narrowest accurate path scope. Keep the lease alive during long work. Produce focused commits and submit their immutable SHAs to the broker. Workers must not merge, rebase, push, open pull requests, or modify integration branches.
+
+Read `.merge-broker/agent-instructions.md` for the exact command protocol. The integration owner runs `merge-broker plan`, `merge-broker integrate`, and publication commands.