@modootoday/pmcp 0.22.12 → 0.23.1

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 (154) 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 +836 -0
  6. package/dist/{apply-LPKZZ6EL.js → apply-3PWUO4J5.js} +27 -22
  7. package/dist/{available-BFXLII4A.js → available-74CMIBPD.js} +9 -9
  8. package/dist/{broadcast-DZGMSZRG.js → broadcast-VKZY7WSD.js} +6 -5
  9. package/dist/chunk-2GZKA33O.js +173 -0
  10. package/dist/chunk-2HL2MFNI.js +159 -0
  11. package/dist/{chunk-OAX6MIOZ.js → chunk-2K4WYN4C.js} +2 -2
  12. package/dist/{chunk-PEMMV5YQ.js → chunk-2MX5C7B2.js} +3 -3
  13. package/dist/{chunk-7I7O7ZNT.js → chunk-3V37OZQH.js} +5 -3
  14. package/dist/chunk-43MXRTKH.js +134 -0
  15. package/dist/chunk-4VVQLWTS.js +93 -0
  16. package/dist/{chunk-DYZVHO2L.js → chunk-5HNLHI5F.js} +2 -2
  17. package/dist/{chunk-JEL35P7S.js → chunk-5NDUWEMW.js} +2 -2
  18. package/dist/chunk-65BW7Y6O.js +40 -0
  19. package/dist/{chunk-HUBJWC7T.js → chunk-6NRLBSEG.js} +7 -7
  20. package/dist/chunk-6QJ3F445.js +166 -0
  21. package/dist/{chunk-2OOWAGBE.js → chunk-72V6U7CZ.js} +3 -3
  22. package/dist/{chunk-RPCIROW7.js → chunk-7CHUMF3E.js} +2 -2
  23. package/dist/{chunk-INT7QLEU.js → chunk-7DJQASH3.js} +25 -6
  24. package/dist/chunk-7IRXUPM2.js +7 -0
  25. package/dist/{chunk-UDVYVRGJ.js → chunk-DNSHJIS4.js} +2 -2
  26. package/dist/{chunk-UMQLIRSU.js → chunk-DZTSCJOZ.js} +3 -3
  27. package/dist/{chunk-KEHB4FZP.js → chunk-E2E4HIEN.js} +49 -3
  28. package/dist/{chunk-SUJCVEBM.js → chunk-EQF64INS.js} +3 -3
  29. package/dist/chunk-F3R5HEUB.js +39 -0
  30. package/dist/chunk-FOLA4EUJ.js +261 -0
  31. package/dist/chunk-FQLCD4HU.js +24 -0
  32. package/dist/{chunk-OEH47H6A.js → chunk-GUHOEIHP.js} +3 -20
  33. package/dist/{chunk-B2WRYGHJ.js → chunk-HES44LTA.js} +5 -5
  34. package/dist/{chunk-RHJEGLYM.js → chunk-HF5D6B2U.js} +45 -6
  35. package/dist/{chunk-R5MT42JS.js → chunk-HYXOJYVR.js} +2 -2
  36. package/dist/chunk-JANBBPKP.js +50 -0
  37. package/dist/{chunk-ITOTOC6Y.js → chunk-JJFPSFDU.js} +3 -3
  38. package/dist/{chunk-XNML2KIC.js → chunk-JPYQDOEW.js} +3 -3
  39. package/dist/{chunk-SPZQRLL5.js → chunk-KYGGQPAH.js} +18 -6
  40. package/dist/{chunk-EX4YXPVW.js → chunk-LGRFYN5T.js} +2 -2
  41. package/dist/{chunk-DP326AER.js → chunk-LO54UUDE.js} +2 -2
  42. package/dist/{chunk-5QKXEWDB.js → chunk-MHKY6TNF.js} +6 -4
  43. package/dist/chunk-N7ANFMA5.js +171 -0
  44. package/dist/{chunk-KPKMEUUH.js → chunk-OGCJO6HQ.js} +9 -8
  45. package/dist/{chunk-N63QCJHX.js → chunk-P25V6NEX.js} +5 -5
  46. package/dist/{chunk-PUIWESU3.js → chunk-Q6V274OB.js} +8 -6
  47. package/dist/chunk-QR6A3TYP.js +315 -0
  48. package/dist/{chunk-EIDIVIAD.js → chunk-QYLOIM4U.js} +9 -2
  49. package/dist/{chunk-MIFPPUWY.js → chunk-RRKA3GF5.js} +4 -4
  50. package/dist/{chunk-7CSUKCU7.js → chunk-RZYZILU4.js} +17 -96
  51. package/dist/{chunk-FODUHLZM.js → chunk-SDQYZDHS.js} +2 -2
  52. package/dist/chunk-SGFTHKKS.js +86 -0
  53. package/dist/chunk-T6C3TSTO.js +99 -0
  54. package/dist/chunk-UVTGY2R3.js +78 -0
  55. package/dist/{chunk-LLT5FQBE.js → chunk-VBVNOLRR.js} +7 -3
  56. package/dist/{chunk-ABTJQ4QV.js → chunk-WBPVNCQO.js} +20 -5
  57. package/dist/{chunk-63RZGEVI.js → chunk-WQBKQTNT.js} +98 -26
  58. package/dist/{chunk-YGOWIJPE.js → chunk-WZYGM3FR.js} +6 -2
  59. package/dist/chunk-Y6NFETNG.js +232 -0
  60. package/dist/{chunk-D5MIZM6L.js → chunk-YRNFMPZB.js} +7 -8
  61. package/dist/{chunk-2GRECE6B.js → chunk-ZXMECZBI.js} +4 -4
  62. package/dist/{cli-34EDFXJA.js → cli-GFDT4YXM.js} +14 -15
  63. package/dist/{cli-JXPJFHUA.js → cli-YWV7FLYO.js} +24 -12
  64. package/dist/cli.js +317 -51
  65. package/dist/{completion-KTECNPVY.js → completion-OKGNN7DE.js} +25 -21
  66. package/dist/{diagnostics-I5VZHK42.js → diagnostics-N4XRRCQG.js} +10 -6
  67. package/dist/{doctor-JJ2VUNHT.js → doctor-3H6UYNEA.js} +27 -23
  68. package/dist/{entry-OT7BN3ID.js → entry-KDLLG6ED.js} +19 -15
  69. package/dist/{exec-mcp-3E4SRJUY.js → exec-mcp-AENALAHJ.js} +15 -11
  70. package/dist/{harness-Q236VJSU.js → harness-GRYTNUF2.js} +26 -44
  71. package/dist/harness-launch-gate.js +8 -4
  72. package/dist/harness-worker.js +10 -6
  73. package/dist/heavy-BGXKJKYB.js +1965 -0
  74. package/dist/hook-body.js +69 -21
  75. package/dist/hooks-V25ANQ4Q.js +24 -0
  76. package/dist/{host-LT5JMUFJ.js → host-4EGPADOJ.js} +11 -7
  77. package/dist/{host-UDC4HVX3.js → host-MLSWY7D7.js} +24 -17
  78. package/dist/{host-run-LD63JGN7.js → host-run-VI52IUKF.js} +10 -6
  79. package/dist/http.js +1 -1
  80. package/dist/{import-mcp-URVONIZ3.js → import-mcp-FIXFLUDM.js} +18 -14
  81. package/dist/index.d.ts +1 -1
  82. package/dist/index.js +17 -12
  83. package/dist/init-ALTBFUPP.js +14 -0
  84. package/dist/{install-7V6NIA7W.js → install-5JH4DSFF.js} +10 -10
  85. package/dist/{invoke-JW5OC2HO.js → invoke-7T7UY57O.js} +12 -8
  86. package/dist/{list-UM4DYJRL.js → list-JFZ7UZLV.js} +18 -14
  87. package/dist/{list-WK2IYUK7.js → list-LV5EKCF6.js} +11 -7
  88. package/dist/{logout-H5X4D26I.js → logout-7CNBO76Z.js} +15 -11
  89. package/dist/{logs-UHJM7ZCL.js → logs-2JEMSNSG.js} +11 -10
  90. package/dist/{mailbox-NIMBOQPA.js → mailbox-5FVFMQ2J.js} +12 -44
  91. package/dist/{mailbox-YN6PG66A.js → mailbox-ZHZWZMAY.js} +14 -21
  92. package/dist/{mainline-74WCH4T4.js → mainline-6PBT3VNR.js} +75 -126
  93. package/dist/{marketplace-G4VQET5W.js → marketplace-2X3OOEPW.js} +10 -9
  94. package/dist/{mcp-6P3MVT4V.js → mcp-MVQVMAKJ.js} +4 -4
  95. package/dist/{mcp-AXHV547W.js → mcp-PBTQ5SJW.js} +2 -2
  96. package/dist/{models-ISU4DCMA.js → models-XSF45MCD.js} +9 -5
  97. package/dist/{pause-CBZ3BTJL.js → pause-CMZOIHTJ.js} +6 -5
  98. package/dist/{preview-DT7DWG5F.js → preview-465CQJBQ.js} +4 -4
  99. package/dist/{project-6QUIC73W.js → project-FZGJRG2U.js} +14 -12
  100. package/dist/{reindex-I7RYWCUR.js → reindex-D62HQAN2.js} +7 -7
  101. package/dist/{report-ZHOHQ4PZ.js → report-UB7MXAUB.js} +14 -13
  102. package/dist/{resume-UJEWQ66P.js → resume-PAKIT4TT.js} +6 -5
  103. package/dist/{run-HQTB7N2R.js → run-TOP37ZQC.js} +14 -10
  104. package/dist/run-VGJDMA2O.js +23 -0
  105. package/dist/{serve-APEVIJD2.js → serve-LR7SJHNH.js} +13 -13
  106. package/dist/{session-YZVX4NGN.js → session-3YVVO2GR.js} +6 -6
  107. package/dist/{setup-SOUBEZ3H.js → setup-6AQUOWOH.js} +7 -4
  108. package/dist/{smoke-2FI5D74B.js → smoke-6X6IXQIQ.js} +4 -4
  109. package/dist/{start-login-ER7DEGYN.js → start-login-X37KGCCB.js} +16 -12
  110. package/dist/{status-KN2ZE64O.js → status-4PYPTYUB.js} +7 -6
  111. package/dist/{status-7NYXRZ3R.js → status-E4AFUOQO.js} +24 -13
  112. package/dist/{status-OGABWCPO.js → status-LBRK37GA.js} +35 -30
  113. package/dist/stdio.js +2 -2
  114. package/dist/{sweep-EPZCW63Q.js → sweep-VURZU6DI.js} +6 -5
  115. package/dist/{test-WRZQERYC.js → test-D2EEFUN2.js} +18 -14
  116. package/dist/{tui-YUHQ36FC.js → tui-D7E3MD3X.js} +45 -19
  117. package/dist/{unbroadcast-N6LXHAMT.js → unbroadcast-7AMLURCG.js} +6 -5
  118. package/dist/{validate-KFBCUFI4.js → validate-YXR7FJJX.js} +11 -9
  119. package/dist/wait-HEODT7KV.js +141 -0
  120. package/dist/{worker-OKBJNDEI.js → worker-WTBC6VYO.js} +12 -8
  121. package/dist/{worktree-create-KMXPQXIQ.js → worktree-create-FTSLMZWS.js} +2 -2
  122. package/docs/commands.md +108 -36
  123. package/docs/git-workflow.md +51 -0
  124. package/docs/hooks.md +11 -4
  125. package/docs/project-configuration.md +136 -20
  126. package/docs/terminal-workspace.md +2 -0
  127. package/docs/upgrading.md +54 -0
  128. package/gemini-extension.json +2 -2
  129. package/mcp.json +1 -1
  130. package/package.json +5 -5
  131. package/plugin.json +1 -1
  132. package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
  133. package/plugins/pmcp/.mcp.json +1 -1
  134. package/plugins/pmcp/gemini-extension.json +2 -2
  135. package/plugins/pmcp/mcp.json +1 -1
  136. package/plugins/pmcp/plugin.json +1 -1
  137. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +1 -1
  138. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +1 -1
  139. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +3 -2
  140. package/skills/headless-agents-ci-scaffold/SKILL.md +1 -1
  141. package/skills/pmcp-project-init/SKILL.md +1 -1
  142. package/skills/pmcp-sessions-and-git/SKILL.md +3 -2
  143. package/dist/chunk-2P4Z2NUX.js +0 -28
  144. package/dist/chunk-3C5FVHQ3.js +0 -7
  145. package/dist/chunk-3Y3HDMHA.js +0 -108
  146. package/dist/chunk-A4PKLESO.js +0 -112
  147. package/dist/chunk-E3DQB5LS.js +0 -48
  148. package/dist/chunk-GFOQDLPL.js +0 -35
  149. package/dist/chunk-JWRZDYB5.js +0 -59
  150. package/dist/chunk-LMUBBIE2.js +0 -83
  151. package/dist/chunk-SMZPYJQI.js +0 -151
  152. package/dist/hooks-PABOEQO6.js +0 -24
  153. package/dist/init-4O24ZNUQ.js +0 -14
  154. package/dist/run-GZK3XJ62.js +0 -19
