@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.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/.mcp.json +1 -1
- package/dist/affected-D6FRJPPI.js +836 -0
- package/dist/{apply-LPKZZ6EL.js → apply-3PWUO4J5.js} +27 -22
- package/dist/{available-BFXLII4A.js → available-74CMIBPD.js} +9 -9
- package/dist/{broadcast-DZGMSZRG.js → broadcast-VKZY7WSD.js} +6 -5
- package/dist/chunk-2GZKA33O.js +173 -0
- package/dist/chunk-2HL2MFNI.js +159 -0
- package/dist/{chunk-OAX6MIOZ.js → chunk-2K4WYN4C.js} +2 -2
- package/dist/{chunk-PEMMV5YQ.js → chunk-2MX5C7B2.js} +3 -3
- package/dist/{chunk-7I7O7ZNT.js → chunk-3V37OZQH.js} +5 -3
- package/dist/chunk-43MXRTKH.js +134 -0
- package/dist/chunk-4VVQLWTS.js +93 -0
- package/dist/{chunk-DYZVHO2L.js → chunk-5HNLHI5F.js} +2 -2
- package/dist/{chunk-JEL35P7S.js → chunk-5NDUWEMW.js} +2 -2
- package/dist/chunk-65BW7Y6O.js +40 -0
- package/dist/{chunk-HUBJWC7T.js → chunk-6NRLBSEG.js} +7 -7
- package/dist/chunk-6QJ3F445.js +166 -0
- package/dist/{chunk-2OOWAGBE.js → chunk-72V6U7CZ.js} +3 -3
- package/dist/{chunk-RPCIROW7.js → chunk-7CHUMF3E.js} +2 -2
- package/dist/{chunk-INT7QLEU.js → chunk-7DJQASH3.js} +25 -6
- package/dist/chunk-7IRXUPM2.js +7 -0
- package/dist/{chunk-UDVYVRGJ.js → chunk-DNSHJIS4.js} +2 -2
- package/dist/{chunk-UMQLIRSU.js → chunk-DZTSCJOZ.js} +3 -3
- package/dist/{chunk-KEHB4FZP.js → chunk-E2E4HIEN.js} +49 -3
- package/dist/{chunk-SUJCVEBM.js → chunk-EQF64INS.js} +3 -3
- package/dist/chunk-F3R5HEUB.js +39 -0
- package/dist/chunk-FOLA4EUJ.js +261 -0
- package/dist/chunk-FQLCD4HU.js +24 -0
- package/dist/{chunk-OEH47H6A.js → chunk-GUHOEIHP.js} +3 -20
- package/dist/{chunk-B2WRYGHJ.js → chunk-HES44LTA.js} +5 -5
- package/dist/{chunk-RHJEGLYM.js → chunk-HF5D6B2U.js} +45 -6
- package/dist/{chunk-R5MT42JS.js → chunk-HYXOJYVR.js} +2 -2
- package/dist/chunk-JANBBPKP.js +50 -0
- package/dist/{chunk-ITOTOC6Y.js → chunk-JJFPSFDU.js} +3 -3
- package/dist/{chunk-XNML2KIC.js → chunk-JPYQDOEW.js} +3 -3
- package/dist/{chunk-SPZQRLL5.js → chunk-KYGGQPAH.js} +18 -6
- package/dist/{chunk-EX4YXPVW.js → chunk-LGRFYN5T.js} +2 -2
- package/dist/{chunk-DP326AER.js → chunk-LO54UUDE.js} +2 -2
- package/dist/{chunk-5QKXEWDB.js → chunk-MHKY6TNF.js} +6 -4
- package/dist/chunk-N7ANFMA5.js +171 -0
- package/dist/{chunk-KPKMEUUH.js → chunk-OGCJO6HQ.js} +9 -8
- package/dist/{chunk-N63QCJHX.js → chunk-P25V6NEX.js} +5 -5
- package/dist/{chunk-PUIWESU3.js → chunk-Q6V274OB.js} +8 -6
- package/dist/chunk-QR6A3TYP.js +315 -0
- package/dist/{chunk-EIDIVIAD.js → chunk-QYLOIM4U.js} +9 -2
- package/dist/{chunk-MIFPPUWY.js → chunk-RRKA3GF5.js} +4 -4
- package/dist/{chunk-7CSUKCU7.js → chunk-RZYZILU4.js} +17 -96
- package/dist/{chunk-FODUHLZM.js → chunk-SDQYZDHS.js} +2 -2
- package/dist/chunk-SGFTHKKS.js +86 -0
- package/dist/chunk-T6C3TSTO.js +99 -0
- package/dist/chunk-UVTGY2R3.js +78 -0
- package/dist/{chunk-LLT5FQBE.js → chunk-VBVNOLRR.js} +7 -3
- package/dist/{chunk-ABTJQ4QV.js → chunk-WBPVNCQO.js} +20 -5
- package/dist/{chunk-63RZGEVI.js → chunk-WQBKQTNT.js} +98 -26
- package/dist/{chunk-YGOWIJPE.js → chunk-WZYGM3FR.js} +6 -2
- package/dist/chunk-Y6NFETNG.js +232 -0
- package/dist/{chunk-D5MIZM6L.js → chunk-YRNFMPZB.js} +7 -8
- package/dist/{chunk-2GRECE6B.js → chunk-ZXMECZBI.js} +4 -4
- package/dist/{cli-34EDFXJA.js → cli-GFDT4YXM.js} +14 -15
- package/dist/{cli-JXPJFHUA.js → cli-YWV7FLYO.js} +24 -12
- package/dist/cli.js +317 -51
- package/dist/{completion-KTECNPVY.js → completion-OKGNN7DE.js} +25 -21
- package/dist/{diagnostics-I5VZHK42.js → diagnostics-N4XRRCQG.js} +10 -6
- package/dist/{doctor-JJ2VUNHT.js → doctor-3H6UYNEA.js} +27 -23
- package/dist/{entry-OT7BN3ID.js → entry-KDLLG6ED.js} +19 -15
- package/dist/{exec-mcp-3E4SRJUY.js → exec-mcp-AENALAHJ.js} +15 -11
- package/dist/{harness-Q236VJSU.js → harness-GRYTNUF2.js} +26 -44
- package/dist/harness-launch-gate.js +8 -4
- package/dist/harness-worker.js +10 -6
- package/dist/heavy-BGXKJKYB.js +1965 -0
- package/dist/hook-body.js +69 -21
- package/dist/hooks-V25ANQ4Q.js +24 -0
- package/dist/{host-LT5JMUFJ.js → host-4EGPADOJ.js} +11 -7
- package/dist/{host-UDC4HVX3.js → host-MLSWY7D7.js} +24 -17
- package/dist/{host-run-LD63JGN7.js → host-run-VI52IUKF.js} +10 -6
- package/dist/http.js +1 -1
- package/dist/{import-mcp-URVONIZ3.js → import-mcp-FIXFLUDM.js} +18 -14
- package/dist/index.d.ts +1 -1
- package/dist/index.js +17 -12
- package/dist/init-ALTBFUPP.js +14 -0
- package/dist/{install-7V6NIA7W.js → install-5JH4DSFF.js} +10 -10
- package/dist/{invoke-JW5OC2HO.js → invoke-7T7UY57O.js} +12 -8
- package/dist/{list-UM4DYJRL.js → list-JFZ7UZLV.js} +18 -14
- package/dist/{list-WK2IYUK7.js → list-LV5EKCF6.js} +11 -7
- package/dist/{logout-H5X4D26I.js → logout-7CNBO76Z.js} +15 -11
- package/dist/{logs-UHJM7ZCL.js → logs-2JEMSNSG.js} +11 -10
- package/dist/{mailbox-NIMBOQPA.js → mailbox-5FVFMQ2J.js} +12 -44
- package/dist/{mailbox-YN6PG66A.js → mailbox-ZHZWZMAY.js} +14 -21
- package/dist/{mainline-74WCH4T4.js → mainline-6PBT3VNR.js} +75 -126
- package/dist/{marketplace-G4VQET5W.js → marketplace-2X3OOEPW.js} +10 -9
- package/dist/{mcp-6P3MVT4V.js → mcp-MVQVMAKJ.js} +4 -4
- package/dist/{mcp-AXHV547W.js → mcp-PBTQ5SJW.js} +2 -2
- package/dist/{models-ISU4DCMA.js → models-XSF45MCD.js} +9 -5
- package/dist/{pause-CBZ3BTJL.js → pause-CMZOIHTJ.js} +6 -5
- package/dist/{preview-DT7DWG5F.js → preview-465CQJBQ.js} +4 -4
- package/dist/{project-6QUIC73W.js → project-FZGJRG2U.js} +14 -12
- package/dist/{reindex-I7RYWCUR.js → reindex-D62HQAN2.js} +7 -7
- package/dist/{report-ZHOHQ4PZ.js → report-UB7MXAUB.js} +14 -13
- package/dist/{resume-UJEWQ66P.js → resume-PAKIT4TT.js} +6 -5
- package/dist/{run-HQTB7N2R.js → run-TOP37ZQC.js} +14 -10
- package/dist/run-VGJDMA2O.js +23 -0
- package/dist/{serve-APEVIJD2.js → serve-LR7SJHNH.js} +13 -13
- package/dist/{session-YZVX4NGN.js → session-3YVVO2GR.js} +6 -6
- package/dist/{setup-SOUBEZ3H.js → setup-6AQUOWOH.js} +7 -4
- package/dist/{smoke-2FI5D74B.js → smoke-6X6IXQIQ.js} +4 -4
- package/dist/{start-login-ER7DEGYN.js → start-login-X37KGCCB.js} +16 -12
- package/dist/{status-KN2ZE64O.js → status-4PYPTYUB.js} +7 -6
- package/dist/{status-7NYXRZ3R.js → status-E4AFUOQO.js} +24 -13
- package/dist/{status-OGABWCPO.js → status-LBRK37GA.js} +35 -30
- package/dist/stdio.js +2 -2
- package/dist/{sweep-EPZCW63Q.js → sweep-VURZU6DI.js} +6 -5
- package/dist/{test-WRZQERYC.js → test-D2EEFUN2.js} +18 -14
- package/dist/{tui-YUHQ36FC.js → tui-D7E3MD3X.js} +45 -19
- package/dist/{unbroadcast-N6LXHAMT.js → unbroadcast-7AMLURCG.js} +6 -5
- package/dist/{validate-KFBCUFI4.js → validate-YXR7FJJX.js} +11 -9
- package/dist/wait-HEODT7KV.js +141 -0
- package/dist/{worker-OKBJNDEI.js → worker-WTBC6VYO.js} +12 -8
- package/dist/{worktree-create-KMXPQXIQ.js → worktree-create-FTSLMZWS.js} +2 -2
- package/docs/commands.md +108 -36
- package/docs/git-workflow.md +51 -0
- package/docs/hooks.md +11 -4
- package/docs/project-configuration.md +136 -20
- package/docs/terminal-workspace.md +2 -0
- package/docs/upgrading.md +54 -0
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +5 -5
- package/plugin.json +1 -1
- package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/plugin.json +1 -1
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +1 -1
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +1 -1
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +3 -2
- package/skills/headless-agents-ci-scaffold/SKILL.md +1 -1
- package/skills/pmcp-project-init/SKILL.md +1 -1
- package/skills/pmcp-sessions-and-git/SKILL.md +3 -2
- package/dist/chunk-2P4Z2NUX.js +0 -28
- package/dist/chunk-3C5FVHQ3.js +0 -7
- package/dist/chunk-3Y3HDMHA.js +0 -108
- package/dist/chunk-A4PKLESO.js +0 -112
- package/dist/chunk-E3DQB5LS.js +0 -48
- package/dist/chunk-GFOQDLPL.js +0 -35
- package/dist/chunk-JWRZDYB5.js +0 -59
- package/dist/chunk-LMUBBIE2.js +0 -83
- package/dist/chunk-SMZPYJQI.js +0 -151
- package/dist/hooks-PABOEQO6.js +0 -24
- package/dist/init-4O24ZNUQ.js +0 -14
- package/dist/run-GZK3XJ62.js +0 -19
|
@@ -9,7 +9,7 @@ import {
|
|
|
9
9
|
import {
|
|
10
10
|
ArgumentError,
|
|
11
11
|
one
|
|
12
|
-
} from "./chunk-
|
|
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-
|
|
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
|
|
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
|
-
##
|
|
56
|
+
## JSON output
|
|
55
57
|
|
|
56
|
-
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
305
|
-
|
|
|
306
|
-
| `--root <dir>`
|
|
307
|
-
| `--scope <prefix>`
|
|
308
|
-
| `--
|
|
309
|
-
| `--
|
|
310
|
-
| `--
|
|
311
|
-
| `--
|
|
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
|
-
|
|
318
|
-
|
|
319
|
-
|
|
|
320
|
-
|
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
|
package/docs/git-workflow.md
CHANGED
|
@@ -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,
|
|
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`
|
|
244
|
-
|
|
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
|
|
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
|
|
55
|
-
|
|
|
56
|
-
| `[catalog]`, `[catalog.validation]`
|
|
57
|
-
| `[embedding]`, `[embedding.encoder]`
|
|
58
|
-
| `[marketplaces.<name>]`
|
|
59
|
-
| `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]`
|
|
60
|
-
| `[mcp.<alias>]`
|
|
61
|
-
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]`
|
|
62
|
-
| `[budget]`
|
|
63
|
-
| `[[hooks.shell]]`, `[[hooks.edit]]`
|
|
64
|
-
| `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]`
|
|
65
|
-
| `[git]`, `[git.shared_checkout]`, `[git.worktrees]`, `[git.worktrees.sync]`, `[git.mainline]`, `[git.mainline.gate]`, `[git.mainline.deliver]`, `[git.mainline.sync]`, `[git.submodules]`
|
|
66
|
-
| `[logging]`, `[logging.components]`
|
|
67
|
-
| `[permissions.claude]`
|
|
68
|
-
| `[ui.claude]`
|
|
69
|
-
| `[tui]`, `[mailbox]`
|
|
70
|
-
| `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]`
|
|
71
|
-
| `[
|
|
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
|
|
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
|
|
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
|
|