@modootoday/pmcp 0.24.0 → 0.25.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.
Files changed (105) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +1 -1
  4. package/.mcp.json +1 -1
  5. package/dist/{affected-D6FRJPPI.js → affected-IPFJM2KD.js} +484 -140
  6. package/dist/{apply-6JVJ7FDZ.js → apply-6XLLYLJT.js} +15 -14
  7. package/dist/{broadcast-VKZY7WSD.js → broadcast-34CEG2NQ.js} +5 -2
  8. package/dist/{chunk-B3OZ4GGO.js → chunk-23PE3HZB.js} +16 -1
  9. package/dist/{chunk-42SO7KYX.js → chunk-2GD7PQ7J.js} +2 -2
  10. package/dist/{chunk-7A6QIROT.js → chunk-2TXVOHRS.js} +3 -3
  11. package/dist/{chunk-QR4GXET7.js → chunk-3P6Y2BAO.js} +3 -3
  12. package/dist/{chunk-5QBOGEVE.js → chunk-5MUD7FHP.js} +2 -2
  13. package/dist/{chunk-2GZKA33O.js → chunk-A4P3IIPE.js} +2 -2
  14. package/dist/{chunk-UFWW4H6V.js → chunk-BG6TONJO.js} +2 -2
  15. package/dist/{chunk-HES44LTA.js → chunk-C3KRMTIZ.js} +28 -4
  16. package/dist/{chunk-QY2P54Z2.js → chunk-DITIXBFB.js} +61 -8
  17. package/dist/{chunk-6UGHVU5B.js → chunk-DWHM5BAY.js} +2 -2
  18. package/dist/{chunk-TIH7JFPJ.js → chunk-EC5QLEZD.js} +2 -2
  19. package/dist/{chunk-RZYZILU4.js → chunk-EWYLWBKS.js} +2 -2
  20. package/dist/{chunk-LI3BII4F.js → chunk-ISWR2XIU.js} +2 -2
  21. package/dist/{chunk-WNP2BXR7.js → chunk-LZVHFPN6.js} +5 -5
  22. package/dist/{chunk-K6ATERWS.js → chunk-MBHI2TKQ.js} +4 -4
  23. package/dist/{chunk-43MXRTKH.js → chunk-NAHAESFV.js} +9 -4
  24. package/dist/chunk-NQCAKDRY.js +156 -0
  25. package/dist/chunk-OIKT4SYO.js +42 -0
  26. package/dist/{chunk-D2MHB5EF.js → chunk-PECS47OL.js} +3 -3
  27. package/dist/{chunk-62BC3K4Z.js → chunk-PGZZI42O.js} +2 -2
  28. package/dist/{chunk-S6G7YWNE.js → chunk-QYHM6554.js} +2 -2
  29. package/dist/{chunk-2W2F5BWF.js → chunk-RF6RDJYH.js} +16 -16
  30. package/dist/{chunk-SUDG7B6S.js → chunk-SDFJJJB5.js} +2 -2
  31. package/dist/chunk-SMBU3QLE.js +7 -0
  32. package/dist/{chunk-644GNYMB.js → chunk-SRSKCFFS.js} +3 -3
  33. package/dist/{chunk-LB2WXBPA.js → chunk-SSQ6EWNA.js} +5 -5
  34. package/dist/{chunk-56VBB3H7.js → chunk-TJW4DP26.js} +2 -2
  35. package/dist/{chunk-25M2YWBH.js → chunk-TOR6SKRB.js} +146 -63
  36. package/dist/{chunk-ISGHJHVH.js → chunk-UQHJUTDW.js} +2 -2
  37. package/dist/{chunk-M6X6HVQK.js → chunk-VQBXWMLT.js} +2 -2
  38. package/dist/{chunk-UYBWUOLR.js → chunk-VYQJPT27.js} +4 -4
  39. package/dist/{cli-GFDT4YXM.js → cli-5G2OYTIL.js} +9 -9
  40. package/dist/{cli-WWNTQJPV.js → cli-QDQYUHAP.js} +9 -9
  41. package/dist/cli.js +38 -5
  42. package/dist/{completion-I63UIDZ7.js → completion-3GVNPLZY.js} +4 -4
  43. package/dist/{diagnostics-RUJZBPNZ.js → diagnostics-2W7QDQNG.js} +6 -6
  44. package/dist/{doctor-CLUFTEFO.js → doctor-3TDO5LJ5.js} +17 -16
  45. package/dist/{entry-QSJCFI5Z.js → entry-E62DZQJF.js} +10 -10
  46. package/dist/{exec-mcp-AFPUJTN7.js → exec-mcp-4N7FLY52.js} +13 -12
  47. package/dist/{harness-PPM32AI5.js → harness-E2AUZDLV.js} +3 -3
  48. package/dist/harness-launch-gate.js +4 -4
  49. package/dist/harness-worker.js +6 -6
  50. package/dist/{heavy-TEHP5PHT.js → heavy-HZQVFI6P.js} +182 -52
  51. package/dist/hook-body.js +116 -45
  52. package/dist/{hooks-L4PXVEGR.js → hooks-VAEAK2FY.js} +4 -4
  53. package/dist/{host-MU2GRH57.js → host-4GJDGTLW.js} +7 -7
  54. package/dist/{host-LBTL47X7.js → host-I2EMQ7UE.js} +18 -65
  55. package/dist/{host-run-IRSAQA5Z.js → host-run-DDMKD3BU.js} +5 -5
  56. package/dist/http.js +1 -1
  57. package/dist/{import-mcp-QVPW6A2Q.js → import-mcp-TNSAMJXI.js} +12 -11
  58. package/dist/index.d.ts +1 -1
  59. package/dist/index.js +16 -15
  60. package/dist/{init-46STH6FP.js → init-UA7MDNTZ.js} +2 -2
  61. package/dist/{invoke-I6C6UT6Q.js → invoke-HW7NBPGP.js} +8 -8
  62. package/dist/{list-HXG6EB7V.js → list-A7VQJXE5.js} +14 -13
  63. package/dist/{logout-SSUXJ6SE.js → logout-HNPLUKJY.js} +13 -12
  64. package/dist/{mailbox-5FVFMQ2J.js → mailbox-MR6TPD3P.js} +20 -6
  65. package/dist/{mainline-4XP6ZORU.js → mainline-MSLW3UFD.js} +14 -8
  66. package/dist/{mcp-L6X45IOS.js → mcp-6C23GX2E.js} +2 -2
  67. package/dist/{modes-SEINLLMK.js → modes-7OY7R73T.js} +3 -3
  68. package/dist/{pause-CMZOIHTJ.js → pause-H6ZYZF7C.js} +5 -2
  69. package/dist/{project-4JPKU2D7.js → project-BX6NCGKB.js} +4 -4
  70. package/dist/{report-UB7MXAUB.js → report-43SFNNCF.js} +2 -2
  71. package/dist/{resume-PAKIT4TT.js → resume-2BWGSTCN.js} +5 -2
  72. package/dist/{run-PMASXIGY.js → run-2UVAWBAF.js} +12 -11
  73. package/dist/{run-OW7436TY.js → run-7TRWZFEZ.js} +4 -4
  74. package/dist/{serve-P3HJN6AF.js → serve-4XZ5SKJJ.js} +3 -3
  75. package/dist/{setup-6AQUOWOH.js → setup-GRWLDBVB.js} +4 -4
  76. package/dist/{start-login-P7YDRTA3.js → start-login-AR7ITWNV.js} +13 -12
  77. package/dist/{status-4PYPTYUB.js → status-2GDYLIR3.js} +6 -3
  78. package/dist/{status-DAXQKT35.js → status-VQCMJFVE.js} +31 -28
  79. package/dist/{status-DLGZDYEP.js → status-ZY6LDQSF.js} +13 -12
  80. package/dist/stdio.js +2 -2
  81. package/dist/{sweep-VURZU6DI.js → sweep-76BUOGEI.js} +5 -2
  82. package/dist/{test-H243OTSK.js → test-VWGNFSH5.js} +15 -13
  83. package/dist/{tui-P6XTSTQO.js → tui-TUMOQBE7.js} +4 -4
  84. package/dist/{unbroadcast-7AMLURCG.js → unbroadcast-HJHYUHZL.js} +5 -2
  85. package/dist/{worker-5YJLIGTU.js → worker-NEEPJRVV.js} +8 -8
  86. package/dist/{worktree-create-FTSLMZWS.js → worktree-create-ZQRN5JBD.js} +2 -2
  87. package/dist/{worktree-list-WH6OX6U7.js → worktree-list-WZC75NLF.js} +11 -12
  88. package/dist/{worktree-sync-DGNHSQ64.js → worktree-sync-MUVKK2CV.js} +5 -5
  89. package/docs/commands.md +9 -7
  90. package/docs/git-workflow.md +7 -1
  91. package/docs/glossary.md +1 -1
  92. package/docs/hooks.md +20 -16
  93. package/docs/project-configuration.md +76 -37
  94. package/docs/sessions.md +9 -2
  95. package/docs/upgrading.md +58 -0
  96. package/gemini-extension.json +2 -2
  97. package/mcp.json +1 -1
  98. package/package.json +5 -5
  99. package/plugin.json +1 -1
  100. package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
  101. package/plugins/pmcp/.mcp.json +1 -1
  102. package/plugins/pmcp/gemini-extension.json +2 -2
  103. package/plugins/pmcp/mcp.json +1 -1
  104. package/plugins/pmcp/plugin.json +1 -1
  105. package/dist/chunk-LTMHE5VL.js +0 -7
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 or worktree ahead/behind drift exists or a budget limit is exceeded; 2 when there is no `pmcp.toml`. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stdout; JSON retains the full details.
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 drift exists or a budget limit is exceeded; 2 when there is no `pmcp.toml`. 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 defaults to `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`.
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,9 +214,9 @@ 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
- - `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 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"`).
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
 
