@mergeline/agent 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -28,8 +28,11 @@ a newer kit, the claim's answer says to run
28
28
  `npx -y @mergeline/agent@latest init --claude` again. `login` checks the key with the
29
29
  board and saves it in `~/.config/mergeline/credentials.json` (readable only
30
30
  by you, outside any repository), per board and agent: `fe-1` on two boards
31
- is two saved keys. In a repository with `.mergeline.json`, `--url` can be
32
- left out. Several agents can be saved and work from the same repository:
31
+ is two saved keys. `login` takes the address typed with `--url` (or
32
+ `BOARD_URL`), never from `.mergeline.json`: in a repository someone else
33
+ controls (a clone, a fork, a PR branch) the key would go wherever its file
34
+ says, so without `--url` it refuses and prints the command with the file's
35
+ address for you to check. Several agents can be saved and work from the same repository:
33
36
  `board start qa-1` in another terminal. `board agents` lists them with their
34
37
  boards, `board logout <name>` forgets one (`--url <board>` when the name is
35
38
  saved for several). `board start <name> -- codex` starts another tool the
@@ -37,7 +40,12 @@ same way; `--agent <name>` makes any command act as a saved agent. The board
37
40
  in use is `BOARD_URL` when it is set, else the repository's
38
41
  `.mergeline.json`.
39
42
 
40
- Environment variables still work and win over saved keys:
43
+ Environment variables still work and win over saved keys. A key in
44
+ `BOARD_AGENT_KEY` (or `BOARD_AGENT_EMAIL` and `BOARD_AGENT_PASSWORD`) is used
45
+ with `BOARD_URL`: in a repository whose `.mergeline.json` names the board and
46
+ `BOARD_URL` is not set, every command and the MCP server refuse before any
47
+ request and say what to do, so a key exported in your shell never goes to
48
+ the address a repository names. `board start` and `--agent` set both.
41
49
 
42
50
  ```sh
43
51
  export BOARD_URL=https://board.example.com
@@ -62,13 +70,38 @@ npx @mergeline/agent init --dry-run # show what would change
62
70
  `CLAUDE.md` and leaves the rest of each file alone; running it again updates
63
71
  only that section. It writes `/pick` and `/done` only where no file of that
64
72
  name exists or where the file still carries the kit's marker line, adds its
65
- permissions to `.claude/settings.json` without removing any (plus the
66
- repository's own package manager: install and its test, lint and typecheck
67
- scripts, from the lockfile and `package.json`), and adds a `board` server to
73
+ permissions to `.claude/settings.json` (plus the repository's own package
74
+ manager: install and its test, lint and typecheck scripts, from the lockfile
75
+ and `package.json`) and removes only the broad rules an older kit wrote
76
+ (`Bash(board *)`, `Bash(git push *)` and the like), and adds a `board` server to
68
77
  `.mcp.json` that reads `${BOARD_URL}` and `${BOARD_AGENT_KEY}` from the
69
78
  environment, or else the key `login` saved: the key is never written to the
70
79
  repository.
71
80
 
81
+ What the agent may run without asking (kit 3, in `.claude/settings.json`):
82
+
83
+ - the board's MCP tools, and `board` (or `npx -y @mergeline/agent`) with
84
+ `claim`, `heartbeat`, `log`, `record-spec`, `ask`, `submit`, `release`,
85
+ `list`, `whoami`, `help`; Claude Code asks the person for `start`,
86
+ `watch`, `login`, `init` and `mcp`;
87
+ - `git fetch origin ...`, `git show`, `git rev-parse`, `git status`,
88
+ `git diff`, `git log`, `git add`, `git commit`, `git worktree add
89
+ ../.wt/...`, `git worktree list`, `git push origin agent/...` and
90
+ `git push -u origin agent/...` (one branch, nothing after it),
91
+ `git merge origin/main`;
92
+ - `gh pr create` and `gh pr view`, with the PR body as `--body` text;
93
+ - `npm test`, `npm run lint` and the project's own install, test, lint and
94
+ typecheck scripts.
95
+
96
+ Denied, whatever else allows it: `--upload-pack` (`git fetch -u`),
97
+ `--receive-pack`, `--exec`, `--output`, `--git-dir` and `--work-tree` on any
98
+ `git` command; a push to `main`, with `--force`, a refspec with `:`,
99
+ `--delete`, `-d`, `--mirror`, `--all` or `--tags`; a worktree path that
100
+ leaves `../.wt/`; `--repo` (`-R`) on `gh pr`, `--body-file` (`-F`) on
101
+ `gh pr create`; `gh pr merge`, `gh api`, `gh repo`, `curl`. An agent
102
+ stopped by a rule asks on the board (`board ask`) or releases the ticket
103
+ with what it needed, instead of waiting.
104
+
72
105
  MCP config (Claude Code `--mcp-config`, Codex, other MCP clients):
73
106
 
74
107
  ```json
