@puh00/pi-merge-watcher0.1.1

Pi merge watcher

This Pi extension registers watch_gerrit_merge, watch_github_merge, and /watch-merge. It monitors one forge change per session. When the forge confirms a merge, Pi displays a custom message such as:

GitHub pull request merged
owner/repository #123
https://github.com/owner/repository/pull/123

Polling makes no model requests. When a change merges, the extension displays a custom message and wakes the agent by default. Set wakeAgent to false in ~/.pi/agent/merge-watcher.json to keep the message passive. The awakened agent follows its AGENTS.md instructions. The extension itself never performs cleanup, and a merge wake does not grant blanket authorization for cleanup.

Arm, status, and cancel

Arm with the provider, host, project, and change number. GitHub projects use owner/repository; Gerrit projects use their project path. The tools accept these three identity fields and an optional action (arm, status, or cancel). Omitting the action arms. Cancel must match provider, host, project, and change.

The first argument autocompletes github, gerrit, status, or cancel; completion stops after the first argument.

Slash command forms:

• /watch-merge github <host> <owner/repo> <pull-request>
• /watch-merge gerrit <host> <project> <change>
• /watch-merge <host> <project> <change> for Gerrit, retained for compatibility
• /watch-merge status and /watch-merge cancel

The deprecated GitHub seven-word form /watch-merge github <host> <owner/repo> <pull-request> <worktree> <lease> <head> and Gerrit six-word form /watch-merge <host> <project> <change> <worktree> <lease> <head> still work. Their extra local identity fields are ignored. Legacy tool inputs worktree, lease, and head are also accepted and ignored.

The extension checks immediately and then every five minutes. Gerrit WIP and GitHub draft changes pause until re-armed. Authentication failures pause until re-armed. Missing CLI dependencies pause with an actionable error and do not retry. Other errors retry with exponential backoff. Closed, unmerged GitHub pull requests stop as abandoned. Pi must remain open, and the session must resume for monitoring to continue.

Agent wake configuration

The extension reads ~/.pi/agent/merge-watcher.json when it loads. If PI_CODING_AGENT_DIR is set, it reads merge-watcher.json from that directory instead. A missing file or omitted wakeAgent property defaults to true. Set it to false to disable merge-triggered agent turns:

{
  "wakeAgent": false
}

The setting applies after /reload. Invalid JSON, a non-object value, a non-boolean wakeAgent, or a config read error produces an error notification at session start and prevents a merge message from being delivered. Polling itself never makes model requests. With wake enabled, the merge message starts an agent turn when idle and queues as a follow-up when the agent is busy. With wake disabled, Pi stores and displays the message without starting a turn. A wake only schedules agent work. It does not authorize deleting local or remote data; follow the project's AGENTS.md instructions and obtain approval when required.

Dependencies and authentication

Use Node 22.23.2 or newer and Pi 1.4.0 or compatible. When you install this package with pi install npm:@puh00/pi-merge-watcher, Pi installs its declared @toon-format/toon runtime dependency. Pi supplies @earendil-works/pi-coding-agent and TypeBox as host peer dependencies. Do not install or bundle those host packages through this extension. The npm ci command is for working from a source checkout, as shown under Local checks.

GitHub monitoring requires gh-axi and its underlying GitHub CLI gh. It was checked with gh-axi 0.1.35 and gh 2.102.0. Authenticate the host with gh auth login --hostname <host> and confirm with gh auth status --hostname <host>. gh-axi uses that configured gh authentication. Gerrit monitoring requires gerrit-axi (checked with 0.5.0) and its own configured authentication. See gerrit-axi --help for the installed version's authentication setup. You need only the CLI and authentication for the provider you use. The extension never installs either CLI, calls Git, or invokes Treehouse.

Persistence and legacy records

State is appended to the Pi session and restored from its active branch. Session ID and canonical session working directory scope each watcher. Legacy v1 records migrate to v2 notification-only records; their worktree, lease, and HEAD metadata are discarded and never used for cleanup. A record with notified: true is treated as terminal merged, even if its old state was inconsistent. The last valid matching record on the branch wins, so an earlier legacy record cannot override a later cancellation or merge.

Pi cannot atomically persist watcher state and deliver a message. With wake disabled, a busy Pi queues a passive message until the current turn ends; with wake enabled, a busy Pi queues a follow-up turn. In both cases, the watcher stores notified: true before Pi flushes the queued message. A crash in that interval can lose the notice, and restore will not retry it. When Pi is idle, Pi appends the message immediately and may start a turn before the watcher stores notified; a crash in that interval can produce a duplicate notice or turn after resume. The extension has no delivery acknowledgment or transaction to close either window.

Install the extension

Install the Pi package from npm:

pi install npm:@puh00/pi-merge-watcher

If you previously installed this extension by symlinking the repository into ~/.pi/agent/extensions/, remove only that link before reloading. First inspect it and confirm the link points to this repository:

ls -ld ~/.pi/agent/extensions/pi-merge-watcher
readlink ~/.pi/agent/extensions/pi-merge-watcher

If the path is a symlink and its target is the old repository checkout, remove the link itself with unlink, not rm -r:

unlink ~/.pi/agent/extensions/pi-merge-watcher

Do not run unlink if the path is a directory or points somewhere else. Keep the repository checkout; removing the symlink does not remove its target. Run /reload in Pi after installation and removal of the old link.

Automated releases

Pull requests to main and pushes to main run the tests, typecheck, smoke test, and package dry run. With the matching npm trusted publisher configured, each successful push to main publishes the next patch version. The workflow reads the latest npm version before incrementing and serializes releases to avoid version collisions. It does not commit version changes or create Git tags.

To enable publishing, open the package's settings on npm and add a GitHub Actions trusted publisher with owner Puh00, repository pi-merge-watcher, workflow filename publish.yml, and permission to run npm publish. Leave the environment blank. The workflow uses OIDC, so the repository does not need an npm publish token. This private GitHub repository does not produce npm provenance attestations.

Local checks

This repository targets Pi 1.4.0 and Node 22.23.2. For tests and type checking in a development worktree, install project dependencies first. Then link Pi's host-provided peer modules into the project's local node_modules (do not replace the whole directory with a symlink):

npm ci --legacy-peer-deps
PI_NODE_MODULES=/path/to/your/pi/node_modules
mkdir -p node_modules/@earendil-works
ln -s "$PI_NODE_MODULES/@earendil-works/pi-coding-agent" node_modules/@earendil-works/pi-coding-agent
ln -s "$PI_NODE_MODULES/typebox" node_modules/typebox

Set PI_NODE_MODULES to the node_modules directory for the Pi version used in development. Run:

npm test
npm run typecheck
npm run smoke

The smoke test loads the directory-linked extension through the Pi SDK and sends no prompt or model request.

License

This project is licensed under GNU GPL version 3 or, at your option, any later version. See LICENSE.