221
221
  ## heavy
222
222
 
@@ -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 <ticket>` reads the state (queued with its position, running, done, or lost when the runner died), `--json` as data; `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 one line with the share of all runs that skipped it, `--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, or `--now` without a reason.
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. `result <ticket>` reads the state (queued with its position, running, done, or lost when the runner died), `--json` as data; `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
 
@@ -374,7 +374,9 @@ Both show the project and lockfile changes and stop: `--yes` (`-y`) approves the
374
374
 
375
375
  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
376
 
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.
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. 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.
378
+
379
+ 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
380
 
379
381
  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
382
 
@@ -213,7 +213,13 @@ changed file no member reads on stderr as `unmapped, not tested: <path>`. It alw
213
213
  with an answer and answers `ALL` (fail closed) when the base or head does not resolve, the
214
214
  base equals the head, the root manifest or lockfile does not parse, or `[git.affected]` is
215
215
  absent. Paths in the table are relative to the checkout root, so `--config` may name a file
216
- outside the checkout. Membership is read from the checkout, which must be at the head.
216
+ outside the checkout. Every input (membership, member manifests, tsconfig and vitest configs,
217
+ sources and the lockfile) is read from git objects at the head, and a submodule at the commit the
218
+ head pins, never from the working tree, so the checkout may move while it runs. A submodule with
219
+ no object store on the host reads as empty, as an uninitialized one would; one whose store lacks
220
+ the pinned commit answers `ALL`. What the consumer graph needs from each source file is cached
221
+ by blob id in `$XDG_CACHE_HOME/pmcp/affected-sources.json`, so a later run reads only the
222
+ sources that changed.
217
223
 