@@ -9,7 +9,7 @@ import {
9
9
  import {
10
10
  ArgumentError,
11
11
  one
12
- } from "./chunk-A4PKLESO.js";
12
+ } from "./chunk-Y6NFETNG.js";
13
13
 
14
14
  // src/git/worktrees/create.ts
15
15
  import { existsSync, symlinkSync } from "fs";
@@ -86,4 +86,4 @@ var worktreeCreate = (setup, context, report) => {
86
86
  export {
87
87
  worktreeCreate
88
88
  };
89
- //# sourceMappingURL=worktree-create-KMXPQXIQ.js.map
89
+ //# sourceMappingURL=worktree-create-FTSLMZWS.js.map
package/docs/commands.md CHANGED
@@ -3,7 +3,9 @@
3
3
  [Back to the overview](../README.md)
4
4
 
5
5
  Every pmcp command with its flags, behaviour and exit codes. `pmcp <command> --help` prints
6
- the same usage from the command itself.
6
+ the same usage from the command itself, with its subcommands and examples, and
7
+ `pmcp <command> <subcommand> --help` prints the usage, options and examples of one
8
+ subcommand, such as `pmcp harness group create --help` or `pmcp mailbox export --help`.
7
9
 
8
10
  ## The invocation a host uses
9
11
 
@@ -12,7 +14,7 @@ the same usage from the command itself.
12
14
  - `pmcp --root ./node_modules`: a leading option with no command is still a server, because
13
15
  hosts pass options without one.
14
16
 
15
- An unrecognised command does not fall through to a server the caller did not ask for. Only an empty argument list, or one that begins with an option, takes that path.
17
+ An unrecognised command does not fall through to a server the caller did not ask for. Only an empty argument list, or one that begins with an option `serve` accepts, takes that path. `-v`, `-V`, `--version` and `version` print the version; any other leading option, such as `-x` or a misspelled `--verison`, is an unknown option and exits 2 without reading standard input.
16
18
 
17
19
  ## status
18
20
 
@@ -20,7 +22,7 @@ An unrecognised command does not fall through to a server the caller did not ask
20
22
  pmcp status [--config <file>] [--json]
21
23
  ```
22
24
 
23
- 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 2 when projection or worktree ahead/behind drift exists or a budget limit is exceeded. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stderr; 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 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.
24
26
 
25
27
  ## init
26
28
 
@@ -51,21 +53,40 @@ pmcp hooks report --switch-check shell.heredoc [--since 2d] [--json]
51
53
 
52
54
  `report` summarises the guard lines the hook bundle writes to the project log at debug level (`[logging] level = "debug"`, or `PMCP_LOG=debug`). For each guard and runtime it counts the runs, what the guard found before its mode (`raw`: allow, deny, ask) and what the call got, the modes seen, the sessions, and the p50, p95 and longest durations. Sessions matching a `[hooks.report] exclude_sessions` regex (replays, smoke runs) are left out and counted. `--since` takes a duration such as `10m`, `2h` or `3d`, or an ISO time. `--switch-check <guard>` lists instead the calls that guard found something in and let through, because it was in `observe` or `warn`: what `deny` would have refused. The log holds no command, prompt or transcript text, so neither does the report. `--json` prints `{version, since?, lines, sessions, excluded, guards}`, or `{version, guard, refused}` with `--switch-check`.
53
55
 
54
- ## Read command JSON schemas
56
+ ## JSON output
55
57
 
56
- These opt-in snapshots write one JSON object and a newline to stdout, with `version: 1`. No color or human summary is mixed into stdout. Errors remain on stderr. Without the flag, existing human output is retained, including MCP status's original unversioned object and logs' JSONL stream. Schemas are named in [schemas.json](https://pmcp.build/commands/schemas.json); each entry under `schemas` uses the shared root `$defs`. Consumers must allow unknown fields inside session, decision and log records. Tokens are never part of an auth status object.
58
+ Every command that prints a result takes `--json` and then writes exactly one line to standard output, a JSON envelope, whether it succeeded or failed:
57
59
 
58
- | Command | Schema | Fields after version |
59
- | -------------------------- | ----------------- | --------------------------------------------------------------------- |
60
- | `status --json` | status | config, drift, features, projection, sessions, worktrees, mcp, errors |
61
- | `hooks list --json` | hooks-list | policies: runtime, event, policy, mode, source |
62
- | `hooks test --json` | hooks-test | runtime, event, payload, decision, policies, rendered |
63
- | `sessions status --json` | sessions-status | live, pause, leases, broadcasts with unseenBy session IDs |
64
- | `logs --json` | logs | records; filtered snapshot, incompatible with --follow and --pretty |
65
- | `git worktree list --json` | git-worktree-list | worktrees: path, main, optional alias, branch, behind and ahead |
66
- | `mcp status <name> --json` | mcp-status | name, present, expiresAt (UTC string or null), scopes |
60
+ ```json
61
+ {
62
+ "schema": "pmcp.hooks.list.v1",
63
+ "ok": true,
64
+ "data": { "version": 1, "policies": [] },
65
+ "errors": []
66
+ }
67
+ ```
68
+
69
+ - `schema` is `pmcp.<command>[.<subcommand>].v1`, such as `pmcp.status.v1`, `pmcp.git.worktree.list.v1` or `pmcp.models.v1`. A change that removes or retypes a field gets a new version.
70
+ - `ok` is true exactly when the exit code is 0 (see [Exit codes](#exit-codes)); `status` with drift prints its report with `ok: false` and exit 4.
71
+ - `data` is the command's result: the object the tables below describe, the array `models` lists, or `null` when the command failed before it had one.
72
+ - `errors` lists `{code, message}` for each error the command reported; `code` names the exit code (`failure`, `usage`, `missing_optional`, `differences`, `busy`). A usage error such as an unknown option still prints an envelope, with `data: null`.
73
+
74
+ No colour or human text is mixed into standard output; the same errors also go to standard error. Without `--json` every command prints human output (`mcp status` and the `tui` receipts included). `mailbox` and `harness` are machine protocols: they always print their own JSON receipts (`{ok, data}` and `{schemaVersion, ok, ...}`), take no `--json`, and are unchanged. `logs` without `--json` keeps its JSONL stream.
75
+
76
+ The `data` of these commands has a published schema in [schemas.json](https://pmcp.build/commands/schemas.json), with `version: 1` inside `data`; each entry under `schemas` uses the shared root `$defs`, and `envelope` describes the wrapper. Consumers must allow unknown fields inside session, decision and log records. Tokens are never part of an auth status object.
77
+
78
+ | Command | Schema | Fields after version |
79
+ | -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
+ | `status --json` | status | config, drift, features, projection, sessions, worktrees, mcp, errors |
81
+ | `hooks list --json` | hooks-list | policies: runtime, event, policy, mode, source |
82
+ | `hooks test --json` | hooks-test | runtime, event, payload, decision, policies, rendered |
83
+ | `sessions status --json` | sessions-status | live, pause, leases, broadcasts with unseenBy session IDs |
84
+ | `logs --json` | logs | records; filtered snapshot, incompatible with --follow and --pretty |
85
+ | `git worktree list --json` | git-worktree-list | worktrees: path, main, optional alias, branch, behind and ahead |
86
+ | `mcp status <name> --json` | mcp-status | name, present, expiresAt (UTC string or null), scopes |
87
+ | `heavy status --json` | heavy-status | schema `pmcp.heavy.status.v1`, enabled, dir, budget, running_weight, legacy_holder, host, lanes with running jobs, waiters, tickets, grace_24h, outside, skip |
67
88
 
68
- Feature rows have feature, enabled and source. Projection has drift, outputs and problems. Session snapshots include only live records; broadcasts include the IDs that have not yet seen each entry. Worktree counts are omitted when the upstream cannot be compared; absence does not assert equality. Status auth rows add a redacted error when credentials are unavailable or invalid. Errors are JSONL records with valid timestamps within the last hour, excluding future rows. Hooks test observations have policy, mode, decision, durationMs, skipped, source, verdict and reason; rendered has stdout and exitCode. The final decision includes runtime lowering, while each policy row retains its configured verdict. Mutating sessions, git and MCP verbs reject `--json`.
89
+ Feature rows have feature, enabled and source. Projection has drift, outputs and problems. Session snapshots include only live records; broadcasts include the IDs that have not yet seen each entry. Worktree counts are omitted when the upstream cannot be compared; absence does not assert equality. Status auth rows add a redacted error when credentials are unavailable or invalid. Errors are JSONL records with valid timestamps within the last hour, excluding future rows. Hooks test observations have policy, mode, decision, durationMs, skipped, source, verdict and reason; rendered has stdout and exitCode. The final decision includes runtime lowering, while each policy row retains its configured verdict. Heavy status jobs have pid, label, cwd, lane, weight, session, started, running_s, flags (grace, bypass, over_hold_warn, over_hold_max) and bypass_reason; waiters have pid, label, cwd, lane, weight, session, position, waited_s and eta_s (a rough estimate or null). It only reads: no record is pruned and nothing is written. Mutating sessions, git and MCP verbs reject `--json`.
69
90
 
70
91
  ## serve
71
92
 
@@ -142,9 +163,12 @@ Credentials and attachment files contain secrets and must stay outside source co
142
163
  pmcp project
143
164
  pmcp project --check [--smoke]
144
165
  pmcp project import-mcp --source codex:/path/to/config.toml
166
+ pmcp project exec-mcp remote
145
167
  ```
146
168
 
147
- Generate selected runtimes' native files from `pmcp.toml`. Unmanaged entries and credential references are preserved; conflicts stop the write. `--check` reports drift without writes, and MCP import previews changes by default; `--write` applies them. `--check --smoke` then runs the `[hooks.test] fixtures` file as `pmcp hooks test --fixtures` does, and exits 2 on any finding. [Configuration and guard examples](project-configuration.md).
169
+ `exec-mcp <alias>` is what a projected native entry runs to start a declared MCP server with its resolved environment, or, for `auth = "pmcp"`, the shared-auth proxy; you rarely run it by hand. See [shared remote MCP authentication](project-configuration.md#shared-remote-mcp-authentication).
170
+
171
+ Generate selected runtimes' native files from `pmcp.toml`. Unmanaged entries and credential references are preserved; conflicts stop the write. `--check` reports drift without writes (exit 4), and MCP import previews changes by default; `--write` applies them. `--check --smoke` then runs the `[hooks.test] fixtures` file as `pmcp hooks test --fixtures` does, and exits 4 on any finding. [Configuration and guard examples](project-configuration.md).
148
172
 
149
173
  Configuration files and the ownership lock are replaced atomically one file at a time. If projection is interrupted, inspect with `pmcp project --check`, then run `pmcp project` explicitly to repair drift. Projection does not start a runtime or replay terminal input. The complete set of files is not a single transaction.
150
174
 
@@ -182,15 +206,49 @@ pmcp git worktree list
182
206
  pmcp git worktree sync
183
207
  pmcp git deliver [<commit>...] [--during-pause] [--no-push] [--json]
184
208
  pmcp git sync
209
+ pmcp git affected --base <ref> [--head <ref>] [--tests-only] [--json]
185
210
  ```
186
211
 
187
- The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs its table; without it the command exits 1 and names the missing table.
212
+ The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs its table; without it, or without a `pmcp.toml`, the command exits 2 and names what is missing.
188
213
 
189
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.
190
215
  - `worktree list` prints alias, branch, behind/ahead and path for the main checkout and each linked worktree.
191
216
  - `worktree sync` moves the current worktree onto the mainline when that loses nothing; exit 1 when it is held back.
192
- - `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. Exit 0 delivered, gated with `--no-push`, or nothing to deliver; 1 refused, gate failed or attempts exhausted; 2 fetch failed or `--no-push` with the pre-push gate.
193
- - `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, 2 when blocked (undelivered edits) or the fetch failed. 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.
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.
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"`).
220
+
221
+ ## heavy
222
+
223
+ ```sh
224
+ pmcp heavy -- npm test
225
+ pmcp heavy --lane bulk --weight 3 -- npm run build:all
226
+ pmcp heavy --profile gate --weight 2 -- npm run typecheck
227
+ pmcp heavy --profile hook -- npm run lint:staged
228
+ pmcp heavy --now --reason "prod is down" -- npm run deploy
229
+ pmcp heavy status [--json]
230
+ pmcp heavy stats [--json]
231
+ ticket=$(pmcp heavy submit --lane bulk -- npm run build:all)
232
+ pmcp heavy result "$ticket"
233
+ pmcp heavy wait "$ticket" --timeout 1800
234
+ pmcp heavy cancel "$ticket" [--force]
235
+ pmcp heavy queue [--json]
236
+ pmcp heavy promote <id> --now --reason "release blocker"
237
+ pmcp heavy priority <id> gate --reason "blocks a land"
238
+ pmcp heavy priority <id> +2 --reason "the session waits on it"
239
+ ```
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, or with `PMCP_HEAVY_DISABLE=<reason>` set, the command runs at once. `--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, `--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.
242
+
243
+ ## wait
244
+
245
+ ```sh
246
+ pmcp wait --pid 4242
247
+ pmcp wait --until gone:/tmp/build.lock --until load-below:6 --timeout 900
248
+ pmcp wait --until no-process:"vitest run"
249
+ ```
250
+
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.
194
252
 
195
253
  ## completion
196
254
 
@@ -297,33 +355,47 @@ pmcp sync [--project <dir>] [--dry-run | --yes]
297
355
 
298
356
  `install` adds skill packages as dev dependencies with your own package manager, and what gets installed is checked against the digest the catalogue published — not its name and version, which any registry can claim. `sync` updates the ones already declared and removes nothing else. pmcp uses the free bundled public catalog by default and verifies immutable archives and installed resources without login. Explicit `--provider hosted` or `--api` selects a separate service's credentialed distribution, such as skills.modoo.today (see [login](#login--logout--whoami)).
299
357
 
300
- Both show the project and lockfile changes and stop: `--yes` approves them, `--dry-run` prints the plan and changes nothing.
358
+ Both show the project and lockfile changes and stop: `--yes` (`-y`) approves them, `--dry-run` prints the plan and changes nothing.
301
359
 
302
360
  ## Options
303
361
 
304
- | Option | Where | Effect |
305
- | ------------------ | ------------------------- | --------------------------------------------------------------------------------------------- |
306
- | `--root <dir>` | `serve`, `list`, `index` | a `node_modules` directory to walk; repeatable, and the first one wins on a duplicate package |
307
- | `--scope <prefix>` | `serve`, `list`, `index` | only packages whose names start with this; repeatable, matched with a plain prefix test |
308
- | `--model <id>` | `index`, `serve` | the encoder to use; rows from another model are never scored |
309
- | `--json` | `list`, `index`, `models` | emit JSON on standard output rather than a table or a summary |
310
- | `--help`, `-h` | anywhere | the help for that command, generated from the command itself |
311
- | `--version` | on its own | the version, on standard output |
362
+ | Option | Where | Effect |
363
+ | ---------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
364
+ | `--root <dir>` | `serve`, `list`, `index`, `validate`, `project` | a `node_modules` directory to walk; repeatable, and the first one wins on a duplicate package |
365
+ | `--scope <prefix>` | `serve`, `list`, `index`, `validate`, `project` | only packages whose names start with this; repeatable, matched with a plain prefix test |
366
+ | `--config <file>` | every command that reads `pmcp.toml` | a `pmcp.toml` to read instead of the nearest one at or above the working directory |
367
+ | `--model <id>` | `index`, `serve` | the encoder to use; rows from another model are never scored |
368
+ | `--json` | every command that prints a result; `pmcp <command> --help` lists it | emit JSON on standard output rather than a table or a summary |
369
+ | `-y`, `--yes` | `install`, `sync`, `tui` | approve the displayed changes, or the first runtime start, without a prompt |
370
+ | `-q`, `--quiet` | anywhere | silence diagnostics and progress on standard error, except errors; results on standard output still print |
371
+ | `--color`, `--no-color` | anywhere | always or never colour; without either, `FORCE_COLOR` (`0` off, anything else on) wins over `NO_COLOR`, `TERM=dumb` and the terminal test |
372
+ | `--help`, `-h` | anywhere | the help for that command or subcommand, generated from the command itself: usage, subcommands, the options that apply and examples |
373
+ | `-v`, `-V`, `--version`, `version` | on its own | the version, on standard output |
374
+
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
+
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.
312
378
 
313
379
  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.
314
380
 
381
+ An unknown command, subcommand or option exits 2 with one line naming it, the closest valid name when one is near (`unknown command "stauts"; did you mean "status"?`), and where to look next (`Run pmcp status --help for its usage.`), rather than the whole help. An unknown subcommand also lists every valid one. `pmcp help <command>` for a command that does not exist is the same error. Every command that needs a `pmcp.toml` and finds none says so the same way and suggests `pmcp init`.
382
+
315
383
  ## Exit codes
316
384
 
317
- | Code | Means | For example |
318
- | ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
319
- | `0` | it did what you asked | skills listed, or the whole catalog indexed |
320
- | `1` | it ran and found a problem | no skills under those roots, a partial index, no SQLite in this runtime to store vectors in, a refused or failed `git deliver` |
321
- | `2` | the arguments were unusable, or a check found drift | an unknown command, an unknown option, a missing value; `project --check` drift, stale or undeclared outputs; a `git` fetch that failed or a sync blocked by undelivered edits |
322
- | `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
385
+ Every command uses one table, so a script can branch on the code alone:
386
+
387
+ | Code | Means | For example |
388
+ | ---- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
389
+ | `0` | it did what you asked | skills listed, the whole catalog indexed, nothing to deliver |
390
+ | `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
+ | `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
+ | `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
393
+ | `4` | a check ran and found differences | `status` drift or an exceeded budget, `project --check` drift, stale or undeclared outputs, a `hooks test --fixtures` or `--smoke` finding |
394
+ | `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` |
323
395
 
324
- The distinction between 1 and 3 is worth wiring into a script: 1 says the project is not what you expected, and 3 says the machine is missing something optional and the server still works without it.
396
+ 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).
325
397
 
