@modootoday/pmcp 0.24.1 → 0.26.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/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +1 -1
- package/dist/{affected-IPFJM2KD.js → affected-4FILH743.js} +174 -77
- package/dist/{apply-CDJQJAZH.js → apply-HJUCYQDQ.js} +18 -15
- package/dist/{broadcast-VKZY7WSD.js → broadcast-U7ZYOJWE.js} +7 -4
- package/dist/{chunk-GEDRPMBH.js → chunk-2GL5L2G5.js} +2 -2
- package/dist/{chunk-AQM2JZMB.js → chunk-2JUHFM4V.js} +2 -2
- package/dist/{chunk-UKR64U7J.js → chunk-374AZ4J4.js} +2 -2
- package/dist/{chunk-MZ52S4YJ.js → chunk-3JOFDNL4.js} +2 -2
- package/dist/{chunk-264DIB5U.js → chunk-3KISMGVP.js} +4 -4
- package/dist/{chunk-V5PXMLLL.js → chunk-6XE3WW7S.js} +3 -3
- package/dist/{chunk-7CGGDX7X.js → chunk-7FHOSWNQ.js} +2 -2
- package/dist/{chunk-5NQZGNKT.js → chunk-7PBWLYCO.js} +3 -3
- package/dist/{chunk-2GZKA33O.js → chunk-A4P3IIPE.js} +2 -2
- package/dist/{chunk-3O3JZTUU.js → chunk-C7Y2MBCN.js} +3 -3
- package/dist/chunk-D7IDT7OA.js +21 -0
- package/dist/chunk-E272CFPS.js +14 -0
- package/dist/chunk-FLG7VRTC.js +1 -0
- package/dist/{chunk-X3RUXLAV.js → chunk-FXDGW2IH.js} +3 -3
- package/dist/{chunk-DLIO2D7S.js → chunk-GIL3RBRX.js} +27 -20
- package/dist/{chunk-ARXCYFFZ.js → chunk-GQRDEIQA.js} +22 -2
- package/dist/chunk-J43Z4O3G.js +7 -0
- package/dist/chunk-KLIYFD3W.js +32 -0
- package/dist/{chunk-PG62GOPU.js → chunk-KQV2EPAP.js} +2 -2
- package/dist/{chunk-LNKAR3IS.js → chunk-LCPCRZ7N.js} +2 -2
- package/dist/chunk-NQCAKDRY.js +156 -0
- package/dist/{chunk-3SEJNT6F.js → chunk-NQZMGQFG.js} +5 -5
- package/dist/{chunk-DGXZBQCA.js → chunk-OBCBCLS2.js} +7 -7
- package/dist/{chunk-D4FIBB2G.js → chunk-OG2ESRQP.js} +5 -5
- package/dist/{chunk-43MXRTKH.js → chunk-OHCUPXU4.js} +26 -8
- package/dist/chunk-OIKT4SYO.js +42 -0
- package/dist/{chunk-3V37OZQH.js → chunk-PAY6HEEY.js} +2 -2
- package/dist/{chunk-QY2P54Z2.js → chunk-PZ6D3WKD.js} +125 -8
- package/dist/{chunk-MOKZPZZO.js → chunk-Q5BQIRM3.js} +2 -2
- package/dist/{chunk-VYQJPT27.js → chunk-S2FUWBLO.js} +18 -4
- package/dist/{chunk-OGCJO6HQ.js → chunk-TQRLWO4F.js} +2 -2
- package/dist/{chunk-VBWB2T3C.js → chunk-UVPIVSZB.js} +14 -6
- package/dist/{chunk-MHKY6TNF.js → chunk-VN34GLGJ.js} +3 -3
- package/dist/chunk-WUFNKK3U.js +71 -0
- package/dist/{chunk-2ZH77O2D.js → chunk-Y7FYCVUK.js} +646 -103
- package/dist/{chunk-HES44LTA.js → chunk-YJVSN6UN.js} +29 -5
- package/dist/{chunk-EWYLWBKS.js → chunk-YKICVMF7.js} +22 -5
- package/dist/{cli-OV5LSSGE.js → cli-FVUHK2NB.js} +7 -7
- package/dist/{cli-GFDT4YXM.js → cli-ZOY2274X.js} +9 -9
- package/dist/cli.js +40 -6
- package/dist/{completion-QNDCU4MF.js → completion-ZKWGPMEK.js} +6 -5
- package/dist/{diagnostics-TPK3VC5F.js → diagnostics-IM2OPAPL.js} +7 -7
- package/dist/{doctor-K2LADSW2.js → doctor-VZTHEPVC.js} +32 -20
- package/dist/{entry-HFQHKL5L.js → entry-Q4EI4PNO.js} +13 -13
- package/dist/{exec-mcp-I2YGGWY4.js → exec-mcp-AWGUQVT2.js} +15 -12
- package/dist/{harness-BMWGAXCF.js → harness-L4C5XWKR.js} +3 -3
- package/dist/harness-launch-gate.js +5 -5
- package/dist/harness-worker.js +7 -7
- package/dist/{heavy-G6CYQQ7O.js → heavy-OG3UVZNY.js} +327 -131
- package/dist/hook-body.js +664 -161
- package/dist/{hook-spec-Bd24eo2L.d.ts → hook-spec-u7hnz571.d.ts} +10 -0
- package/dist/{hooks-R7AYQXHY.js → hooks-2E6PJJQK.js} +4 -4
- package/dist/{host-PLE2T55E.js → host-OQDBQJB2.js} +8 -8
- package/dist/{host-EUD6GLWV.js → host-RJJGTKWA.js} +20 -65
- package/dist/{host-run-QFNGIDL5.js → host-run-PWCIXJDN.js} +6 -6
- package/dist/http.js +1 -1
- package/dist/{import-mcp-DVKJOEOE.js → import-mcp-2H2NRUCL.js} +14 -11
- package/dist/index.d.ts +2 -2
- package/dist/index.js +18 -15
- package/dist/{init-DKWNL62M.js → init-O2UCU2WT.js} +2 -2
- package/dist/{invoke-U6JTPTXT.js → invoke-SJ3JHRJU.js} +9 -9
- package/dist/{list-YKQFJN3G.js → list-SJVXZGKK.js} +17 -14
- package/dist/{logout-5YSKC46N.js → logout-ROKXWR3T.js} +15 -12
- package/dist/{logs-2JEMSNSG.js → logs-J4W6GFMK.js} +4 -4
- package/dist/{mailbox-5FVFMQ2J.js → mailbox-6MHH6CUA.js} +22 -8
- package/dist/{mainline-D3PSR6AJ.js → mainline-SWZPKA7U.js} +19 -9
- package/dist/{mcp-CHKKXHBB.js → mcp-U7MVFAB4.js} +2 -2
- package/dist/owners-MPI22SFU.js +63 -0
- package/dist/{pause-CMZOIHTJ.js → pause-3IMVYXQQ.js} +7 -4
- package/dist/project/hook-adapter.d.ts +1 -1
- package/dist/{project-QEYXISHC.js → project-MGUYHUF7.js} +4 -4
- package/dist/{report-UB7MXAUB.js → report-MWXB5XKE.js} +5 -5
- package/dist/{resume-PAKIT4TT.js → resume-7LCSV4X3.js} +7 -4
- package/dist/{run-HKMYYEZJ.js → run-DDWLS6FY.js} +14 -11
- package/dist/{run-FYKDIW4C.js → run-TBO5JO4Y.js} +4 -4
- package/dist/{serve-QZNG5UUV.js → serve-RBQYB3FP.js} +3 -3
- package/dist/{setup-GRWLDBVB.js → setup-7JHWLV7K.js} +6 -4
- package/dist/{smoke-6X6IXQIQ.js → smoke-GZECLXOJ.js} +3 -3
- package/dist/{start-login-4GPM32RA.js → start-login-SOTNDUP6.js} +15 -12
- package/dist/{status-55CD352M.js → status-EBIUQIGY.js} +35 -30
- package/dist/{status-4PYPTYUB.js → status-QFMN7IUG.js} +8 -5
- package/dist/{status-W6SCF2GF.js → status-TSTOFNZU.js} +15 -12
- package/dist/stdio.js +2 -2
- package/dist/{sweep-VURZU6DI.js → sweep-BS7HVSNP.js} +7 -4
- package/dist/{test-XYEMYZ2P.js → test-4PZHHWOQ.js} +28 -16
- package/dist/{tui-FXSWN2PV.js → tui-QD2LMXHV.js} +4 -4
- package/dist/{unbroadcast-7AMLURCG.js → unbroadcast-GRGX3F6T.js} +7 -4
- package/dist/{worker-Q4I4EIAJ.js → worker-SPJ4HFWV.js} +11 -11
- package/dist/{worktree-list-2HV6ODBS.js → worktree-list-WZC75NLF.js} +8 -9
- package/dist/{worktree-sync-MUVKK2CV.js → worktree-sync-BQZD4J73.js} +5 -2
- package/docs/commands.md +18 -7
- package/docs/git-workflow.md +40 -5
- package/docs/glossary.md +1 -1
- package/docs/hooks.md +75 -16
- package/docs/project-configuration.md +136 -40
- package/docs/sessions.md +9 -2
- package/docs/upgrading.md +71 -0
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +5 -5
- package/plugin.json +1 -1
- package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/plugin.json +1 -1
- package/dist/chunk-65H4PN33.js +0 -7
- package/dist/chunk-7TD53M7L.js +0 -13
- package/dist/chunk-FQLCD4HU.js +0 -24
package/docs/commands.md
CHANGED
|
@@ -22,7 +22,7 @@ An unrecognised command does not fall through to a server the caller did not ask
|
|
|
22
22
|
pmcp status [--config <file>] [--json]
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
Show enabled features and their TOML or auto source, projection drift, live sessions, pause, leases, unseen broadcasts, worktree ahead/behind counts, shared MCP credential presence, logged errors from the last hour, and, with a [`[budget]`](project-configuration.md#budget) table, each limit beside what it measured. Reads do not acknowledge broadcasts, refresh credentials, prune logs, fetch or move git refs. Projection uses the same check as `project --check`. Exit 0, or 4 when projection
|
|
25
|
+
Show enabled features and their TOML or auto source, projection drift, live sessions, pause, leases, unseen broadcasts, worktree ahead/behind counts, shared MCP credential presence, logged errors from the last hour, and, with a [`[budget]`](project-configuration.md#budget) table, each limit beside what it measured, and how many are over. Reads do not acknowledge broadcasts, refresh credentials, prune logs, fetch or move git refs. Projection uses the same check as `project --check`. Exit 0, or 4 when projection drift exists; 2 when there is no `pmcp.toml`. A limit over its number is reported and never changes the exit code: `project --check` is the one that judges it. Linked worktrees ahead of or behind the mainline are live state in a multi-session workspace: the summary and `data.lagging` count them, and they never change the exit code. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stdout; JSON retains the full details.
|
|
26
26
|
|
|
27
27
|
## init
|
|
28
28
|
|
|
@@ -185,7 +185,7 @@ pmcp sessions send --to <selector>... [--subject <s>] [--wake] <body>
|
|
|
185
185
|
pmcp sessions inbox
|
|
186
186
|
```
|
|
187
187
|
|
|
188
|
-
Coordinate the live agent sessions of this repository and its worktrees, through the state the hooks keep for [`[sessions]`](project-configuration.md#sessions). `status` (the default verb) prints each live session, the pause, current broadcasts, held leases and undelivered edits in a shared checkout to standard output, or `no live sessions`. `pause` refuses edits and mutating commands in every other session until `resume`; `broadcast` delivers its text once to each session as context, and `unbroadcast` withdraws it. `--by` names the sender, whose own session is exempt; it
|
|
188
|
+
Coordinate the live agent sessions of this repository and its worktrees, through the state the hooks keep for [`[sessions]`](project-configuration.md#sessions). `status` (the default verb) prints each live session, the pause, current broadcasts, held leases and undelivered edits in a shared checkout to standard output, or `no live sessions`. `pause` refuses edits and mutating commands in every other session until `resume`; `broadcast` delivers its text once to each session as context, and `unbroadcast` withdraws it. `--by` names the sender, whose own session is exempt; without it the sender is the agent session the command runs in, or `operator` from the operator's terminal (`--by operator` is refused anywhere else). `pause` and `resume` are operator verbs: inside an agent session they exit 1 with a line naming who to ask (see [the operator](project-configuration.md#the-operator)). `sweep` removes records whose process is gone. `send` addresses `all`, `session:<id>`, `alias:<name>`, `role:<name>` or `worktree:<path>` through `[sessions.mailbox]`; `inbox` lists your messages. [Run several agents](sessions.md) walks through them. Exit 0, or 2 for an unknown verb, missing text or no `pmcp.toml`.
|
|
189
189
|
|
|
190
190
|
## logs
|
|
191
191
|
|
|
@@ -214,7 +214,7 @@ The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs
|
|
|
214
214
|
- `worktree create <alias>` makes a linked worktree under `[git.worktrees] root` on a new branch from the upstream (or `--base`), links the configured files from the main checkout, runs `bootstrap`, and prints the path.
|
|
215
215
|
- `worktree list` prints alias, branch, behind/ahead and path for the main checkout and each linked worktree.
|
|
216
216
|
- `worktree sync` moves the current worktree onto the mainline when that loses nothing; exit 1 when it is held back.
|
|
217
|
-
- `deliver` fetches, replays the named commits (default: the ones the upstream lacks) onto the mainline, runs the gate in its own tree under a lock, and pushes; it replays again if the mainline moved. A delivery that touches a leased path holds that lease until it has pushed and installed, and it refuses during a pause unless `--during-pause` or `during_pause = "allow"`. `--no-push` replays and runs the gate command, then stops: it takes no lease and pushes, syncs and notifies nothing, and it refuses `gate = "pre-push"`, where the push is the gate. Deliver never takes the [host lease](project-configuration.md#host-lease): replay, gate tree, hooks and push run without it, and the gate wraps only its test stages in `pmcp heavy --profile gate`. Exit 0 delivered, gated with `--no-push`, or nothing to deliver; 1 refused, fetch failed, gate failed or attempts exhausted; 2 `--no-push` with the pre-push gate; 75 the gate command exited 75 because a test stage never got the host lease ("gate not run: host busy"), so nothing was pushed.
|
|
217
|
+
- `deliver` fetches, replays the named commits (default: the ones the upstream lacks) onto the mainline, runs the gate in its own tree under a lock, and pushes; it replays again if the mainline moved. A delivery that touches a leased path holds that lease until it has pushed and installed, and it refuses during a pause unless `--during-pause` (an operator verb, refused inside an agent session) or `during_pause = "allow"`. `--no-push` replays and runs the gate command, then stops: it takes no lease and pushes, syncs and notifies nothing, and it refuses `gate = "pre-push"`, where the push is the gate. Deliver never takes the [host lease](project-configuration.md#host-lease): replay, gate tree, hooks and push run without it, and the gate wraps only its test stages in `pmcp heavy --profile gate`. Exit 0 delivered, gated with `--no-push`, or nothing to deliver; 1 refused, fetch failed, gate failed or attempts exhausted; 2 `--no-push` with the pre-push gate; 75 the gate command exited 75 because a test stage never got the host lease ("gate not run: host busy"), so nothing was pushed.
|
|
218
218
|
- `sync` moves the main checkout to the mainline, installs when a listed file changed, and follows clean submodule pins. Exit 0 moved or already equal, 1 when local work would be lost or the fetch failed, 2 when blocked (undelivered edits, another branch, a git operation in progress). Run in a desk (a linked worktree matching `[git.worktrees] desks`), it brings the desk up to date the same way without rebasing: exit 0 moved or current, 1 held (an unlanded commit, uncommitted tracked edits, a pause, another session's lease, a git operation in progress), with the reason. In any other linked worktree it exits 2.
|
|
219
219
|
- `affected --base <ref>` prints the workspace members the delta from `<ref>` to `--head` (default `HEAD`) touches, with their consumers when [`[git.affected]`](git-workflow.md#affected-members) `consumers` is on (`--tests-only` leaves them out), or `ALL`; unmapped files are named on stderr. It reads git objects at `--head` (each submodule at its pin), never the working tree. It needs only `[git.affected]`, not an enabled workflow. Exit 0 with an answer, `ALL` included when the base does not resolve, equals the head or a manifest does not parse; 2 for a missing `--base` or an invalid table. `--json` prints the [envelope](#json-output) `pmcp.git.affected.v1`, whose `data` has `all`, `reason`, `base`, `head`, `changed`, `members`, `unmapped` and `selected` (the printed list, or `"ALL"`).
|
|
220
220
|
|
|
@@ -227,7 +227,7 @@ pmcp heavy --profile gate --weight 2 -- npm run typecheck
|
|
|
227
227
|
pmcp heavy --profile hook -- npm run lint:staged
|
|
228
228
|
pmcp heavy --now --reason "prod is down" -- npm run deploy
|
|
229
229
|
pmcp heavy status [--json]
|
|
230
|
-
pmcp heavy stats [--json]
|
|
230
|
+
pmcp heavy stats [--top <n>] [--json]
|
|
231
231
|
ticket=$(pmcp heavy submit --lane bulk -- npm run build:all)
|
|
232
232
|
pmcp heavy result "$ticket"
|
|
233
233
|
pmcp heavy wait "$ticket" --timeout 1800
|
|
@@ -238,7 +238,7 @@ pmcp heavy priority <id> gate --reason "blocks a land"
|
|
|
238
238
|
pmcp heavy priority <id> +2 --reason "the session waits on it"
|
|
239
239
|
```
|
|
240
240
|
|
|
241
|
-
Run a heavy command within the host-wide budget of [`[host.lease]`](project-configuration.md#host-lease), across every session and worktree on the host. A job starts once its lane has a free slot, its weight fits what the running jobs leave of the budget, and the host is under `max_load` and `max_io` (or, past `load_grace` and with nothing leased running, under `hard_factor` times them). Waiting jobs start by lane (gate, hook, interactive, bulk), oldest first within a lane, with a line on standard error every `heartbeat`; `--lane` and `--weight` override the profile and `[host.lease] commands`. The command runs with the lease marker set, so a nested `pmcp heavy` runs at once. Everything after `--` is the command, options included. `status` prints the lock, the host readings, when the host was last settled, the holder record, each waiter with its lane, weight, position and a rough wait estimate from the log's run times, the lanes' use and the running weight against the budget, each running job against `hold_warn` and `hold_max`, the IO average the check reads, how many jobs started on `load_grace` in the last day, and the busiest processes outside the lease. With the lease disabled (`enabled = false`), the command runs at once. With `PMCP_HEAVY_DISABLE=<reason>` set, an ordinary command runs at once and its usage record keeps the reason, but a bulk job (`--lane bulk`, or a `commands` entry with `lane = "bulk"`) still queues in the bulk lane, with a line saying the skip was not honoured, unless `[host.lease] skip_always` lists the reason. `--now --reason <text>` (or `PMCP_HEAVY_NOW=<reason>`) is the emergency bypass: it runs at once, logged and shown in status, and still counts its weight. Where the io controller reaches the user's scopes, each job runs in its own scope with its lane's `io.weight`. `submit` queues the command and returns a ticket at once, so the caller keeps working: a detached runner (its own session, so it outlives the caller) waits and runs it under the same rules, its output in the ticket's log and its exit code and usage record in the ticket's result. `result <
|
|
241
|
+
Run a heavy command within the host-wide budget of [`[host.lease]`](project-configuration.md#host-lease), across every session and worktree on the host. A job starts once its lane has a free slot, its weight fits what the running jobs leave of the budget, and the host is under `max_load` and `max_io` (or, past `load_grace` and with nothing leased running, under `hard_factor` times them). Waiting jobs start by lane (gate, hook, interactive, bulk), oldest first within a lane, with a line on standard error every `heartbeat`; `--lane` and `--weight` override the profile and `[host.lease] commands`. The command runs with the lease marker set, so a nested `pmcp heavy` runs at once. Everything after `--` is the command, options included. `status` prints the lock, the host readings, when the host was last settled, the holder record, each waiter with its lane, weight, position and a rough wait estimate from the log's run times, the lanes' use and the running weight against the budget, each running job against `hold_warn` and `hold_max`, the IO average the check reads, how many jobs started on `load_grace` in the last day, and the busiest processes outside the lease. With the lease disabled (`enabled = false`), the command runs at once. With `PMCP_HEAVY_DISABLE=<reason>` set to an allowed reason (`nested` inside a leased job, `operator` for the operator, or one listed in `[host.lease] skip_reasons` or `skip_always`), an ordinary command runs at once and its usage record keeps the reason; any other reason runs nothing and exits 2 with the allowed list, but a bulk job (`--lane bulk`, or a `commands` entry with `lane = "bulk"`) still queues in the bulk lane, with a line saying the skip was not honoured, unless `[host.lease] skip_always` lists the reason. `--now --reason <text>` (or `PMCP_HEAVY_NOW=<reason>`) is the operator's emergency bypass: it runs at once, logged and shown in status, and still counts its weight; from an agent session it exits 1 and names who to ask, as `promote --now` and `cancel --force` on another session's job do. Where the io controller reaches the user's scopes, each job runs in its own scope with its lane's `io.weight`. `submit` queues the command and returns a ticket at once, so the caller keeps working: a detached runner (its own session, so it outlives the caller) waits and runs it under the same rules, its output in the ticket's log and its exit code and usage record in the ticket's result. Every job keeps its stdout and stderr in its ticket, bounded by `[host.lease] job_log_bytes` (default 4 MiB, rotated once to `log.1`, so a job keeps at most twice that): a submitted job's runner writes them there, and a blocking run opens a ticket of its own and copies them there as they reach the terminal, so the command sees pipes instead of a terminal; a blocking run that fails ends with a line naming its id. `job_log_bytes = 0`, or a disabled lease, keeps nothing for blocking runs, which then write to the terminal directly. `result <id>` reads the state (queued with its position, running, done, or lost when the runner died), `--json` as data, and `result <id> --log` prints the kept output instead, the rotated part first; `--tail <n>` keeps its last n lines. `wait <ticket>` blocks until it is done, prints the log's tail and exits with the job's code (75 at `--timeout`); `cancel <ticket>` stops a queued job and, with `--force`, a running one. Tickets live under `<dir>/tickets/` and finished ones are removed after a week. Every waiting or running job has an id (a ticket's, or one made for a blocking run), shown by `status` and `queue`: `queue` lists the waiters with id, lane, position, waited and estimated time, weight, pid, session and label; `promote <id> --now --reason` starts a waiter at once as a bypass; `priority <id> <lane|+N|-N> --reason` moves it to another lane's end or N places within its lane; `cancel <id>` takes a waiter out of the queue (its run exits 130) and, with `--force`, stops a running job. The waiting process reads the change on its next poll; each change is made under the admission lock and logged as a `control` line with the uid, the session and the reason, and a waiter whose process died is removed instead of changed. `stats` lists each command signature's recorded runs with the median and 90th percentile of wall time, CPU time, peak RSS and IO and how many skipped the lease, after a line with the share of all runs that skipped it and lines counting the skip reasons and the refused ones, the most-run first; `--top <n>` keeps the first n, `--json` as data. Exit: the command's own code; 75 when nothing ran within `max_wait`, with the reason (the queue, the session's cap, a shell wrapper's hold, a host past `hard_factor`); 2 for a missing `--`, an unknown profile or lane, a bad weight, `--now` without a reason, or a skip reason that is not allowed; 1 for an operator verb outside the operator's terminal.
|
|
242
242
|
|
|
243
243
|
## wait
|
|
244
244
|
|
|
@@ -250,6 +250,15 @@ pmcp wait --until no-process:"vitest run"
|
|
|
250
250
|
|
|
251
251
|
Sleep until every condition holds: `--pid` until that process has exited, `--until exists:<path>`, `gone:<path>`, `load-below:<n>` (1-minute load average) or `no-process:<text>` (no command line contains the text). It never matches itself or the shells that started it, which a loop around `pgrep -f` does, and it sleeps between checks (`--interval`, default 5 s) instead of spinning. Exit 0 once met, 75 after `--timeout` (default 3600 s), 2 for an unreadable condition.
|
|
252
252
|
|
|
253
|
+
## owners
|
|
254
|
+
|
|
255
|
+
```sh
|
|
256
|
+
pmcp owners services/auth/src/login.ts
|
|
257
|
+
pmcp owners docs --json
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Name who looks after each path, from [`[[owners]]`](project-configuration.md#owners): one line per matching entry, `<path> belongs to <owner>: <note>`, or `<path>: no owner`. Paths are taken from the working directory and matched relative to the directory holding `pmcp.toml`. `--json` gives `paths`, each with `path` and `owners` (owner, note, mode). It only reads. Exit 0, or 2 without a path or a `pmcp.toml`, or with an invalid `[[owners]]`.
|
|
261
|
+
|
|
253
262
|
## completion
|
|
254
263
|
|
|
255
264
|
```sh
|
|
@@ -374,7 +383,9 @@ Both show the project and lockfile changes and stop: `--yes` (`-y`) approves the
|
|
|
374
383
|
|
|
375
384
|
With `TERM=dumb`, or a locale that is not UTF-8, the few typographic characters in messages (an em dash, a middle dot) print as ASCII. Long operations such as `index` report progress on standard error: one rewritten line on a terminal, a plain `k/N` line every tenth of the work otherwise.
|
|
376
385
|
|
|
377
|
-
Help and tables fit the terminal: `COLUMNS` when set, else the terminal width, kept between 40 and 120 columns; long descriptions wrap under their column, and a name too wide for its column puts its description on the next lines. Off a terminal, help wraps at 80 columns and a table prints one plain record per line (`name description`, no padding), so `grep` and `cut` see whole records.
|
|
386
|
+
Help and tables fit the terminal: `COLUMNS` when set, else the terminal width, kept between 40 and 120 columns; long descriptions wrap under their column, and a name too wide for its column puts its description on the next lines. Status records (`status`, `sessions status`, `heavy status`, `queue` and `stats`, `git worktree list`) fit the same width on a terminal: a long record wraps under a hanging indent, and a word wider than the line is cut with an ellipsis. Off a terminal, help wraps at 80 columns and a table or status listing prints one plain record per line (`name description`, no padding), so `grep` and `cut` see whole records.
|
|
387
|
+
|
|
388
|
+
A reader that closes the pipe early, as `pmcp list | head -1` or `pmcp heavy stats | head` does, ends the command quietly with exit 0 instead of a write error.
|
|
378
389
|
|
|
379
390
|
Options are parsed against the command's own list, so an unknown flag is an error rather than a silently ignored typo. Giving a non-repeatable option twice, or leaving off a value it needs, is the same error.
|
|
380
391
|
|
|
@@ -390,7 +401,7 @@ Every command uses one table, so a script can branch on the code alone:
|
|
|
390
401
|
| `1` | it ran and failed, or found a problem | no skills under those roots, a partial index, no SQLite to store vectors in, `validate` errors, a `doctor` FAIL, a declined or failed install, a refused delivery, a failed gate or fetch |
|
|
391
402
|
| `2` | usage error: it could not run as asked | an unknown command, subcommand or option, a missing value, no `pmcp.toml` or a missing `[git]` table, `git sync` in the wrong checkout |
|
|
392
403
|
| `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
|
|
393
|
-
| `4` | a check ran and found differences | `status` drift
|
|
404
|
+
| `4` | a check ran and found differences | `status` projection drift, `project --check` drift or an exceeded budget, stale or undeclared outputs, a `hooks test --fixtures` or `--smoke` finding |
|
|
394
405
|
| `75` | the host stayed busy, so nothing ran; retry later | `heavy` past `max_wait`, a `git deliver` gate whose test stage never got the host lease, `wait` past `--timeout` |
|
|
395
406
|
|
|
396
407
|
1 says the project is not what you expected; 2 says the command line or the setup is wrong, so retrying the same command will not help; 3 says the machine is missing something optional and the server still works without it; 4 says a check did its job and found something to fix, usually with `pmcp project`. A command that runs another command, such as `heavy`, exits with that command's code. Before 0.23.0, drift exited 2 like a usage error; see [Upgrading](upgrading.md).
|
package/docs/git-workflow.md
CHANGED
|
@@ -61,10 +61,16 @@ session's lease, or a git operation in progress holds the desk where it is
|
|
|
61
61
|
|
|
62
62
|
Both kinds check out a submodule the move adds, such as a directory split into its
|
|
63
63
|
own repository. When that path still holds files from before and git ignores all of
|
|
64
|
-
them (install or build output), they are moved
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
line names
|
|
64
|
+
them (install or build output), they are moved out of the checkout to
|
|
65
|
+
`$XDG_STATE_HOME/pmcp/displaced/<project id>/<UTC time>/<path>` (`~/.local/state`
|
|
66
|
+
without `XDG_STATE_HOME`; the project id is the one the state directory uses, shared
|
|
67
|
+
by every worktree of the repository), never deleted, and the line names that
|
|
68
|
+
directory and says to run the install again. Nothing under the checkout or its git
|
|
69
|
+
dir holds them, so a scan of the tree, `git clean` or a new worktree never meets
|
|
70
|
+
them; remove a directory there once the install has run. A file git does not ignore
|
|
71
|
+
leaves the submodule unchecked, and the line names the path. Releases up to 0.25.0
|
|
72
|
+
kept them under the git dir in `pmcp-displaced/`; pmcp no longer writes there, and
|
|
73
|
+
what is there can be moved or removed by hand.
|
|
68
74
|
|
|
69
75
|
`[git.mainline.gate]`: `command` (argv; no gate when missing), `tree` (the
|
|
70
76
|
gate's worktree, default `<state dir>/gate/tree`; a relative path is relative to
|
|
@@ -124,7 +130,9 @@ from the mainline or a branch tracking it, `--all`, `--mirror`, wildcard
|
|
|
124
130
|
refspecs, and a push to a URL. A dry run, another branch, a tag, another
|
|
125
131
|
remote and a submodule's own push pass), `during_pause` (`"refuse"` default or `"allow"`),
|
|
126
132
|
`lease_wait_seconds` (default `3600`), `notify` (argv run after a
|
|
127
|
-
delivery), `gate` and `push_env`.
|
|
133
|
+
delivery), `gate` and `push_env`. When the project declares
|
|
134
|
+
[`[[owners]]`](project-configuration.md#owners), delivery first prints one line
|
|
135
|
+
for each owner whose paths the commits touch; it never stops the delivery.
|
|
128
136
|
|
|
129
137
|
A commit is already on the mainline when `git cherry` finds the same patch there,
|
|
130
138
|
or when it only moves submodule pins, each to a commit that the mainline's pin for
|
|
@@ -244,6 +252,33 @@ trailing `*` matches a prefix) every member builds with: a change to one selects
|
|
|
244
252
|
root field outside the dependency fields and `inert_root_fields` (default `scripts`,
|
|
245
253
|
`description`, `version`) or a lockfile that does not parse.
|
|
246
254
|
|
|
255
|
+
A change to the root `workspaces` globs does not select `ALL` by itself: the members are listed at
|
|
256
|
+
both revisions, the members the globs added are selected, the ones they dropped are reported
|
|
257
|
+
in `--json` as `workspaceMembers` (`added`, `removed`; a dropped member is no longer one, so it
|
|
258
|
+
is not run), and `on_member_change` is selected when either list is not empty. A `workspaces`
|
|
259
|
+
value that is not a list of globs (or `{packages}` holding one) at either revision, or another
|
|
260
|
+
non-inert root field changing with it, still selects `ALL`. Listing `workspaces` in
|
|
261
|
+
`inert_root_fields` ignores the field entirely, as before, with no member comparison.
|
|
262
|
+
|
|
263
|
+
A dependency of the root `package.json` itself (a CLI the root's scripts or git hooks run)
|
|
264
|
+
belongs to no member, so without more the lockfile adapter selects only the members whose own
|
|
265
|
+
resolution of it moved. `[git.affected.root_dependencies]` (it needs `[git.affected.lockfile]`)
|
|
266
|
+
names the members that use each one: a key is a package name, or a prefix ending in `*`, and
|
|
267
|
+
its value the member directories, an empty list meaning no member is affected.
|
|
268
|
+
|
|
269
|
+
```toml
|
|
270
|
+
[git.affected.root_dependencies]
|
|
271
|
+
"@modootoday/pmcp" = ["tools/husky-hook-runner", "tools/pmcp-verify"]
|
|
272
|
+
"eslint-*" = []
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Once the table is declared, every root dependency whose range changed, or whose resolved
|
|
276
|
+
package (or anything below it) moved in the lockfile, must be mapped: the mapped members are
|
|
277
|
+
selected beside the members whose resolution moved (and their consumers with
|
|
278
|
+
`consumers = true`), and one changed root dependency the table does not map selects `ALL`,
|
|
279
|
+
naming it. `--json` lists the mappings that applied in `rootDependencies`
|
|
280
|
+
(`name`, the `key` that matched, `members`). A name in `toolchain` still selects `ALL` first.
|
|
281
|
+
|
|
247
282
|
Consumer edges are a member's `dependencies`, `peerDependencies` and `optionalDependencies`, the
|
|
248
283
|
`devDependencies` its production source under `src/` imports (all of them when its
|
|
249
284
|
`tsconfig.json` `exclude` names no tests), the member whose tsconfig preset it extends, and
|
package/docs/glossary.md
CHANGED
|
@@ -22,7 +22,7 @@ The words pmcp's documentation and messages use, each with the page that owns it
|
|
|
22
22
|
| broadcast | Text every running session receives once, as context. |
|
|
23
23
|
| sessions mailbox | Addressed messages between the sessions of one repository, `pmcp sessions send`. [Run several agents](sessions.md) |
|
|
24
24
|
| local mailbox | Messages between actors that hold their own credentials, `pmcp mailbox`, across projects and hosts. [Local mailbox](mailbox.md) |
|
|
25
|
-
| `operator` |
|
|
25
|
+
| `operator` | You, recognised by `[sessions.operator]`: your own terminal, or a token file agents cannot read. Only the operator runs the operator verbs or signs as `operator` (`--by`). The docs say "you". |
|
|
26
26
|
| runtime id | How each table names a native runtime; the ids differ between tables. [Compatibility](compatibility.md#native-runtimes) |
|
|
27
27
|
| main and worker | In a terminal workspace or harness group, the session you mainly talk to and the ones it delegates to. [Terminal workspace](terminal-workspace.md) |
|
|
28
28
|
| harness group | The sessions one pmcp-pty daemon hosts for `pmcp tui` or `pmcp harness`, with a budget and a generation that changes when the group is replaced. [Native terminal control](terminal-harness.md) |
|
package/docs/hooks.md
CHANGED
|
@@ -70,21 +70,26 @@ nothing, no verdict and no context, even when the guard fails; use it to run a g
|
|
|
70
70
|
beside a hook it will replace and compare. Every guard writes one debug log line per
|
|
71
71
|
call: `policy`, `session`, `verdict` (what the call got) and, under `data`, `raw`
|
|
72
72
|
(what the guard found: `allow`, `ask` or `deny`), `mode`, `tool` (the tool kind) and
|
|
73
|
-
`native` (the runtime's tool name), never the command, the reason or the prompt.
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
| `[hooks.guards.shell.
|
|
81
|
-
| `[hooks.guards.shell.
|
|
82
|
-
| `[hooks.guards.shell.
|
|
83
|
-
| `[hooks.guards.shell.
|
|
84
|
-
| `[hooks.guards.
|
|
85
|
-
| `[hooks.guards.
|
|
86
|
-
| `[hooks.guards.
|
|
87
|
-
| `[hooks.guards.
|
|
73
|
+
`native` (the runtime's tool name), never the command, the reason or the prompt. A call
|
|
74
|
+
an `observe` or `warn` guard found something in but let through is written at info
|
|
75
|
+
instead, so `pmcp hooks report --switch-check <guard>` counts a week of observe at the
|
|
76
|
+
default log level.
|
|
77
|
+
|
|
78
|
+
| Table | Default mode | Modes | Refuses |
|
|
79
|
+
| ------------------------------------------ | ------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
80
|
+
| `[hooks.guards.shell.in_place_edit]` | deny | deny, ask, warn, observe, off | `sed -i`, `perl -i`, `awk -i inplace`: edits without a diff. |
|
|
81
|
+
| `[hooks.guards.shell.heredoc]` | deny | deny, ask, warn, observe, off | Heredocs and here-strings, whose body the shell expands silently. |
|
|
82
|
+
| `[hooks.guards.shell.stdin_interpreter]` | ask | deny, ask, warn, observe, off | An interpreter reading its program from stdin (`python3 -`, `cat x.py \| python3`). |
|
|
83
|
+
| `[hooks.guards.shell.compose_teardown]` | deny | deny, ask, warn, observe, off | `docker compose down`, and `stop`, `rm` or `kill` with no service named: they hit every service. |
|
|
84
|
+
| `[hooks.guards.shell.secret_exfiltration]` | graded | deny, ask, warn, observe, off, graded | Reading a credential asks; sending one over the network, or changing a live one, denies. |
|
|
85
|
+
| `[hooks.guards.shell.host_approval]` | deny | deny, ask, warn, observe, off | `host approve`, and commands or edits touching the host approvals directory. On by itself when `[host]` is declared. |
|
|
86
|
+
| `[hooks.guards.shell.runaway_regex]` | deny | deny, ask, warn, observe, off | A grep pattern that can hold a core for minutes: a repetition count over the threshold (`\{0,2500\}`, `{0,2500}` with `-E` or `-P`), or a `-P` group quantified inside a quantifier such as `(a+)+`. ripgrep (`rg`) matches in linear time and is never refused. |
|
|
87
|
+
| `[hooks.guards.shell.self_matching_wait]` | observe | deny, ask, warn, observe, off | A `while`, `until` or `for` loop that polls with `pgrep -f`, `pkill -f`, `pidwait -f` or `ps \| grep` (also inside `$( )` or `bash -c`): the pattern matches the shell running the loop, whose command line holds it, so the wait may never end. `ps -p`, `ps -C` and `pgrep` without `-f` pass. The reason points to `pmcp wait --pid`, `pmcp wait --until no-process:<text>` and `pmcp heavy wait <ticket>`. Starts in observe; set `mode = "deny"` once a week of hits is measured. |
|
|
88
|
+
| `[hooks.guards.git.push_without_verify]` | deny | deny, ask, warn, observe, off | `git push --no-verify`. |
|
|
89
|
+
| `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, observe, off | Forcing a branch that is checked out in another working tree. |
|
|
90
|
+
| `[hooks.guards.git.gate_bypass_env]` | deny | deny, ask, warn, observe, off | Setting a named gate-bypass variable where it takes effect, and optionally `--no-verify` on any git command. |
|
|
91
|
+
| `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, observe, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
|
|
92
|
+
| `[hooks.guards.pmcp.operator_verbs]` | deny | deny, ask, warn, observe, off | The operator verbs: `pmcp sessions pause` and `resume`, `pmcp heavy --now` and `promote --now`, `pmcp heavy cancel --force`, `pmcp git deliver --during-pause`, and setting `PMCP_HEAVY_NOW`, `PMCP_OPERATOR_TOKEN` or the lease skip `PMCP_HEAVY_DISABLE=operator`. On by itself with any session feature. |
|
|
88
93
|
|
|
89
94
|
Options:
|
|
90
95
|
|
|
@@ -210,6 +215,60 @@ A command that needs to end a session's turn with a check of its own (tests, a
|
|
|
210
215
|
linter, a generated-file check) is a custom guard with `on = "stop"` and
|
|
211
216
|
`mode = "warn"`.
|
|
212
217
|
|
|
218
|
+
## `[[hooks.guards.external]]`
|
|
219
|
+
|
|
220
|
+
A checker the project already has (a document linter, a size or schema check)
|
|
221
|
+
judges each file an agent edits whose path a glob matches, and its own JSON
|
|
222
|
+
answer becomes the guard's verdict. Unlike a custom guard it needs no adapter
|
|
223
|
+
script and speaks no pmcp protocol: pmcp passes the path (and, with `stdin`,
|
|
224
|
+
the new text) and reads the checker's exit code and `items`. It runs in the hook
|
|
225
|
+
bundle for every `[hooks] targets` runtime.
|
|
226
|
+
|
|
227
|
+
| Key | Type | Default | Meaning |
|
|
228
|
+
| ------------ | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
229
|
+
| `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique among external guards; the guard id is `external.<name>`. |
|
|
230
|
+
| `paths` | glob list | required | Project-relative globs (`*` within a segment, `**` across segments); an edited file that matches one is checked. Other edits do not run it. |
|
|
231
|
+
| `command` | argv list | required | The checker. Each `{path}` is replaced by the edited file's project-relative path; with no `{path}`, the path is added as the last argument. |
|
|
232
|
+
| `timeout_ms` | integer | `15000` | 100 to 60000, for all the files of one edit together. |
|
|
233
|
+
| `mode` | string | `"observe"` | `deny`, `warn`, `observe` or `off`. A new external guard starts in `observe`; move it to `deny` once its hits are measured. |
|
|
234
|
+
| `stdin` | boolean | `false` | Send the file's new text on stdin, so the edit is checked before it is written (see below). |
|
|
235
|
+
| `on_error` | string | `"allow"` | What a checker that cannot answer means in `deny` mode: `allow` lets the edit through with a log line, `deny` refuses it. |
|
|
236
|
+
|
|
237
|
+
When it runs. With `stdin = true`, before the write, when the runtime's payload
|
|
238
|
+
says what the edit writes: the whole new text, or replacements pmcp applies to
|
|
239
|
+
the file as it stands (Claude Code's `Write`, `Edit` and `MultiEdit`). A `deny`
|
|
240
|
+
then refuses the edit before anything is written. When the payload cannot say
|
|
241
|
+
(another runtime's patch, a replacement whose old text is not in the file), the
|
|
242
|
+
check runs after the write instead, with the file's text from disk on stdin, and
|
|
243
|
+
a `deny` reaches the agent as feedback on the edit. Without `stdin`, it always
|
|
244
|
+
runs after the write and the checker reads the file itself.
|
|
245
|
+
|
|
246
|
+
The command runs in the project root with only `PATH`, `HOME` and `LANG`, once
|
|
247
|
+
per matched file. Exit 0 passes. Exit 1 is a finding, and stdout must then be a
|
|
248
|
+
JSON object with a non-empty `items` array: each item a string, or an object with
|
|
249
|
+
`message` and optionally `path`, `line` and `rule`, shown as
|
|
250
|
+
`path:line: rule: message`, up to 20 lines. Anything else (exit 2 or another
|
|
251
|
+
code, exit 1 without such JSON, a checker that cannot start or runs past
|
|
252
|
+
`timeout_ms`) is a checker error: logged at warn, said to a `warn` session once
|
|
253
|
+
per session, and in `deny` mode refused only with `on_error = "deny"`.
|
|
254
|
+
|
|
255
|
+
`deny` refuses a finding, `warn` gives it to the agent as context, and `observe`
|
|
256
|
+
logs it for `pmcp hooks report`. The numbers a size checker judges can live in
|
|
257
|
+
[`[budgets]`](project-configuration.md#budgets), so a project keeps one place for
|
|
258
|
+
them:
|
|
259
|
+
|
|
260
|
+
```toml
|
|
261
|
+
[budgets]
|
|
262
|
+
"**/AGENTS.md" = { bytes = 4096 }
|
|
263
|
+
|
|
264
|
+
[[hooks.guards.external]]
|
|
265
|
+
name = "doc-budget"
|
|
266
|
+
paths = ["**/AGENTS.md", ".agents/rules/*.md"]
|
|
267
|
+
command = ["node_modules/.bin/doc-check", "--stdin-path", "{path}", "--json"]
|
|
268
|
+
stdin = true
|
|
269
|
+
mode = "warn"
|
|
270
|
+
```
|
|
271
|
+
|
|
213
272
|
## `[hooks.report]`
|
|
214
273
|
|
|
215
274
|
Read by [`pmcp hooks report`](commands.md#hooks) alone; it changes nothing in the
|
|
@@ -330,7 +389,7 @@ table for your project, with Codex trust.
|
|
|
330
389
|
| `[git.shared_checkout]`, `[git.worktrees.sync]`, `[git.mainline.deliver]` | measured | measured |
|
|
331
390
|
| heredoc, compose_teardown, push_without_verify, forced_branch_move, gate_bypass_env, stage_all | measured | measured |
|
|
332
391
|
| in_place_edit, stdin_interpreter, secret_exfiltration (ask) | ask not measured | ask lowered by `ask_fallback` |
|
|
333
|
-
| host_approval
|
|
392
|
+
| host_approval, operator_verbs | works; not live-measured | works; not live-measured |
|
|
334
393
|
| `[hooks.checks.after_edit]` | measured | measured |
|
|
335
394
|
| `[hooks.checks.on_stop]` | measured, in the same turn | at the next prompt |
|
|
336
395
|
| `[[hooks.guards.custom]]` | not measured | not measured |
|