218
224
  `[git.affected]` describes the workspace; every key is optional:
219
225
 
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` | A name, not a role: the default sender of `pmcp sessions pause`, `broadcast` and `send` (`--by`), and a mailbox actor you may register. The docs call the person "you". |
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,25 @@ 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
- | Table | Default mode | Modes | Refuses |
76
- | ------------------------------------------ | ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
- | `[hooks.guards.shell.in_place_edit]` | deny | deny, ask, warn, observe, off | `sed -i`, `perl -i`, `awk -i inplace`: edits without a diff. |
78
- | `[hooks.guards.shell.heredoc]` | deny | deny, ask, warn, observe, off | Heredocs and here-strings, whose body the shell expands silently. |
79
- | `[hooks.guards.shell.stdin_interpreter]` | ask | deny, ask, warn, observe, off | An interpreter reading its program from stdin (`python3 -`, `cat x.py \| python3`). |
80
- | `[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. |
81
- | `[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. |
82
- | `[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. |
83
- | `[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. |
84
- | `[hooks.guards.git.push_without_verify]` | deny | deny, ask, warn, observe, off | `git push --no-verify`. |
85
- | `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, observe, off | Forcing a branch that is checked out in another working tree. |
86
- | `[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. |
87
- | `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, observe, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
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.git.push_without_verify]` | deny | deny, ask, warn, observe, off | `git push --no-verify`. |
88
+ | `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, observe, off | Forcing a branch that is checked out in another working tree. |
89
+ | `[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. |
90
+ | `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, observe, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
91
+ | `[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
92
 
89
93
  Options:
90
94
 
@@ -330,7 +334,7 @@ table for your project, with Codex trust.
330
334
  | `[git.shared_checkout]`, `[git.worktrees.sync]`, `[git.mainline.deliver]` | measured | measured |
331
335
  | heredoc, compose_teardown, push_without_verify, forced_branch_move, gate_bypass_env, stage_all | measured | measured |
332
336
  | in_place_edit, stdin_interpreter, secret_exfiltration (ask) | ask not measured | ask lowered by `ask_fallback` |
333
- | host_approval | works; not live-measured | works; not live-measured |
337
+ | host_approval, operator_verbs | works; not live-measured | works; not live-measured |
334
338
  | `[hooks.checks.after_edit]` | measured | measured |
335
339
  | `[hooks.checks.on_stop]` | measured, in the same turn | at the next prompt |
336
340
  | `[[hooks.guards.custom]]` | not measured | not measured |
@@ -61,7 +61,7 @@ ignored.
61
61
  | `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]` | [Hooks](hooks.md) |
62
62
  | `[budget]` | [Budget](#budget) |
63
63
  | `[[hooks.shell]]`, `[[hooks.edit]]` | [Deprecated shell guards](hooks.md#deprecated-shell-guards) |
64
- | `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]` | [Sessions](#sessions) |
64
+ | `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]`, `[sessions.operator]` | [Sessions](#sessions) |
65
65
  | `[git]`, `[git.shared_checkout]`, `[git.worktrees]`, `[git.worktrees.sync]`, `[git.mainline]`, `[git.mainline.gate]`, `[git.mainline.deliver]`, `[git.mainline.sync]`, `[git.submodules]` | [Git workflow](git-workflow.md) |
66
66
  | `[logging]`, `[logging.components]` | [Logging](#logging) |
67
67
  | `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
@@ -276,8 +276,9 @@ max_io = 8
276
276
  budget = 4
277
277
  hold_warn = 1800