326
- **Data on stdout, everything else on stderr.** The JSON from `--json` and the string from `--version` go to standard output so they can be piped. Tables, help and messages go to standard error, which is what keeps a pipeline's input clean.
398
+ **Results on stdout, diagnostics on stderr.** What you asked for goes to standard output: the JSON from `--json`, the version, requested help, and the human result of a read (the `list`, `models`, `marketplace list` and `doctor` tables, `validate` findings, the `status` summary, `hooks` and `sessions` listings, an `install` or `sync` plan). So `pmcp list | grep react` and `pmcp list > skills.txt` work, and `-q` never erases a result. Progress, summaries such as "144 skills", warnings, hints and errors go to standard error. Before 0.23.0, human tables and help went to standard error; see [Upgrading](upgrading.md).
327
399
 
328
400
  ## Runtime
329
401
 
@@ -84,6 +84,15 @@ delivery that holds the lock waits until the load is below it before the gate st
84
84
  checking every 15 seconds for up to `load_wait_seconds` (default `1800`), and then
85
85
  fails without running the gate; once started, a gate is never retried.
86
86
 
87
+ Deliver never takes the [host lease](project-configuration.md#host-lease):
88
+ replay, gate tree preparation, hooks and the push run without it, so a land never
89
+ queues behind other sessions' builds and never holds the gate lock while it
90
+ waits for capacity. The gate puts only its test stages under `pmcp heavy
91
+ --profile gate [--weight N] -- <command>`, which queue first, in the gate lane.
92
+ When such a stage gives up (exit 75), a gate command that exits 75 makes
93
+ `pmcp git deliver` stop with "gate not run: host busy, nothing pushed, retry
94
+ later" and exit 75.
95
+
87
96
  One delivery gates at a time: pmcp takes an exclusive `flock` on the file `lock`
88
97
  beside the gate tree (`<dir of tree>/lock`), so another tool that takes the same
89
98
  file with `flock` (a project's own landing script, say) and pmcp never gate together. With
@@ -195,6 +204,48 @@ branch (`branch` in `.gitmodules`, else `main`) as a fast-forward, never a later
195
204
  commit; if that branch has moved past the pin's base, delivery stops before
196
205
  anything else moves.
197
206
 
207
+ ## Affected members
208
+
209
+ `pmcp git affected --base <ref> [--head <ref>] [--tests-only] [--json]` maps the delta
210
+ `<base>...<head>` to the workspace members it touches, so a gate checks in proportion to the
211
+ change. It prints one member directory per line, or the single line `ALL`, and names each
212
+ changed file no member reads on stderr as `unmapped, not tested: <path>`. It always exits 0
213
+ with an answer and answers `ALL` (fail closed) when the base or head does not resolve, the
214
+ base equals the head, the root manifest or lockfile does not parse, or `[git.affected]` is
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.
217
+
218
+ `[git.affected]` describes the workspace; every key is optional:
219
+
220
+ | Key | Type | Default | Meaning |
221
+ | ------------------ | ------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
222
+ | `members` | `"workspaces"` | `"workspaces"` | Members are the directories the root `package.json` `workspaces` globs (or `workspaces.packages`) match; the last matching glob decides, so `!glob` excludes. |
223
+ | `shared_inputs` | globs | `[]` | A changed path matching one selects `ALL`. |
224
+ | `readers` | table: glob to members | `{}` | Members that read a path outside themselves which no adapter can derive (a test reading a file by path). The path counts as mapped. |
225
+ | `derive` | `"tsconfig"`, `"vitest"` | `[]` | Compute readers instead of listing them: files outside every member that a member's `tsconfig*.json` extends chain (relative or through a member package) or vitest config imports. |
226
+ | `owners` | table: glob to member | `{}` | Map a directory without a manifest to the member that runs it, before walking up to the nearest member. |
227
+ | `include` | globs, `!` excludes | `["**"]` | Paths that map to a member at all; a path outside `include` is neither selected nor reported. |
228
+ | `include_deleted` | globs | `[]` | A deleted path maps only when it matches here; deleting a file cannot break its member. |
229
+ | `ignore` | globs | `[]` | Paths read by no member: never selected, never reported. |
230
+ | `on_member_change` | members | `[]` | Selected when a member manifest is added or removed (suites that assert something about the whole workspace). |
231
+ | `unmapped` | `"all"`, `"report"` | `"all"` | What an included path outside every member and reader does: widen to `ALL`, or only be reported. |
232
+ | `consumers` | boolean | `false` | Add every member that depends on a selected one (typecheck semantics). `--tests-only` prints the selection without them. |
233
+
234
+ `[git.affected.lockfile]` reads the package manager's lockfile at both revisions when it or the
235
+ root `package.json` changed, and selects the members whose resolved dependencies moved, with
236
+ their consumers. `adapter = "bun"` is the one implemented. `toolchain` lists package names (a
237
+ trailing `*` matches a prefix) every member builds with: a change to one selects `ALL`, as does a
238
+ root field outside the dependency fields and `inert_root_fields` (default `scripts`,
239
+ `description`, `version`) or a lockfile that does not parse.
240
+
241
+ Consumer edges are a member's `dependencies`, `peerDependencies` and `optionalDependencies`, the
242
+ `devDependencies` its production source under `src/` imports (all of them when its
243
+ `tsconfig.json` `exclude` names no tests), the member whose tsconfig preset it extends, and
244
+ relative imports from `src/` that leave the package.
245
+
246
+ `node scripts/affected-shadow.mjs` compares this answer with a project's own selector over
247
+ recent commits in a disposable clone before a gate switches to it.
248
+
198
249
  ## Shared file formats
199
250
 
200
251
  Delivery and sync coordinate through plain files, so any tool, a project's own
package/docs/hooks.md CHANGED
@@ -41,7 +41,14 @@ where they apply: declared `[git]` features detect git (`enabled = "auto"`), and
41
41
  logging falls back to its defaults rather than to no logging. The bundle is
42
42
  projected only when `[hooks]` declares guards or checks, a `[sessions.*]`
43
43
  feature table is declared, `[git.shared_checkout]` or `[git.worktrees.sync]` is
44
- declared, or `[git.mainline.deliver]` keeps `refuse_direct_push`.
44
+ declared, `[git.mainline.deliver]` keeps `refuse_direct_push`, or
45
+ `[host.lease]` lists `heavy` commands.
46
+
47
+ The `host.lease` guard holds agents to the [host lease](project-configuration.md#host-lease):
48
+ a shell step whose argv starts with a `[host.lease] heavy` prefix and is not
49
+ wrapped in `pmcp heavy --` is reported, in the mode `[host.lease] guard` names
50
+ (`observe` by default; `deny` refuses with the wrapped command to run instead).
51
+ A step that sets `PMCP_HEAVY_DISABLE=<reason>` passes.
45
52
 
46
53
  ## `[hooks]`
47
54
 
@@ -240,8 +247,8 @@ hook does not look at the repository being committed. Findings:
240
247
  - `[hooks.failure]` differing from the fixtures' `failure`;
241
248
  - a target whose native hook entry is missing, and a run in which no case ran.
242
249
 
243
- `hooks test --fixtures` exits 0 with no finding and 1 otherwise; `project --check
244
- --smoke` exits 2 on a finding, as for drift.
250
+ `hooks test --fixtures` and `project --check --smoke` exit 0 with no finding and 4
251
+ otherwise, as for drift.
245
252
 
246
253
  ## `[hooks.failure]`
247
254
 
@@ -295,7 +302,7 @@ as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
295
302
  ## Native hook entries pmcp does not own
296
303
 
297
304
  Hook entries a project or a tool wrote itself run beside pmcp's, and a broken one
298
- fails every call it matches. `pmcp project --check` (exit 2) and `pmcp doctor`
305
+ fails every call it matches. `pmcp project --check` (exit 4) and `pmcp doctor`
299
306
  check each such entry in `.claude/settings.json`, `.claude/settings.local.json`,
300
307
  `.codex/hooks.json`, and the `hooks/hooks.json` (or the manifest's `hooks` path)
301
308
  of each plugin whose `.claude-plugin/plugin.json` is tracked by git. Entries that
@@ -51,24 +51,25 @@ Every table pmcp reads, and where it is described. An unknown key inside one
51
51
  of these tables is an error unless noted; an unknown top-level table is
52
52
  ignored.
53
53
 
54
- | Table | Section |
55
- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
56
- | `[catalog]`, `[catalog.validation]` | [Project config](#project-config) |
57
- | `[embedding]`, `[embedding.encoder]` | [Embedding models](embeddings.md) |
58
- | `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
59
- | `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
60
- | `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
61
- | `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]` | [Hooks](hooks.md) |
62
- | `[budget]` | [Budget](#budget) |
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) |
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
- | `[logging]`, `[logging.components]` | [Logging](#logging) |
67
- | `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
68
- | `[ui.claude]` | [Claude session panes](#claude-session-panes) |
69
- | `[tui]`, `[mailbox]` | [Terminal workspace](terminal-workspace.md) |
70
- | `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]` | [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts) |
71
- | `[harness]` | [Terminal harness](terminal-harness.md#create-a-group-and-its-sessions) |
54
+ | Table | Section |
55
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
56
+ | `[catalog]`, `[catalog.validation]` | [Project config](#project-config) |
57
+ | `[embedding]`, `[embedding.encoder]` | [Embedding models](embeddings.md) |
58
+ | `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
59
+ | `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
60
+ | `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
61
+ | `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]` | [Hooks](hooks.md) |
62
+ | `[budget]` | [Budget](#budget) |
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) |
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
+ | `[logging]`, `[logging.components]` | [Logging](#logging) |
67
+ | `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
68
+ | `[ui.claude]` | [Claude session panes](#claude-session-panes) |
69
+ | `[tui]`, `[mailbox]` | [Terminal workspace](terminal-workspace.md) |
70
+ | `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]` | [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts) |
71
+ | `[host.lease]`, `[host.lease.lanes]`, `[host.lease.weights]`, `[[host.lease.commands]]`, `[host.lease.profiles.<name>]`, `[host.lease.io]`, `[host.lease.io.weights]`, `[host.lease.io.max]` | [Host lease](#host-lease) |
72
+ | `[harness]` | [Terminal harness](terminal-harness.md#create-a-group-and-its-sessions) |
72
73
 
73
74
  ## Marketplaces
74
75
 
@@ -129,7 +130,7 @@ args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
129
130
 
130
131
  ```sh
131
132
  pmcp project # write
132
- pmcp project --check # exit 2 on drift, stale or undeclared outputs
133
+ pmcp project --check # exit 4 on drift, stale or undeclared outputs
133
134
  pmcp project add <name> # copy a catalog skill or agent into .agents/
134
135
  pmcp project remove <name>
135
136
  pmcp doctor # ask each installed tool what it loads
@@ -256,6 +257,118 @@ boundary, since any process running as you can write the approvals directory
256
257
  directly. A real boundary needs the approvals stored under a different user or
257
258
  owned by root.
258
259
 
260
+ ## Host lease
261
+
262
+ `[host.lease]` configures the host-wide budget behind
263
+ [`pmcp heavy`](commands.md#heavy): heavy commands (installs, test suites,
264
+ typechecks, builds, gates) from every session and worktree on the host start
265
+ only while their lane has a free slot, their weight fits what the running jobs
266
+ leave of the budget, and the host is under its load and IO limits. It trades
267
+ throughput for stability: a queued job waits instead of overflowing memory or
268
+ IO beside the others. Turn it off (`enabled = false`) on a host that runs one
269
+ session at a time or has room for every job at once; keep it on where several
270
+ agents share one machine. It is on by default, also without the table.
271
+
272
+ ```toml
273
+ [host.lease]
274
+ max_load = 8
275
+ max_io = 8
276
+ budget = 4
277
+ hold_warn = 1800
278
+ hold_max = 3600
279
+ heavy = [["npm", "install"], ["npm", "test"], ["cargo", "build"]]
280
+ guard = "deny"
281
+
282
+ [host.lease.lanes]
283
+ interactive = 2
284
+
285
+ [[host.lease.commands]]
286
+ argv = ["npm", "install"]
287
+ lane = "bulk"
288
+ weight = 3
289
+
290
+ [host.lease.profiles.gate]
291
+ max_wait = 2700
292
+ load_grace = 600
293
+ ```
294
+
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
+ | `max_load` | number | the CPU count | A job starts only while the 1-minute load average is below this. |
309
+ | `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. |
310
+ | `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. |
311
+ | `max_wait` | seconds | `3600` | How long the `default` profile waits; then nothing runs and the exit is 75. |
312
+ | `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. |
313
+ | `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. |
314
+ | `hold_warn` | seconds | `1800` | A job running past this prints one warning, and `pmcp heavy status` marks it. |
315
+ | `hold_max` | seconds | none | `pmcp heavy status` flags a job past this as over the limit. Nothing is killed. |
316
+ | `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. |
317
+ | `heartbeat`, `poll` | seconds | `60`, `15` | How often a waiter prints that it is still waiting, and how often the host is reread. |
318
+ | `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. |
319
+ | `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. |
320
+ | `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. |
321
+ | `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. |
322
+ | `io.weights.<lane>` | integer | gate 500, hook 300, interactive 100, bulk 25 | The scope's `io.weight` per lane (1 to 10000). |
323
+ | `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. |
324
+ | `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. |
325
+ | `usage_cap` | bytes | `5000000` | `usage.jsonl` (one record per run) moves to `usage.jsonl.1` past this size. |
326
+
327
+ Lanes, in the order a short budget goes to them: `gate` (a land's gate),
328
+ `hook` (commit-hook work, a short slot that skips the host wait unless the host
329
+ is past `hard_factor`), `interactive` (the tests, builds and
330
+ typechecks a session waits on now, the default) and `bulk` (batch runs,
331
+ experiments, bootstraps, installs). Within a lane the oldest waiter goes first,
332
+ and the first waiter the remaining budget cannot fit holds back the ones behind
333
+ it, so a heavy job is not starved by lighter ones. Admission and release happen
334
+ under a short lock beside the records, and dead processes' records are dropped
335
+ on every admission, so running weight never exceeds the budget and a crashed
336
+ job frees its share.
337
+
338
+ `pmcp heavy --now --reason <text>` (or `PMCP_HEAVY_NOW=<reason>` in a script) is
339
+ the emergency bypass: the command starts at once, outside the lanes, the budget
340
+ and the host check, and never exits 75, but it needs a reason, is logged as a
341
+ `bypass` line, shows as `bypass running` in status and counts its weight, so the
342
+ other jobs' admission sees its load. It is not the off switch below.
343
+
344
+ Every run appends one record to `usage.jsonl` beside the lease files: the
345
+ command's signature (the program and the lower-case words before its first
346
+ option, path or value; never argument values or the environment), the package
347
+ directory relative to the project, lane, weight, how it started (queue, grace,
348
+ bypass), exit code, wall time, user and system CPU time, peak RSS and bytes read
349
+ and written. CPU time comes from the reaped process tree; peak RSS and IO come
350
+ from the job's cgroup when it runs in a scope, else from `/proc` sampled once a
351
+ second. `pmcp heavy stats` summarises them per signature. The weights are still
352
+ the configured ones.
353
+
354
+ `PMCP_HEAVY_DISABLE=<reason>` is the one way to run without the lease for a
355
+ single command or a whole shell (a test suite, an emergency): `pmcp heavy`
356
+ runs at once and logs the reason, and the guard lets a command that sets it
357
+ pass. `enabled = false` is the switch for a host or project that does not
358
+ want the lease at all.
359
+
360
+ The files extend those of a shell wrapper that takes the same lock with
361
+ `flock`: records hold `key=value` lines (`pid`, `since`, `started`, `cwd`,
362
+ `label`, then pmcp's `lane`, `weight`, `queued`, `session`), and `heavy.log` has
363
+ one tab-separated line per event (`<UTC time>`, `<pid>`,
364
+ `acquired|released|timeout|grace|skip`, `<details>`), pmcp appending to the
365
+ details only. Each running pmcp job holds the lock file shared, so a wrapper
366
+ holding it exclusively counts as the whole budget, and a wrapper waits until no
367
+ pmcp job runs. Point `dir`, `legacy_marker_env` and `legacy_skip_env` at such a
368
+ wrapper's values and the two exclude each other while both are in use. A
369
+ wrapper does not join the lanes, so the order and the budget are complete only
370
+ once every caller uses `pmcp heavy`.
371
+
259
372
  ## Browser and desktop for agents
260
373
 
261
374
  pmcp-browser and pmcp-desktop, and how to declare them: [Browser and desktop](browser-and-desktop.md).
@@ -609,7 +722,7 @@ Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-w
609
722
  ## Budget
610
723
 
611
724
  `[budget]` sets limits on what every agent session loads and on paths the
612
- project keeps out of its tree. `pmcp project --check` exits 2 when one is
725
+ project keeps out of its tree. `pmcp project --check` exits 4 when one is
613
726
  exceeded, naming each, and `pmcp status` shows the measurements beside the
614
727
  limits (its JSON gains `budget: {rows, problems}`, and an exceeded limit counts
615
728
  as drift). Every key is optional; nothing is checked without the table.
@@ -776,6 +889,9 @@ notice_paths = ["AGENTS.md", "pmcp.toml"]
776
889
 
777
890
  [git.submodules]
778
891
 
892
+ [host.lease]
893
+ heavy = [["npm", "install"], ["npm", "test"]]
894
+
779
895
  [logging]
780
896
  level = "warn"
781
897