@@ -107,7 +140,11 @@ stalls the agent at its first push.
107
140
 
108
141
  It stops when the queue is empty (unless `--follow`), after `--max-runs`
109
142
  (default 10), after 2 runs that changed nothing in the queue, or after 3
110
- failed runs in a row. One watcher per agent and machine.
143
+ failed runs in a row. One watcher per agent and machine. When the runs that
144
+ changed nothing all failed, the stop says so and points at the agent's
145
+ output; with `--usage-from claude-json`, a run Claude Code reports as failed
146
+ (`"is_error": true`, such as an expired login) is logged as `the agent
147
+ failed: <its message>`.
111
148
 
112
149
  A board that is paused (asleep until a person opens it; it answers HTTP 503
113
150
  with `{"code": "board_paused"}`) is not a failure: tools and commands say
package/dist/cli.js CHANGED
@@ -5,7 +5,8 @@
5
5
  // board <command> [args] the same calls as the MCP tools, one per run
6
6
  //
7
7
  // Connection: BOARD_URL and BOARD_AGENT_KEY (or BOARD_AGENT_EMAIL and
8
- // BOARD_AGENT_PASSWORD), as for the MCP server; without them, a key saved by
8
+ // BOARD_AGENT_PASSWORD), as for the MCP server (a key from the environment
9
+ // is never sent to the board a .mergeline.json names: pb.ts); without them, a key saved by
9
10
  // `board login <name>` (credentials.ts) for the board in use (BOARD_URL, or
10
11
  // the repository's .mergeline.json written by `board init --url`: repo.ts),
11
12
  // picked with --agent <name> or BOARD_AGENT, or the only one saved. `board start <name>` runs the agent's
@@ -43,11 +44,12 @@ Usage:
43
44
  so the commands below pick that board in this repository.
44
45
  Never overwrites what it did not write. --no-npx: MCP
45
46
  configs run "board mcp" (package installed globally).
46
- board login <name> [--url <board>] --key <key>
47
+ board login <name> --url <board> --key <key>
47
48
  check the key with the board and save it on this machine
48
49
  (~/.config/mergeline, outside any repository), per board and
49
- agent; --url defaults to the repository's board. Key "-"
50
- reads it from stdin. Once per agent and machine
50
+ agent; --url is required (or BOARD_URL), never taken from
51
+ the repository. Key "-" reads it from stdin. Once per agent
52
+ and machine
51
53
  board start [<name>] [-- <command...>] start the agent's tool (default: claude) with that agent's
52
54
  board address and key; then /pick. Name optional when
53
55
  only one agent is saved for the board in use
@@ -80,7 +82,8 @@ A text argument of "-" is read from stdin (for a multi-line plan).
80
82
 
81
83
  Environment:
82
84
  BOARD_URL the board (default: the repository's .mergeline.json, else http://127.0.0.1:8090)
83
- BOARD_AGENT_KEY the agent key shown when a human added the agent
85
+ BOARD_AGENT_KEY the agent key shown when a human added the agent; used only with BOARD_URL
86
+ (never sent to a board a repository's .mergeline.json names)
84
87
  BOARD_AGENT a saved agent's name, used when BOARD_AGENT_KEY is not set
85
88
  BOARD_CONFIG_DIR where board login saves keys (default ~/.config/mergeline)
86
89
  BOARD_SESSION optional session id; otherwise claim saves one in BOARD_STATE_DIR
@@ -172,8 +175,7 @@ function runInit(args) {
172
175
  out.write(result.codexConfig + "\n");
173
176
  }
174
177
  out.write("\nThen, once per agent and machine, save its key (shown when the agent was added on the board):\n" +
175
- ` board login <agent name> ${result.board ? "" : "--url <board address> "}--key <key>` +
176
- (result.board ? ` (the board: ${result.board}, from ${REPO_FILE})` : "") + "\n" +
178
+ ` board login <agent name> --url ${result.board ?? "<board address>"} --key <key>\n` +
177
179
  "and start each session with: board start <agent name>" + (args.includes("--codex") ? " -- codex" : "") + "\n" +
178
180
  "Commit AGENTS.md" + (args.includes("--claude") ? ", CLAUDE.md, .claude/, .mcp.json" : "") + `, ${REPO_FILE}` +
179
181
  " so every checkout has the kit; the key is not in any of them.\n");
@@ -212,16 +214,24 @@ async function runLogin(args) {
212
214
  if (!name || name.startsWith("-"))
213
215
  throw new UsageError("board login needs the agent's name: board login <name> --url <board> --key <key>");
214
216
  const given = option(args, "--url");
217
+ // The address is typed (or in BOARD_URL), never taken from a .mergeline.json:
218
+ // the repository may be someone else's, and the key would go where it says.
215
219
  let url;
220
+ let board = null;
216
221
  try {
217
- url = given === undefined ? boardInContext()?.url : normalizeBoardUrl(given);
222
+ board = given === undefined ? boardInContext() : null;
223
+ url = given !== undefined ? normalizeBoardUrl(given) : board?.from === "BOARD_URL" ? board.url : undefined;
218
224
  }
219
225
  catch (err) {
220
226
  throw new UsageError(err instanceof Error ? err.message : String(err));
221
227
  }
222
228
  let key = option(args, "--key");
229
+ if (!url && board) {
230
+ throw new BoardError(`board login needs the board's address typed; ${board.from} names ${board.url}. If that is your board, run: ` +
231
+ `board login ${name} --url ${board.url} --key <key>`);
232
+ }
223
233
  if (!url)
224
- throw new UsageError(`--url is required: the board's address, as shown on the board (or run it in a repository with ${REPO_FILE}: board init --url <board>)`);
234
+ throw new UsageError("--url is required: the board's address, as shown on the board");
225
235
  if (!key)
226
236
  throw new UsageError("--key is required: the key shown when the agent was added (or - to read it from stdin)");
227
237
  if (key === "-")
package/dist/init.js CHANGED
@@ -7,7 +7,8 @@
7
7
  // - Command and prompt files are written only when missing or when they carry
8
8
  // the kit's marker line; a file of the same name that the kit did not write
9
9
  // is skipped with a note.
10
- // - .claude/settings.json gets the kit's permissions added to its lists;
10
+ // - .claude/settings.json gets the kit's permissions added to its lists
11
+ // (and loses the broad allow rules of kits 1 and 2, RETIRED_ALLOW);
11
12
  // .mcp.json gets a `board` server unless it already has one. The agent key
12
13
  // is never written: .mcp.json refers to ${BOARD_URL} and ${BOARD_AGENT_KEY}.
13
14
  // The permissions also allow the repository's own package manager (from its
@@ -22,9 +23,13 @@
22
23
  // ~/.codex/prompts) and prints the MCP snippet for ~/.codex/config.toml,
23
24
  // which init does not edit. The snippet names the agent; its key stays in
24
25
  // the store `board login` writes, not in config.toml.
25
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
26
+ // - Init writes only real files inside the repository: when a file it would
27
+ // touch, or a folder between --dir and it, is a symbolic link (a cloned
28
+ // repository's CLAUDE.md linking to ~/.zshrc), it writes nothing and fails
29
+ // (realFilesOnly). --dir itself may be reached through a link.
30
+ import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
26
31
  import { homedir } from "node:os";
27
- import { dirname, join, relative } from "node:path";
32
+ import { dirname, join, relative, sep } from "node:path";
28
33
  import { fileURLToPath } from "node:url";
29
34
  import { readRepoFile, REPO_FILE } from "./repo.js";
30
35
  const KIT = fileURLToPath(new URL("../kit/", import.meta.url));
@@ -39,7 +44,7 @@ export const PACKAGE_VERSION = PACKAGE.version;
39
44
  * which wrote no version. The board says when a claim's kit is older than it
40
45
  * expects (KIT_MIN in pocketbase/pb_hooks/board_lib.js).
41
46
  */
42
- export const KIT_VERSION = 2;
47
+ export const KIT_VERSION = 3;
43
48
  const START = `<!-- mergeline:start (kit ${KIT_VERSION}; managed by \`board init\`; edit outside these markers) -->`;
44
49
  /** Markers are found by these prefixes, so an edited marker line or an older kit's still counts. */
45
50
  const START_PREFIX = "<!-- mergeline:start";
@@ -53,6 +58,18 @@ const COMMANDS = {
53
58
  pick: "Take the next ticket from the board and work on it",
54
59
  done: "Finish the current ticket: test, push, open a PR, submit for review",
55
60
  };
61
+ /**
62
+ * Allow rules an older kit wrote that kit 3 narrows (security audit run 1):
63
+ * init takes them out of settings.json, since adding the narrow rules next to
64
+ * them would change nothing.
65
+ */
66
+ const RETIRED_ALLOW = [
67
+ "Bash(board *)",
68
+ ...[PACKAGE_NAME, "@frontender-ua/agent", "@agent-board/agent"].map((p) => `Bash(npx -y ${p} *)`),
69
+ "Bash(git fetch *)",
70
+ "Bash(git worktree *)",
71
+ "Bash(git push *)",
72
+ ];
56
73
  /** Scripts the agent runs before a PR (done.md), when the project has them. */
57
74
  const CHECK_SCRIPTS = ["test", "lint", "typecheck", "check"];
58
75
  /**
@@ -77,7 +94,40 @@ export function projectCommands(dir) {
77
94
  commands.push(run(name));
78
95
  return { manager, commands: [...new Set(commands)] };
79
96
  }
97
+ /** The files init touches under dir, relative to it. */
98
+ function repoPaths(opts) {
99
+ const paths = [REPO_FILE, "AGENTS.md"];
100
+ if (opts.claude) {
101
+ paths.push("CLAUDE.md", join(".claude", "commands", "pick.md"), join(".claude", "commands", "done.md"), join(".claude", "settings.json"), ".mcp.json");
102
+ }
103
+ return paths;
104
+ }
105
+ /**
106
+ * Throws, before anything is written, when one of the files init touches, or
107
+ * a folder between opts.dir and it, is a symbolic link: writing through it
108
+ * would change a file outside the repository.
109
+ */
110
+ function realFilesOnly(opts) {
111
+ for (const path of repoPaths(opts)) {
112
+ const parts = path.split(sep);
113
+ for (let i = 1; i <= parts.length; i++) {
114
+ const rel = parts.slice(0, i).join(sep);
115
+ let link = false;
116
+ try {
117
+ link = lstatSync(join(opts.dir, rel)).isSymbolicLink();
118
+ }
119
+ catch {
120
+ break; // missing: init creates it, and everything below it, as real files and folders
121
+ }
122
+ if (link) {
123
+ throw new Error(`${rel} is a symbolic link; board init writes only real files inside the repository. ` +
124
+ `Replace it with a ${i < parts.length ? "folder" : "file"} and run init again.`);
125
+ }
126
+ }
127
+ }
128
+ }
80
129
  export function init(opts) {
130
+ realFilesOnly(opts);
81
131
  const actions = [];
82
132
  const write = (path, content, kind) => {
83
133
  if (!opts.dryRun && (kind === "create" || kind === "update")) {
@@ -195,7 +245,9 @@ export function init(opts) {
195
245
  json(join(opts.dir, ".claude", "settings.json"), (data) => {
196
246
  data.permissions ??= {};
197
247
  for (const [list, entries] of Object.entries(ours)) {
198
- const have = Array.isArray(data.permissions[list]) ? data.permissions[list] : [];
248
+ let have = Array.isArray(data.permissions[list]) ? data.permissions[list] : [];
249
+ if (list === "allow")
250
+ have = have.filter((e) => !RETIRED_ALLOW.includes(e));
199
251
  data.permissions[list] = [...have, ...entries.filter((e) => !have.includes(e))];
200
252
  }
201
253
  });
package/dist/mcp.js CHANGED
@@ -1,7 +1,8 @@
1
1
  // MCP server for a Mergeline board (stdio). One process = one agent session.
2
2
  // Started by `board mcp` (cli.ts) or `node dist/index.js`.
3
3
  // Credentials come from BOARD_AGENT_KEY (or BOARD_AGENT_EMAIL / BOARD_AGENT_PASSWORD); BOARD_URL
4
- // defaults to http://127.0.0.1:8090. All board access goes through
4
+ // defaults to http://127.0.0.1:8090 (pb.ts: a key from the environment is used
5
+ // only with BOARD_URL). All board access goes through
5
6
  // TicketService.
6
7
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
7
8
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -122,8 +123,13 @@ export async function runMcpServer() {
122
123
  board = new TicketService(agentCredentialsFromEnv());
123
124
  }
124
125
  catch (err) {
125
- console.error(`board MCP: ${err instanceof Error ? err.message : String(err)}`);
126
- process.exit(1);
126
+ // No usable credentials (none, or a key from the environment the board
127
+ // here may not get): serve anyway, so the agent sees why on its first
128
+ // tool call, and send nothing to any board.
129
+ const message = err instanceof Error ? err.message : String(err);
130
+ console.error(`board MCP: ${message}`);
131
+ await createServer(refusingBoard(message)).connect(new StdioServerTransport());
132
+ return;
127
133
  }
128
134
  // Log in up front so a bad config shows in the MCP logs right away. On
129
135
  // failure keep serving: every tool call retries the login and returns the
@@ -131,3 +137,9 @@ export async function runMcpServer() {
131
137
  await board.login().then(() => console.error(`board MCP: logged in as ${board.agentName}`), (err) => console.error(`board MCP: ${err instanceof Error ? err.message : String(err)}`));
132
138
  await createServer(board).connect(new StdioServerTransport());
133
139
  }
140
+ /** A stand-in for TicketService whose every call fails with message, before any request. */
141
+ function refusingBoard(message) {
142
+ return new Proxy({}, {
143
+ get: (_target, prop) => (prop === "then" ? undefined : () => Promise.reject(new BoardError(message))),
144
+ });
145
+ }
package/dist/pb.js CHANGED
@@ -1,21 +1,40 @@
1
1
  // Board connection settings for an agent session: the environment first,
2
2
  // else a key saved on this machine by `board login` (credentials.ts) for the
3
3
  // board in use (BOARD_URL, or the repository's .mergeline.json: repo.ts).
4
+ // A key from the environment is used only with BOARD_URL (envKeyRefusal).
4
5
  // The PocketBase client itself lives in service.ts, the only module that
5
6
  // imports the PocketBase SDK.
6
7
  import { pickSaved } from "./credentials.js";
7
8
  import { boardInContext } from "./repo.js";
8
9
  export const DEFAULT_BOARD_URL = "http://127.0.0.1:8090";
10
+ /**
11
+ * A key from the environment goes only to BOARD_URL (or the default address
12
+ * when nothing names a board): never to an address a repository's
13
+ * .mergeline.json names, since the repository may be someone else's (a
14
+ * clone, a fork, a PR branch checked out to review). Saved keys are safe
15
+ * already: each goes only to the board it was saved for.
16
+ */
17
+ function envKeyRefusal(what, board) {
18
+ return new Error(`${what}, and the board here is ${board.url} (from ${board.from}): ` +
19
+ `set BOARD_URL=${board.url} to use that key there, or save it with board login <name> --url ${board.url} --key <key>`);
20
+ }
9
21
  export function agentCredentialsFromEnv(env = process.env, cwd = process.cwd()) {
10
22
  const board = boardInContext(env, cwd);
11
23
  const url = board?.url || DEFAULT_BOARD_URL;
24
+ const fromFile = board && board.from !== "BOARD_URL" ? board : null;
12
25
  const key = env.BOARD_AGENT_KEY?.trim();
13
- if (key)
26
+ if (key) {
27
+ if (fromFile)
28
+ throw envKeyRefusal("BOARD_AGENT_KEY is set", fromFile);
14
29
  return { url, key };
30
+ }
15
31
  const email = env.BOARD_AGENT_EMAIL?.trim();
16
32
  const password = env.BOARD_AGENT_PASSWORD;
17
- if (email && password)
33
+ if (email && password) {
34
+ if (fromFile)
35
+ throw envKeyRefusal("BOARD_AGENT_EMAIL and BOARD_AGENT_PASSWORD are set", fromFile);
18
36
  return { url, email, password };
37
+ }
19
38
  // BOARD_AGENT names a saved agent; without it, the only one saved (for the board in use, if any).
20
39
  const saved = pickSaved(env.BOARD_AGENT?.trim() || undefined, board, env);
21
40
  if (saved)
package/dist/watch.js CHANGED
@@ -8,7 +8,8 @@
8
8
  // - the queue is empty (unless --follow, which then polls every --interval),
9
9
  // - --max-runs runs have happened,
10
10
  // - two runs in a row changed nothing in the queue (for example another
11
- // session of the agent holds its ticket), or
11
+ // session of the agent holds its ticket; when those runs all exited
12
+ // non-zero the stop says they failed instead), or
12
13
  // - the command failed three times in a row.
13
14
  // A paused board (asleep until a person opens it) is not a failure: the
14
15
  // watcher waits, checking every --interval, and goes on when it is back.
@@ -48,7 +49,29 @@ export function usageFromClaudeJson(output) {
48
49
  }
49
50
  return null;
50
51
  }
51
- /** The ticket a run worked on: the one whose state it changed, else the one it resumed. */
52
+ /**
53
+ * The error text of Claude Code's final JSON when it says the run failed
54
+ * (`"is_error": true`), on one line and cut short; else null.
55
+ */
56
+ export function errorFromClaudeJson(output) {
57
+ const candidates = [output.trim(), ...output.trim().split("\n").reverse()];
58
+ for (const text of candidates) {
59
+ let run;
60
+ try {
61
+ run = JSON.parse(text);
62
+ }
63
+ catch {
64
+ continue;
65
+ }
66
+ if (!run || typeof run !== "object" || run.is_error !== true)
67
+ continue;
68
+ const said = typeof run.result === "string" && run.result.trim() ? run.result : `no result text (subtype ${run.subtype ?? "unknown"})`;
69
+ const line = said.replace(/\s+/g, " ").trim();
70
+ return line.length > ERROR_CHARS ? `${line.slice(0, ERROR_CHARS)}...` : line;
71
+ }
72
+ return null;
73
+ }
74
+ const ERROR_CHARS = 300;
52
75
  /**
53
76
  * The ticket a run worked on, for its usage. Only a ticket the agent could
54
77
  * take when the run started counts (ready or in progress then): what a human
@@ -151,6 +174,8 @@ export async function watch(opts) {
151
174
  };
152
175
  let runs = 0;
153
176
  let noProgress = 0;
177
+ /** Exit codes of the runs counted in noProgress. */
178
+ let noProgressCodes = [];
154
179
  let failures = 0;
155
180
  let waitingLogged = false;
156
181
  try {
@@ -209,10 +234,18 @@ export async function watch(opts) {
209
234
  break;
210
235
  if (opts.usageFrom)
211
236
  await reportRunUsage(board, before, after, output, runs, log);
212
- noProgress = snapshot(after) === snapshot(before) ? noProgress + 1 : 0;
237
+ const unchanged = snapshot(after) === snapshot(before);
238
+ noProgress = unchanged ? noProgress + 1 : 0;
239
+ noProgressCodes = unchanged ? [...noProgressCodes, code] : [];
213
240
  if (noProgress >= NO_PROGRESS_STOP) {
214
- log(`${noProgress} runs in a row changed nothing in the queue; stopping. ` +
215
- "Is another session of this agent holding its ticket? See the board.");
241
+ if (noProgressCodes.every((c) => c !== 0)) {
242
+ const codes = [...new Set(noProgressCodes)].map((c) => `exit ${c}`).join(", ");
243
+ log(`${noProgress} runs in a row failed (${codes}) and changed nothing in the queue; stopping. The agent's error is above.`);
244
+ }
245
+ else {
246
+ log(`${noProgress} runs in a row changed nothing in the queue; stopping. ` +
247
+ "Is another session of this agent holding its ticket? See the board.");
248
+ }
216
249
  return 1;
217
250
  }
218
251
  }
@@ -225,12 +258,15 @@ export async function watch(opts) {
225
258
  }
226
259
  }
227
260
  async function reportRunUsage(board, before, after, output, run, log) {
261
+ const failed = errorFromClaudeJson(output);
262
+ if (failed)
263
+ log(`run ${run}: the agent failed: ${failed}`);
228
264
  const usage = usageFromClaudeJson(output);
229
265
  if (!usage)
230
- return log(`run ${run}: no Claude Code JSON result in the output; no usage reported`);
266
+ return failed ? undefined : log(`run ${run}: no Claude Code JSON result in the output; no usage reported`);
231
267
  const ticket = workedOn(before, after);
232
268
  if (!ticket)
233
- return log(`run ${run}: could not tell which ticket the run worked on; usage not reported`);
269
+ return failed ? undefined : log(`run ${run}: could not tell which ticket the run worked on; usage not reported`);
234
270
  try {
235
271
  const res = await board.reportUsage(ticket.id, usage);
236
272
  log(res.stored
@@ -5,19 +5,68 @@
5
5
  ],
6
6
  "allow": [
7
7
  "mcp__board__*",
8
- "Bash(board *)",
9
- "Bash(npx -y {{package}} *)",
10
- "Bash(git fetch *)",
8
+ "Bash(board claim)",
9
+ "Bash(board claim *)",
10
+ "Bash(board heartbeat)",
11
+ "Bash(board heartbeat *)",
12
+ "Bash(board log)",
13
+ "Bash(board log *)",
14
+ "Bash(board record-spec)",
15
+ "Bash(board record-spec *)",
16
+ "Bash(board ask)",
17
+ "Bash(board ask *)",
18
+ "Bash(board submit)",
19
+ "Bash(board submit *)",
20
+ "Bash(board release)",
21
+ "Bash(board release *)",
22
+ "Bash(board list)",
23
+ "Bash(board list *)",
24
+ "Bash(board whoami)",
25
+ "Bash(board whoami *)",
26
+ "Bash(board help)",
27
+ "Bash(board help *)",
28
+ "Bash(npx -y {{package}} claim)",
29
+ "Bash(npx -y {{package}} claim *)",
30
+ "Bash(npx -y {{package}} heartbeat)",
31
+ "Bash(npx -y {{package}} heartbeat *)",
32
+ "Bash(npx -y {{package}} log)",
33
+ "Bash(npx -y {{package}} log *)",
34
+ "Bash(npx -y {{package}} record-spec)",
35
+ "Bash(npx -y {{package}} record-spec *)",
36
+ "Bash(npx -y {{package}} ask)",
37
+ "Bash(npx -y {{package}} ask *)",
38
+ "Bash(npx -y {{package}} submit)",
39
+ "Bash(npx -y {{package}} submit *)",
40
+ "Bash(npx -y {{package}} release)",
41
+ "Bash(npx -y {{package}} release *)",
42
+ "Bash(npx -y {{package}} list)",
43
+ "Bash(npx -y {{package}} list *)",
44
+ "Bash(npx -y {{package}} whoami)",
45
+ "Bash(npx -y {{package}} whoami *)",
46
+ "Bash(npx -y {{package}} help)",
47
+ "Bash(npx -y {{package}} help *)",
48
+ "Bash(git fetch origin)",
49
+ "Bash(git fetch origin *)",
11
50
  "Bash(git show *)",
12
51
  "Bash(git rev-parse *)",
13
- "Bash(git worktree *)",
52
+ "Bash(git status)",
14
53
  "Bash(git status *)",
54
+ "Bash(git diff)",
15
55
  "Bash(git diff *)",
56
+ "Bash(git log)",
16
57
  "Bash(git log *)",
17
58
  "Bash(git add *)",
18
59
  "Bash(git commit *)",
19
- "Bash(git push *)",
60
+ "Bash(git worktree add ../.wt/*)",
61
+ "Bash(git worktree list)",
62
+ "Bash(git push origin agent/*)",
63
+ "Bash(git push -u origin agent/*)",
64
+ "Bash(git merge origin/main)",
65
+ "Bash(git merge --no-edit origin/main)",
66
+ "Bash(git merge origin/main --no-edit)",
67
+ "Bash(gh pr create)",
20
68
  "Bash(gh pr create *)",
69
+ "Bash(gh pr view)",
21
70
  "Bash(gh pr view *)",
22
71
  "Bash(npm test)",
23
72
  "Bash(npm run lint)"
@@ -27,13 +76,39 @@
27
76
  "Bash(gh pr merge *)",
28
77
  "Bash(gh api *)",
29
78
  "Bash(gh repo *)",
79
+ "Bash(git *--upload-pack*)",
80
+ "Bash(git *--receive-pack*)",
81
+ "Bash(git *--exec*)",
82
+ "Bash(git *--output*)",
83
+ "Bash(git *--git-dir*)",
84
+ "Bash(git *--work-tree*)",
85
+ "Bash(git fetch -u*)",
86
+ "Bash(git fetch * -u*)",
30
87
  "Bash(git push origin main*)",
31
88
  "Bash(git push -u origin main*)",
32
89
  "Bash(git push origin HEAD:main*)",
33
90
  "Bash(git push --force*)",
34
91
  "Bash(git push -f *)",
35
92
  "Bash(git push * --force*)",
36
- "Bash(git push * -f*)"
93
+ "Bash(git push * -f*)",
94
+ "Bash(git push *:*)",
95
+ "Bash(git push origin agent/* *)",
96
+ "Bash(git push -u origin agent/* *)",
97
+ "Bash(git push * --delete*)",
98
+ "Bash(git push * -d*)",
99
+ "Bash(git push * --mirror*)",
100
+ "Bash(git push * --all*)",
101
+ "Bash(git push * --tags*)",
102
+ "Bash(git worktree add ../.wt/*..*)",
103
+ "Bash(gh pr create *--repo*)",
104
+ "Bash(gh pr create * -R*)",
105
+ "Bash(gh pr create -R*)",
106
+ "Bash(gh pr view *--repo*)",
107
+ "Bash(gh pr view * -R*)",
108
+ "Bash(gh pr view -R*)",
109
+ "Bash(gh pr create *--body-file*)",
110
+ "Bash(gh pr create * -F*)",
111
+ "Bash(gh pr create -F*)"
37
112
  ]
38
113
  }
39
114
  }
package/kit/rules.md CHANGED
@@ -25,6 +25,9 @@ the done instructions: `/pick` and `/done` in Claude Code,
25
25
  - Call `heartbeat` after every meaningful step. If a board tool says to claim
26
26
  again, stop and claim. If it says another session holds the ticket, stop
27
27
  at once: no commit, no push, no PR.
28
+ - If something in your environment stops you (a command you need is
29
+ denied, a tool is missing), do not wait: say what and why with
30
+ `ask_human` (`board ask`), or `release` the ticket with that note.
28
31
  - If a board tool says the board is paused, stop and tell the human: it
29
32
  wakes when a person opens it. Do not retry in a loop.
30
33
  - If `claim` answers with `kit_outdated`, tell the human what it says once
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mergeline/agent",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "The agent's side of a Mergeline board: an MCP server and the `board` CLI. Works with any agent tool that runs MCP servers or shell commands.",
5
5
  "license": "MIT",
6
6
  "author": "frontender-ua",