278
278
  hold_max = 3600
279
- heavy = [["npm", "install"], ["npm", "test"], ["cargo", "build"]]
279
+ heavy = ["default", ["make", "all"]]
280
280
  guard = "deny"
281
+ skip_reasons = ["ci"]
281
282
 
282
283
  [host.lease.lanes]
283
284
  interactive = 2
@@ -292,38 +293,39 @@ max_wait = 2700
292
293
  load_grace = 600
293
294
  ```
294
295
 
295
- | Key | Type | Default | Meaning |
296
- | ------------------- | ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
297
- | `enabled` | boolean | `true` | `false` runs every `pmcp heavy` command at once, gates without the lease and turns the guard off. |
298
- | `dir` | path | `~/.cache/pmcp/host` | Where the lock file (`heavy.lock`), the admission lock, the `running/` and `waiters/` records, the holder record and `heavy.log` live. Every tool sharing the lease names the same directory. |
299
- | `budget` | integer | `4` | The most weight that runs at once. `1` is one job at a time. |
300
- | `lanes.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 1 | How many jobs of a lane run at once; `0` closes the lane. |
301
- | `weights.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 3 | A job's weight when neither `--weight` nor a `commands` entry names one. A weight above the budget counts as the budget. |
302
- | `commands` | tables | none | `argv` prefix, `lane` and `weight` for commands run without `--lane` or `--weight`; the first match wins. |
303
- | `tiny` | argv lists | none | Commands so short (a few seconds) that they take no slot and no budget (weight 0, also `--weight 0`); only the hard ceiling holds them back, and the log still records them. |
304
- | `per_session` | integer | `1` | How many jobs one agent session may have queued in the interactive lane, and in the bulk lane; the next one waits outside the queue holding no place. `0` is no cap. Gate and hook are exempt. |
305
- | `marker_env` | name | `PMCP_HEAVY_LEASE` | Set to the job's pid for the leased command; a nested `pmcp heavy` whose marker names a running job runs at once. |
306
- | `legacy_marker_env` | name | none | A second marker, set and honoured like `marker_env`, for a shell wrapper that shares `dir`. |
307
- | `legacy_skip_env` | name | none | A second skip variable, honoured like `PMCP_HEAVY_DISABLE`, and set for the leased command so a nested shell wrapper runs at once. |
308
- | `skip_always` | list of reasons | `[]` | Skip reasons honoured even for a bulk job, for callers that must never wait on the lease (a commit hook). A skip with any other reason does not cover a bulk job. |
309
- | `max_load` | number | the CPU count | A job starts only while the 1-minute load average is below this. |
310
- | `max_io` | number | `8` | And while IO pressure (`some`, the `io_window` average) is below this. A host without pressure files checks load only; one without a load average checks neither. |
311
- | `io_window` | string | `avg60` | Which pressure average the check reads: `avg10` follows spikes, `avg60` and `avg300` smooth them so the queue does not stall on a burst. |
312
- | `max_wait` | seconds | `3600` | How long the `default` profile waits; then nothing runs and the exit is 75. |
313
- | `load_grace` | seconds | `900` | After this long waiting on the host, a job may start into moderate overload, but only while no leased job runs, so a grace never starts two jobs together. `0` is no grace. |
314
- | `hard_factor` | number | `2` | Never start, grace or not, while load or IO is at this many times its limit; such a job waits until `max_wait`, then exits 75. |
315
- | `hold_warn` | seconds | `1800` | A job running past this prints one warning, and `pmcp heavy status` marks it. |
316
- | `hold_max` | seconds | none | `pmcp heavy status` flags a job past this as over the limit. Nothing is killed. |
317
- | `memory_max` | size | none | Runs each command in `systemd-run --user --scope -p MemoryMax=<size> -p MemorySwapMax=0` where that is available, so a runaway job is killed alone. Without a reachable user manager (no `XDG_RUNTIME_DIR`, or no manager socket in it, as under `env -i` or cron) the command runs without the scope and one line on stderr says why; if `systemd-run` still cannot reach the bus, the command runs once more without it. A missing scope never fails the command. |
318
- | `heartbeat`, `poll` | seconds | `60`, `15` | How often a waiter prints that it is still waiting, and how often the host is reread. |
319
- | `profiles.<name>` | table | gate 2700/600, hook 900/30 | `max_wait`, `load_grace` and `memory_max` for `pmcp heavy --profile <name>`. The `gate` and `hook` profiles also choose their lane. Any other profile starts from the top-level values. |
320
- | `heavy` | argv lists | none | The commands the `host.lease` guard expects under the lease, as argv prefixes. Empty, the guard is off. pmcp lists none of its own. |
321
- | `guard` | string | `observe` | The `host.lease` guard's mode: `observe` logs only, `warn` tells the agent, `deny` refuses with the command to run instead (`pmcp heavy -- <command>`), `off`. A command already wrapped passes. |
322
- | `io.enabled` | `"auto"` or boolean | `"auto"` | Each leased job runs in its own `systemd-run --user` scope and gets its lane's `io.weight` where the cgroup v2 io controller reaches the user manager; elsewhere nothing changes. `true` also says when it could not; `false` never. |
323
- | `io.weights.<lane>` | integer | gate 500, hook 300, interactive 100, bulk 25 | The scope's `io.weight` per lane (1 to 10000). |
324
- | `io.max.<lane>` | string | none | An `io.max` line for the lane's scopes, such as `"259:0 wbps=50000000"`; the device is this host's to name. |
325
- | `settle_window` | seconds | `60` | After a leased job ends, its own leftover IO may hold the queue only this long: then a waiter starts on a moderately busy host (below `hard_factor`). `0` turns it off. |
326
- | `usage_cap` | bytes | `5000000` | `usage.jsonl` (one record per run) moves to `usage.jsonl.1` past this size. |
296
+ | Key | Type | Default | Meaning |
297
+ | ------------------- | -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
298
+ | `enabled` | boolean | `true` | `false` runs every `pmcp heavy` command at once, gates without the lease and turns the guard off. |
299
+ | `dir` | path | `~/.cache/pmcp/host` | Where the lock file (`heavy.lock`), the admission lock, the `running/` and `waiters/` records, the holder record and `heavy.log` live. Every tool sharing the lease names the same directory. |
300
+ | `budget` | integer | `4` | The most weight that runs at once. `1` is one job at a time. |
301
+ | `lanes.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 1 | How many jobs of a lane run at once; `0` closes the lane. |
302
+ | `weights.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 3 | A job's weight when neither `--weight` nor a `commands` entry names one. A weight above the budget counts as the budget. |
303
+ | `commands` | tables | none | `argv` prefix, `lane` and `weight` for commands run without `--lane` or `--weight`; the first match wins. |
304
+ | `tiny` | argv lists | none | Commands so short (a few seconds) that they take no slot and no budget (weight 0, also `--weight 0`); only the hard ceiling holds them back, and the log still records them. |
305
+ | `per_session` | integer | `1` | How many jobs one agent session may have queued in the interactive lane, and in the bulk lane; the next one waits outside the queue holding no place. `0` is no cap. Gate and hook are exempt. |
306
+ | `marker_env` | name | `PMCP_HEAVY_LEASE` | Set to the job's pid for the leased command; a nested `pmcp heavy` whose marker names a running job runs at once. |
307
+ | `legacy_marker_env` | name | none | A second marker, set and honoured like `marker_env`, for a shell wrapper that shares `dir`. |
308
+ | `legacy_skip_env` | name | none | A second skip variable, honoured like `PMCP_HEAVY_DISABLE`, and set for the leased command so a nested shell wrapper runs at once. |
309
+ | `skip_always` | list of reasons | `[]` | Skip reasons honoured even for a bulk job, for callers that must never wait on the lease (a commit hook). They are allowed skip reasons too. |
310
+ | `skip_reasons` | list of reasons | `[]` | The further reasons `PMCP_HEAVY_DISABLE` may carry for an ordinary command, beside the built-in `nested` and `operator`. Lower-case words (`a-z`, digits, `-`, `_`, `.`, `:`). |
311
+ | `max_load` | number | the CPU count | A job starts only while the 1-minute load average is below this. |
312
+ | `max_io` | number | `8` | And while IO pressure (`some`, the `io_window` average) is below this. A host without pressure files checks load only; one without a load average checks neither. |
313
+ | `io_window` | string | `avg60` | Which pressure average the check reads: `avg10` follows spikes, `avg60` and `avg300` smooth them so the queue does not stall on a burst. |
314
+ | `max_wait` | seconds | `3600` | How long the `default` profile waits; then nothing runs and the exit is 75. |
315
+ | `load_grace` | seconds | `900` | After this long waiting on the host, a job may start into moderate overload, but only while no leased job runs, so a grace never starts two jobs together. `0` is no grace. |
316
+ | `hard_factor` | number | `2` | Never start, grace or not, while load or IO is at this many times its limit; such a job waits until `max_wait`, then exits 75. |
317
+ | `hold_warn` | seconds | `1800` | A job running past this prints one warning, and `pmcp heavy status` marks it. |
318
+ | `hold_max` | seconds | none | `pmcp heavy status` flags a job past this as over the limit. Nothing is killed. |
319
+ | `memory_max` | size | none | Runs each command in `systemd-run --user --scope -p MemoryMax=<size> -p MemorySwapMax=0` where that is available, so a runaway job is killed alone. Without a reachable user manager (no `XDG_RUNTIME_DIR`, or no manager socket in it, as under `env -i` or cron) the command runs without the scope and one line on stderr says why; if `systemd-run` still cannot reach the bus, the command runs once more without it. A missing scope never fails the command. |
320
+ | `heartbeat`, `poll` | seconds | `60`, `15` | How often a waiter prints that it is still waiting, and how often the host is reread. |
321
+ | `profiles.<name>` | table | gate 2700/600, hook 900/30 | `max_wait`, `load_grace` and `memory_max` for `pmcp heavy --profile <name>`. The `gate` and `hook` profiles also choose their lane. Any other profile starts from the top-level values. |
322
+ | `heavy` | argv lists, or `"default"` | `"default"` with the table, none without | The commands the `host.lease` guard expects under the lease, as argv prefixes. `"default"`, alone or as an item of the list, names pmcp's preset: `install` (and `i`, `ci`), `test`, `build` and `typecheck` for npm, pnpm, yarn and bun (`<manager> run <script>` too), and `cargo build`, `test` and `check`. An empty list turns the guard off. |
323
+ | `guard` | string | `observe` | The `host.lease` guard's mode: `observe` logs what it would have refused (at info, so `pmcp hooks report --switch-check host.lease` reads it at the default log level), `warn` tells the agent, `deny` refuses with the command to run instead (`pmcp heavy -- <command>`), `off`. A command already wrapped passes. Run a week in `observe`, read the report, then set `deny`. |
324
+ | `io.enabled` | `"auto"` or boolean | `"auto"` | Each leased job runs in its own `systemd-run --user` scope and gets its lane's `io.weight` where the cgroup v2 io controller reaches the user manager; elsewhere nothing changes. `true` also says when it could not; `false` never. |
325
+ | `io.weights.<lane>` | integer | gate 500, hook 300, interactive 100, bulk 25 | The scope's `io.weight` per lane (1 to 10000). |
326
+ | `io.max.<lane>` | string | none | An `io.max` line for the lane's scopes, such as `"259:0 wbps=50000000"`; the device is this host's to name. |
327
+ | `settle_window` | seconds | `60` | After a leased job ends, its own leftover IO may hold the queue only this long: then a waiter starts on a moderately busy host (below `hard_factor`). `0` turns it off. |
328
+ | `usage_cap` | bytes | `5000000` | `usage.jsonl` (one record per run) moves to `usage.jsonl.1` past this size. |
327
329
 
328
330
  Lanes, in the order a short budget goes to them: `gate` (a land's gate),
329
331
  `hook` (commit-hook work, a short slot that skips the host wait unless the host
@@ -337,7 +339,7 @@ on every admission, so running weight never exceeds the budget and a crashed
337
339
  job frees its share.
338
340
 
339
341
  `pmcp heavy --now --reason <text>` (or `PMCP_HEAVY_NOW=<reason>` in a script) is
340
- the emergency bypass: the command starts at once, outside the lanes, the budget
342
+ the operator's emergency bypass ([the operator](#the-operator)): the command starts at once, outside the lanes, the budget
341
343
  and the host check, and never exits 75, but it needs a reason, is logged as a
342
344
  `bypass` line, shows as `bypass running` in status and counts its weight, so the
343
345
  other jobs' admission sees its load. It is not the off switch below.
@@ -355,10 +357,18 @@ the configured ones.
355
357
  `PMCP_HEAVY_DISABLE=<reason>` (or the `legacy_skip_env` variable) skips the
356
358
  lease for an ordinary command: `pmcp heavy` runs it at once, logs the reason,
357
359
  and keeps it as `skip` in the command's usage record, and the guard lets a
358
- command that sets it pass. The skip is bounded: a bulk job (an install, a
360
+ command that sets it pass. The reason is one of a closed set: `nested`, which
361
+ pmcp sets itself for a wrapper inside a leased job and honours only while a
362
+ leased job encloses the command; `operator`, honoured only for
363
+ [the operator](#the-operator); and the names in `skip_reasons` or `skip_always`.
364
+ Any other reason runs nothing: `pmcp heavy` exits 2 naming the allowed reasons,
365
+ logs a `skip-invalid` line and records `skip_invalid`, so the share of skipped
366
+ runs reads by reason in `pmcp heavy stats`. The skip is bounded: a bulk job (an install, a
359
367
  whole test suite, a full build), put in the `bulk` lane by `--lane bulk` or by
360
368
  a `commands` entry, still queues in that lane, with a line on standard error
361
- saying the skip was not honoured;
369
+ saying the skip was not honoured and `skip_refused` in its usage record. The
370
+ `skip` or `skip-refused` line in `heavy.log` (`env=`) and the record's
371
+ `skip_env` name the variable that carried the skip;
362
372
  `--now --reason <text>` is the emergency path for it. A bulk job nested in a
363
373
  leased job runs at once on the lease marker, as any nested job does.
364
374
  `pmcp heavy stats` shows how many runs skipped the lease, so a bypass that
@@ -371,6 +381,7 @@ that must never wait on the lease, such as a commit hook:
371
381
  ```toml
372
382
  [host.lease]
373
383
  skip_always = ["git-hook"] # PMCP_HEAVY_DISABLE=git-hook runs even a bulk job at once
384
+ skip_reasons = ["ci"] # PMCP_HEAVY_DISABLE=ci runs an ordinary command at once
374
385
  ```
375
386
 
376
387
  The files extend those of a shell wrapper that takes the same lock with
@@ -626,6 +637,34 @@ lives in one directory shared by every checkout of the repository.
626
637
  These tables have no `mode`, except pause. Without `[sessions.registry]` no
627
638
  session is recorded, and `[ui.claude]` refuses to project.
628
639
 
640
+ ### The operator
641
+
642
+ The operator is you: the person who governs the agent sessions. A few verbs are yours alone,
643
+ because an agent running them would govern the others: `pmcp sessions pause` and `resume`,
644
+ `pmcp heavy --now` (and `PMCP_HEAVY_NOW`), `pmcp heavy promote --now`,
645
+ `pmcp heavy cancel --force` on another session's job, and `pmcp git deliver --during-pause`.
646
+ Signing a broadcast or a message as `operator` is yours too. `[sessions.operator]` says how
647
+ pmcp recognises you:
648
+
649
+ | Key | Type | Default | Meaning |
650
+ | ------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
651
+ | `via` | string | `"tty"` | `"tty"`: an interactive terminal (standard input) with no agent runtime among the command's parent processes and no agent's environment markers. `"token"`: `PMCP_OPERATOR_TOKEN` equals the contents of `token_file`, wherever the command runs (a script, cron). |
652
+ | `token_file` | path | none | With `via = "token"`: absolute or `~/…`, outside the project, readable by its owner only (mode 600); pmcp refuses a file others can read. |
653
+
654
+ ```toml
655
+ [sessions.operator]
656
+ via = "token"
657
+ token_file = "~/.config/pmcp/operator-token"
658
+ ```
659
+
660
+ Run from an agent session, an operator verb exits 1 with
661
+ `<verb> is the operator's to run: <why>. Ask the operator to run it from their own terminal`,
662
+ and changes nothing; the agent relays the request to you. With any session feature declared,
663
+ the `pmcp.operator_verbs` guard ([Hooks](hooks.md)) also refuses these command lines in the
664
+ agent's runtime, before they run. Every session runs as the same user, so this stops
665
+ instructed agents and accidents rather than a determined process: for a hard boundary run the
666
+ agents under another user, where a token file only you can read keeps them out.
667
+
629
668
  ### `[sessions.mailbox]`
630
669
 
631
670
  Addressed messages between sessions, and between you and them. A missing table leaves
package/docs/sessions.md CHANGED
@@ -33,8 +33,15 @@ pmcp sessions sweep # drop records whose process is gone
33
33
 
34
34
  While paused, every other session's edits and mutating commands are refused; reading and
35
35
  planning continue. A broadcast reaches each running session once, as context. `--by <name>`
36
- names who pauses or broadcasts; that session is exempt, and without it the sender is
37
- `operator`.
36
+ names who pauses or broadcasts; that session is exempt. Without it a broadcast is signed by
37
+ the agent session it runs in, or by `operator` from your own terminal.
38
+
39
+ Pause and resume are [operator verbs](project-configuration.md#the-operator): pmcp runs them
40
+ only from your terminal (or with your operator token), refuses them inside an agent session
41
+ with a line telling the agent to ask you, and the `pmcp.operator_verbs` guard refuses them in
42
+ the agent's runtime before they start. The same holds for `pmcp heavy --now`,
43
+ `pmcp heavy promote --now`, `pmcp heavy cancel --force` on another session's job and
44
+ `pmcp git deliver --during-pause`.
38
45
 
39
46
  ## Send a message to one session
40
47
 
package/docs/upgrading.md CHANGED
@@ -5,6 +5,64 @@
5
5
  What to do when a release changes something you rely on. Each release's notes on GitHub
6
6
  Releases list its breaking changes and link here.
7
7
 
8
+ ## From 0.24 to 0.25
9
+
10
+ **`pmcp status` exits 4 only for projection drift or a budget overrun.** A linked worktree
11
+ ahead of or behind the mainline no longer sets `drift` or the exit code; it is counted in
12
+ the summary line and in the new `data.lagging` field. A script that relied on exit 4 to
13
+ notice worktree lag reads `lagging` from `pmcp status --json` instead.
14
+
15
+ **Operator verbs run only as the operator.** `pmcp sessions pause` and `resume`,
16
+ `pmcp heavy --now` (and `PMCP_HEAVY_NOW`), `pmcp heavy promote --now`,
17
+ `pmcp heavy cancel --force` on another session's job and `pmcp git deliver --during-pause`
18
+ now exit 1 inside an agent session, with a line telling the agent to ask you. From your own
19
+ terminal nothing changes. A script or cron job that runs one of them has no terminal: give
20
+ it an operator token,
21
+
22
+ ```toml
23
+ [sessions.operator]
24
+ via = "token"
25
+ token_file = "~/.config/pmcp/operator-token" # outside the project, chmod 600
26
+ ```
27
+
28
+ and run it with `PMCP_OPERATOR_TOKEN` set to the file's contents. A gate or hook that ran
29
+ `pmcp heavy --now` for its own stages should use the `gate` or `hook` profile, or a reason
30
+ in `[host.lease] skip_always`, instead.
31
+
32
+ **`--by` no longer defaults to `operator`.** `pmcp sessions broadcast`, `send` and `reply`
33
+ sign with the agent session they run in, or with `operator` only from the operator's
34
+ terminal; `--by operator` anywhere else exits 2. A command run inside a runtime whose
35
+ session pmcp cannot find (Gemini CLI, OpenCode) now exits 2 asking for `--session <id>` or
36
+ `--by <name>` instead of acting as the operator.
37
+
38
+ **The `pmcp.operator_verbs` guard is on with any session feature.** A project that declares
39
+ `[sessions.registry]`, `[sessions.pause]` or another session table gets it in deny mode;
40
+ run `pmcp project` once so the hook policy carries it (`pmcp project --check` reports the
41
+ drift until then). Turn it off with
42
+ `[hooks.guards.pmcp.operator_verbs]` `mode = "off"`.
43
+
44
+ **Lease skip reasons are a closed set.** `PMCP_HEAVY_DISABLE=<reason>` (and the
45
+ `legacy_skip_env` variable) is honoured only for `nested` (set by pmcp inside a leased job,
46
+ and honoured only there), `operator` (only for the operator) and the names you list:
47
+
48
+ ```toml
49
+ [host.lease]
50
+ skip_reasons = ["ci", "subagent-no-lease"] # ordinary commands
51
+ skip_always = ["git-hook", "gate-light"] # also bulk jobs; allowed as reasons too
52
+ ```
53
+
54
+ Any other reason runs nothing and `pmcp heavy` exits 2 with the allowed list. A wrapper
55
+ that read the old nested value `inside pmcp heavy <pid>` now sees `nested`; the old
56
+ value is still read as `nested` until 0.26. Reasons are lower-case words, so a
57
+ `skip_always` entry with spaces or capitals is now a configuration error.
58
+
59
+ **A declared `[host.lease]` turns the `host.lease` guard on in observe.** Without a
60
+ `heavy` list, the table now gets pmcp's `"default"` preset (install, test, build and
61
+ typecheck for npm, pnpm, yarn, bun and cargo), so the guard logs what it would refuse.
62
+ Run `pmcp project` to project it; set `heavy = []` to keep the guard off. A finding an
63
+ `observe` or `warn` guard let through is now logged at info: after a week,
64
+ `pmcp hooks report --switch-check host.lease` shows what `guard = "deny"` would refuse.
65
+
8
66
  ## From 0.23 to 0.24
9
67
 
10
68
  **A lease skip no longer covers a bulk job.** `PMCP_HEAVY_DISABLE=<reason>` (or the
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.24.0",
3
+ "version": "0.25.0",
4
4
  "mcpServers": {
5
5
  "pmcp": {
6
6
  "type": "stdio",
7
7
  "command": "npx",
8
- "args": ["-y", "@modootoday/pmcp@0.24.0", "serve"]
8
+ "args": ["-y", "@modootoday/pmcp@0.25.0", "serve"]
9
9
  }
10
10
  }
11
11
  }
package/mcp.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "pmcp": {
5
5
  "type": "stdio",
6
6
  "command": "npx",
7
- "args": ["-y", "@modootoday/pmcp@0.24.0", "serve"]
7
+ "args": ["-y", "@modootoday/pmcp@0.25.0", "serve"]
8
8
  }
9
9
  }
10
10
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@modootoday/pmcp",
3
- "version": "0.24.0",
3
+ "version": "0.25.0",
4
4
  "license": "Elastic-2.0",
5
5
  "author": "modootoday",
6
6
  "description": "Use the skills your packages already ship, and keep your AI tools' project configuration in one place.",
@@ -136,9 +136,9 @@
136
136
  "bun": ">=1.3.0"
137
137
  },
138
138
  "optionalDependencies": {
139
- "@modootoday/pmcp-linux-x64": "0.24.0",
140
- "@modootoday/pmcp-linux-arm64": "0.24.0",
141
- "@modootoday/pmcp-darwin-x64": "0.24.0",
142
- "@modootoday/pmcp-darwin-arm64": "0.24.0"
139
+ "@modootoday/pmcp-linux-x64": "0.25.0",
140
+ "@modootoday/pmcp-linux-arm64": "0.25.0",
141
+ "@modootoday/pmcp-darwin-x64": "0.25.0",
142
+ "@modootoday/pmcp-darwin-arm64": "0.25.0"
143
143
  }
144
144
  }
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "pmcp",
4
- "version": "0.24.0",
4
+ "version": "0.25.0",
5
5
  "description": "Find package skills and use native runtime project configuration.",
6
6
  "author": { "name": "modootoday" },
7
7
  "license": "Elastic-2.0",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pmcp",
3
- "version": "0.24.0",
3
+ "version": "0.25.0",
4
4
  "description": "Find package skills and use native runtime project configuration.",
5
5
  "author": { "name": "modootoday" },
6
6
  "license": "Elastic-2.0",
@@ -3,7 +3,7 @@
3
3
  "pmcp": {
4
4
  "type": "stdio",
5
5
  "command": "npx",
6
- "args": ["-y", "@modootoday/pmcp@0.24.0", "serve"]
6
+ "args": ["-y", "@modootoday/pmcp@0.25.0", "serve"]
7
7
  }
8
8
  }
9
9
  }