@modootoday/pmcp 0.17.4 → 0.18.2

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 (272) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +2 -2
  4. package/.mcp.json +1 -1
  5. package/CHANGELOG.md +152 -0
  6. package/CONTRIBUTING.md +71 -0
  7. package/README.md +98 -201
  8. package/SECURITY.md +17 -1
  9. package/dist/apply-JUTGS5WZ.js +242 -0
  10. package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
  11. package/dist/available-DBSIVVJ6.js +73 -0
  12. package/dist/broadcast-CBMVOV3G.js +18 -0
  13. package/dist/chunk-26WLNWDG.js +93 -0
  14. package/dist/chunk-2FIV63WC.js +252 -0
  15. package/dist/chunk-2P4Z2NUX.js +28 -0
  16. package/dist/chunk-34DECPVC.js +22 -0
  17. package/dist/chunk-3FCFAQDG.js +42 -0
  18. package/dist/chunk-3IDXEV5E.js +1934 -0
  19. package/dist/chunk-3PW4FI7U.js +32 -0
  20. package/dist/chunk-3Y3HDMHA.js +108 -0
  21. package/dist/chunk-47O3X4VS.js +113 -0
  22. package/dist/chunk-4NDEP7HU.js +26 -0
  23. package/dist/chunk-5OMOPUE6.js +39 -0
  24. package/dist/chunk-5QQWS4US.js +53 -0
  25. package/dist/chunk-5ZABTVSW.js +48 -0
  26. package/dist/chunk-65KAQSJP.js +7 -0
  27. package/dist/chunk-6STKGOCW.js +27 -0
  28. package/dist/chunk-6WXMJOMI.js +9 -0
  29. package/dist/chunk-73AKO4UL.js +24 -0
  30. package/dist/chunk-7DLZC73N.js +29 -0
  31. package/dist/chunk-7GBYECSK.js +72 -0
  32. package/dist/chunk-7HFIGCSL.js +419 -0
  33. package/dist/chunk-7TD53M7L.js +13 -0
  34. package/dist/chunk-7UCZAN4J.js +778 -0
  35. package/dist/chunk-A4PKLESO.js +112 -0
  36. package/dist/chunk-A7VF7A35.js +1025 -0
  37. package/dist/chunk-ABTJQ4QV.js +74 -0
  38. package/dist/chunk-AJ4VXM2U.js +349 -0
  39. package/dist/chunk-BBTBJCFA.js +380 -0
  40. package/dist/chunk-BU65MNVU.js +13 -0
  41. package/dist/chunk-C4NHQGHL.js +142 -0
  42. package/dist/chunk-CJTKR6K6.js +1213 -0
  43. package/dist/chunk-D77IRGHO.js +1246 -0
  44. package/dist/chunk-DCU2EXQV.js +78 -0
  45. package/dist/chunk-DMZHQZ7P.js +104 -0
  46. package/dist/chunk-DZ2MRTYT.js +135 -0
  47. package/dist/chunk-E2YOZ2FF.js +207 -0
  48. package/dist/chunk-E3DQB5LS.js +48 -0
  49. package/dist/chunk-EATCUWGG.js +66 -0
  50. package/dist/chunk-EAWPJHJ7.js +155 -0
  51. package/dist/chunk-EIDIVIAD.js +33 -0
  52. package/dist/chunk-F5QYZK7E.js +396 -0
  53. package/dist/chunk-F5XMGOOX.js +28 -0
  54. package/dist/chunk-FENOGX3U.js +31 -0
  55. package/dist/chunk-GZHHEHKY.js +44 -0
  56. package/dist/chunk-HDMBVLCZ.js +53 -0
  57. package/dist/chunk-HQOB7OQS.js +81 -0
  58. package/dist/chunk-I2ZP2PSA.js +211 -0
  59. package/dist/chunk-IG33DXLT.js +151 -0
  60. package/dist/chunk-IJBSOWHK.js +86 -0
  61. package/dist/chunk-INT7QLEU.js +114 -0
  62. package/dist/chunk-J7UYNJCR.js +9 -0
  63. package/dist/chunk-JEL35P7S.js +53 -0
  64. package/dist/chunk-JGJ4INEN.js +32 -0
  65. package/dist/chunk-JS5RTH4I.js +84 -0
  66. package/dist/chunk-JWRZDYB5.js +59 -0
  67. package/dist/chunk-KMXRRSKT.js +660 -0
  68. package/dist/chunk-LBXO4VPG.js +73 -0
  69. package/dist/chunk-LLBPVZXM.js +67 -0
  70. package/dist/chunk-LLT5FQBE.js +57 -0
  71. package/dist/chunk-LMT3PPXJ.js +17 -0
  72. package/dist/chunk-LMUBBIE2.js +83 -0
  73. package/dist/chunk-LTZH5E3G.js +479 -0
  74. package/dist/chunk-LW4TG7EL.js +39 -0
  75. package/dist/chunk-MPSQXSC6.js +346 -0
  76. package/dist/chunk-MVFH26QT.js +97 -0
  77. package/dist/chunk-NLEXKE7U.js +67 -0
  78. package/dist/chunk-NQPURJT5.js +44 -0
  79. package/dist/chunk-NRBQK6UX.js +105 -0
  80. package/dist/chunk-OEH47H6A.js +48 -0
  81. package/dist/chunk-OG7QR2DP.js +75 -0
  82. package/dist/chunk-OPYFEHKG.js +52 -0
  83. package/dist/chunk-P4N7DBD5.js +83 -0
  84. package/dist/chunk-PAX3QXX2.js +140 -0
  85. package/dist/chunk-PKODFR5F.js +102 -0
  86. package/dist/chunk-PMJG2CXF.js +122 -0
  87. package/dist/chunk-Q5H3L6Y4.js +23 -0
  88. package/dist/chunk-QEF7EK3T.js +28 -0
  89. package/dist/chunk-QEW4J3IZ.js +74 -0
  90. package/dist/chunk-QPL7E2HW.js +464 -0
  91. package/dist/chunk-R2GPCZUX.js +22 -0
  92. package/dist/chunk-R5MT42JS.js +284 -0
  93. package/dist/chunk-RMATE45Z.js +197 -0
  94. package/dist/chunk-RPQOBHVU.js +87 -0
  95. package/dist/chunk-S3PIAMXV.js +230 -0
  96. package/dist/chunk-T3LKX23M.js +168 -0
  97. package/dist/chunk-T6GOWHK6.js +30 -0
  98. package/dist/chunk-TIA4SPU2.js +10 -0
  99. package/dist/chunk-TNCZ6444.js +57 -0
  100. package/dist/chunk-TVL5RTE6.js +269 -0
  101. package/dist/chunk-TXQ7L33K.js +45 -0
  102. package/dist/chunk-UPQTAHUK.js +189 -0
  103. package/dist/chunk-V4NPDK6X.js +14 -0
  104. package/dist/chunk-VJFEN6DJ.js +38 -0
  105. package/dist/chunk-VMHUEOT5.js +643 -0
  106. package/dist/chunk-VRPMYPZU.js +4985 -0
  107. package/dist/chunk-WIW772I3.js +25 -0
  108. package/dist/chunk-XELAZAIM.js +136 -0
  109. package/dist/chunk-XNML2KIC.js +23 -0
  110. package/dist/chunk-XP2U3LO3.js +30 -0
  111. package/dist/chunk-YGOWIJPE.js +51 -0
  112. package/dist/chunk-YIXDHQYE.js +11 -0
  113. package/dist/chunk-YSAWTGNA.js +117 -0
  114. package/dist/claude-U2JC2DNQ.js +77 -0
  115. package/dist/cli-MI4ZCAZ3.js +41 -0
  116. package/dist/cli-ZN7ZVDEZ.js +46 -0
  117. package/dist/cli.js +144 -16197
  118. package/dist/completion-ILSRB3LW.js +142 -0
  119. package/dist/config-DnpLL2kT.d.ts +46 -0
  120. package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
  121. package/dist/diagnostics-XKXVVQWH.js +93 -0
  122. package/dist/doctor-O2E63YGO.js +538 -0
  123. package/dist/entry-X6CSYQRQ.js +305 -0
  124. package/dist/exec-mcp-2PMWBPD7.js +365 -0
  125. package/dist/harness-L2KSI2ZB.js +177 -0
  126. package/dist/harness-egress-bridge.js +4 -4
  127. package/dist/harness-launch-gate.js +47 -940
  128. package/dist/harness-pane-runner.js +13 -80
  129. package/dist/harness-worker.js +21 -2703
  130. package/dist/hook-body.js +5222 -0
  131. package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
  132. package/dist/hook.js +26 -0
  133. package/dist/hooks-BHTA44X7.js +21 -0
  134. package/dist/host-UIZAXXQH.js +22 -0
  135. package/dist/host-UWK754BW.js +210 -0
  136. package/dist/host-run-BI2OTZDZ.js +307 -0
  137. package/dist/http.d.ts +5 -42
  138. package/dist/http.js +21 -2234
  139. package/dist/import-mcp-GPKJI7DI.js +400 -0
  140. package/dist/index.d.ts +146 -168
  141. package/dist/index.js +133 -4948
  142. package/dist/init-3C2Y7BNJ.js +14 -0
  143. package/dist/install-GG7HHZK2.js +796 -0
  144. package/dist/invoke-44CJRVMK.js +23 -0
  145. package/dist/list-MCP2FXUF.js +68 -0
  146. package/dist/list-WL6L4J5H.js +65 -0
  147. package/dist/load-BEUBABtB.d.ts +21 -0
  148. package/dist/logout-F5EJ5MOU.js +44 -0
  149. package/dist/logs-TBUA4UWU.js +107 -0
  150. package/dist/mailbox/index.d.ts +10 -5
  151. package/dist/mailbox/index.js +53 -1572
  152. package/dist/mailbox-BMTZOSZ7.js +285 -0
  153. package/dist/mailbox-GDJ7BWQN.js +189 -0
  154. package/dist/mainline-KAD2ERLP.js +639 -0
  155. package/dist/marketplace-G4VQET5W.js +191 -0
  156. package/dist/mcp-235QZN2A.js +15 -0
  157. package/dist/mcp-FJ2UQ4RH.js +193 -0
  158. package/dist/models-ISU4DCMA.js +32 -0
  159. package/dist/opencode-CN7JLQYO.js +60 -0
  160. package/dist/pause-7LILUVGL.js +18 -0
  161. package/dist/preview-DT7DWG5F.js +91 -0
  162. package/dist/project/hook-adapter.d.ts +5 -2
  163. package/dist/project/hook-adapter.js +41 -27
  164. package/dist/project-5YV5CUEG.js +70 -0
  165. package/dist/pty-XTJ4MIWK.js +94 -0
  166. package/dist/recovery-U6QB3PMT.js +100 -0
  167. package/dist/reindex-Y27QJFDB.js +22 -0
  168. package/dist/resume-26VFAAMH.js +18 -0
  169. package/dist/run-3AXTZSR7.js +126 -0
  170. package/dist/run-3SOVRQIA.js +19 -0
  171. package/dist/serve-DQMKTFIV.js +104 -0
  172. package/dist/session-XM2CR425.js +159 -0
  173. package/dist/setup-DTKZLZUT.js +18 -0
  174. package/dist/start-login-YTZV6KMF.js +416 -0
  175. package/dist/status-A2OUTNGK.js +9 -0
  176. package/dist/status-H2VAHIDV.js +10 -0
  177. package/dist/status-MROQ7WR7.js +43 -0
  178. package/dist/status-RO55QPKV.js +55 -0
  179. package/dist/status-UME2L33L.js +286 -0
  180. package/dist/stdio.d.ts +3 -13
  181. package/dist/stdio.js +16 -3186
  182. package/dist/sweep-35LGQTTO.js +18 -0
  183. package/dist/test-AGZOJLRZ.js +561 -0
  184. package/dist/tools-gpHNq9Dh.d.ts +328 -0
  185. package/dist/tui-G5LLWCSV.js +153 -0
  186. package/dist/unbroadcast-5QNGAJR2.js +18 -0
  187. package/dist/validate-IU52H2IC.js +46 -0
  188. package/dist/worker-QZ5T6LJD.js +80 -0
  189. package/dist/worktree-create-PZSRB7PH.js +89 -0
  190. package/dist/worktree-list-JYB6VXLW.js +51 -0
  191. package/dist/worktree-sync-UF5CXPWV.js +30 -0
  192. package/docs/authoring.md +82 -0
  193. package/docs/browser-and-desktop.md +46 -0
  194. package/docs/commands.md +325 -0
  195. package/docs/compare.md +35 -0
  196. package/docs/compatibility.md +55 -0
  197. package/docs/embeddings.md +1 -1
  198. package/docs/getting-started.md +105 -0
  199. package/docs/git-workflow.md +60 -0
  200. package/docs/glossary.md +31 -0
  201. package/docs/hooks/capabilities/antigravity.json +199 -0
  202. package/docs/hooks/capabilities/claude.json +179 -0
  203. package/docs/hooks/capabilities/codex.json +179 -0
  204. package/docs/hooks/capabilities/gemini.json +196 -0
  205. package/docs/hooks/capabilities/grok.json +192 -0
  206. package/docs/hooks/capabilities/opencode.json +184 -0
  207. package/docs/hooks.md +264 -0
  208. package/docs/install.md +72 -0
  209. package/docs/library-skills.md +132 -0
  210. package/docs/mailbox.md +16 -5
  211. package/docs/project-configuration.md +540 -58
  212. package/docs/sessions.md +64 -0
  213. package/docs/skills.md +4 -45
  214. package/docs/terminal-harness.md +92 -44
  215. package/docs/terminal-workspace.md +81 -169
  216. package/gemini-extension.json +2 -2
  217. package/mcp.json +1 -1
  218. package/package.json +16 -2
  219. package/plugin.json +2 -2
  220. package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
  221. package/plugins/pmcp/.mcp.json +1 -1
  222. package/plugins/pmcp/gemini-extension.json +2 -2
  223. package/plugins/pmcp/mcp.json +1 -1
  224. package/plugins/pmcp/mod/commands.ts +72 -0
  225. package/plugins/pmcp/mod/contract.d.ts +39 -0
  226. package/plugins/pmcp/mod/draw.tsx +216 -0
  227. package/plugins/pmcp/mod/guard.ts +42 -0
  228. package/plugins/pmcp/mod/hooks.json +4 -0
  229. package/plugins/pmcp/mod/host.ts +46 -0
  230. package/plugins/pmcp/mod/model.ts +144 -0
  231. package/plugins/pmcp/mod/reader/index.ts +18 -0
  232. package/plugins/pmcp/mod/reader/read.ts +76 -0
  233. package/plugins/pmcp/mod/reader/settings.ts +54 -0
  234. package/plugins/pmcp/mod/reader/types.ts +38 -0
  235. package/plugins/pmcp/mod/register.tsx +73 -0
  236. package/plugins/pmcp/mod/sessions/format.ts +91 -0
  237. package/plugins/pmcp/mod/sessions/types.ts +162 -0
  238. package/plugins/pmcp/mod/snapshot.ts +75 -0
  239. package/plugins/pmcp/mod/spinner.tsx +30 -0
  240. package/plugins/pmcp/mod/state.ts +28 -0
  241. package/plugins/pmcp/plugin.json +2 -2
  242. package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
  243. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
  244. package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  245. package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -15
  246. package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
  247. package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
  248. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +153 -0
  249. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +96 -0
  250. package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +89 -0
  251. package/schema/catalog-v1.json +187 -0
  252. package/schema/library.json +196 -0
  253. package/schema/marketplace-manifest.json +144 -0
  254. package/schema/plugin-manifest.json +59 -0
  255. package/schema/skill-frontmatter.json +170 -0
  256. package/schema/skill-metadata-core.json +131 -0
  257. package/skills/agent-assets-migrate/SKILL.md +96 -0
  258. package/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
  259. package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  260. package/skills/package-skill-catalog/SKILL.md +51 -15
  261. package/skills/pmcp-browser/SKILL.md +27 -0
  262. package/skills/pmcp-desktop/SKILL.md +25 -0
  263. package/skills/pmcp-project-init/SKILL.md +153 -0
  264. package/skills/pmcp-sessions-and-git/SKILL.md +96 -0
  265. package/skills/skill-package-scaffold/SKILL.md +89 -0
  266. package/dist/config-BkSpjUG6.d.ts +0 -50
  267. package/dist/embed-DRROSD3F.d.ts +0 -53
  268. package/dist/hook-spec-CSJJySsH.d.ts +0 -11
  269. package/dist/server-VWSY3Shw.d.ts +0 -543
  270. package/dist/tui-worker.js +0 -6549
  271. package/docs/manual-library-skills.md +0 -74
  272. /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
@@ -0,0 +1,64 @@
1
+ # Run several agents in one repository
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Two agents editing one checkout overwrite each other, push half-finished work or reinstall
6
+ dependencies under each other's feet. pmcp lets every agent session in a repository see the
7
+ others, and gives you the controls to coordinate them: a session list, a pause, broadcasts,
8
+ addressed messages, leases on shared files, linked worktrees and one delivery path to the
9
+ mainline. Every part is opt-in through `pmcp.toml`; the keys are in the
10
+ [pmcp.toml reference](project-configuration.md#sessions).
11
+
12
+ ## See who is working
13
+
14
+ ```sh
15
+ pmcp sessions status
16
+ ```
17
+
18
+ It lists each live session (id, runtime, checkout and current tool), the pause, current
19
+ broadcasts, held leases, and files edited but not yet delivered in the shared checkout.
20
+ `pmcp status` adds projection drift and worktree ahead and behind counts.
21
+
22
+ ## Pause and broadcast
23
+
24
+ These are your controls; an agent reports the need for them and leaves the decision to you.
25
+
26
+ ```sh
27
+ pmcp sessions pause "release freeze"
28
+ pmcp sessions resume
29
+ pmcp sessions broadcast "main moved; sync your worktree before delivering"
30
+ pmcp sessions unbroadcast
31
+ pmcp sessions sweep # drop records whose process is gone
32
+ ```
33
+
34
+ While paused, every other session's edits and mutating commands are refused; reading and
35
+ planning continue. A broadcast reaches each running session once, as context. `--by <name>`
36
+ names who pauses or broadcasts; that session is exempt, and without it the sender is
37
+ `operator`.
38
+
39
+ ## Send a message to one session
40
+
41
+ With `[sessions.mailbox]` declared, address a session by id, alias, role or linked worktree:
42
+
43
+ ```sh
44
+ pmcp sessions send --to alias:reviewer --subject review "Please check the config change"
45
+ pmcp sessions send --to worktree:.claude/worktrees/docs --wake "Rebase onto main"
46
+ pmcp sessions inbox
47
+ ```
48
+
49
+ `--wake` also starts a turn in an idle recipient where the runtime allows it (Claude Code,
50
+ opencode). This mailbox is for sessions of one repository; the [local mailbox](mailbox.md)
51
+ serves actors with their own credentials.
52
+
53
+ ## Keep agents out of each other's way
54
+
55
+ - **Leases.** `[sessions.leases.<name>]` names a file two sessions must not change at once,
56
+ such as a lockfile. While a delivery that touches it is in progress, the listed commands
57
+ wait.
58
+ - **Linked worktrees.** `pmcp git worktree create <alias>` gives each agent its own checkout;
59
+ an edit left in the shared main checkout blocks syncing it for everyone.
60
+ - **One delivery path.** With `[git.mainline.deliver]`, `pmcp git deliver` replays, tests and
61
+ pushes one delivery at a time, and a direct `git push` is refused.
62
+
63
+ The [Git workflow](git-workflow.md) page covers worktrees, delivery
64
+ and sync. Agents learn the same rules from the pmcp-sessions-and-git skill in the pmcp plugin.
package/docs/skills.md CHANGED
@@ -62,51 +62,10 @@ are left out of `skill_catalog` and `skill_find` unless `kind` asks for them
62
62
  (`agent`, `hook`, `mcp`, or `any`); `skill_describe`, `skill_read` and
63
63
  `skill_call` work on every kind.
64
64
 
65
- ## Public native marketplace
66
-
67
- The public repository's canonical sources are standard Agent Skills folders:
68
- `plugins/<product-major>/skills/<skill-name>/SKILL.md`. Each supported library
69
- major is a separate selectable plugin. The PMCP bridge has its own `pmcp` plugin.
70
- The website's `docs/skills/` files are generated downloads from those sources;
71
- existing URLs and immutable archive bytes remain available.
72
-
73
- | Tool | Native distribution |
74
- | --------------- | -------------------------------------------------------------------- |
75
- | Claude Code | `.claude-plugin/marketplace.json` and plugin manifests |
76
- | Codex | `.agents/plugins/marketplace.json` and portable `plugin.json` |
77
- | Grok Build | Claude-compatible marketplace and plugin manifests |
78
- | Gemini CLI | `gemini-extension.json`; selected CLI exports are extensions |
79
- | Antigravity CLI | Selected CLI export with its own `plugin.json` and `mcp_config.json` |
80
-
81
- For native marketplace commands, follow the [README](../README.md).
82
- Gemini and Antigravity need their own package formats for selected library plugins;
83
- do not assume that identically named manifest files accept the same schema.
84
- Since 0.14.0, `pmcp marketplace export <plugin> --runtime <tool>
85
- --output <new-directory>` materializes a selected package without altering native
86
- settings or installing it. Use the native manager to review and install that folder.
87
- Existing export destinations are preserved.
88
-
89
- The built-in catalog is available without remote fetching.
90
- `--no-builtin` or `[catalog] builtin = false` opts out; library APIs continue to
91
- read explicitly supplied catalog roots. `--marketplace <directory>` reads installed
92
- Claude, Codex and Grok local descriptors, rejects path escapes and does not fetch
93
- remote plugin sources. Add a remote marketplace with its native manager first.
94
-
95
- Public npm skill installation uses the bundled catalog, a matching installed
96
- dependency version and immutable free archive URLs. It verifies archive integrity,
97
- content-only metadata, instruction digests and installed file bytes. npm, Bun or pnpm
98
- changes the project and lockfile only after confirmation, with scripts disabled.
99
- `--provider hosted` remains a separate service path with its own access policy.
100
- Native plugin installation does not automatically version-match dependencies:
101
- select the appropriate major yourself. Non-npm library instructions remain manual.
102
-
103
- ## Manually selected Python, Rust and Go library skills
104
-
105
- Public Pydantic, serde_json and Google UUID instructions are free to read and
106
- copy into a local collection. Register that collection explicitly; these pilots
107
- are not automatically matched from PyPI, Cargo or Go dependencies. Follow the
108
- [manual library skills guide](manual-library-skills.md) for download paths and
109
- the existing CLI configuration workflow.
65
+ ## Library skills
66
+
67
+ Free instructions for public libraries, as native plugins, npm skill packages or (Python, Rust,
68
+ Go) a local collection: [Library skills](library-skills.md).
110
69
 
111
70
  ## MCP Skills extension
112
71
 
@@ -2,14 +2,26 @@
2
2
 
3
3
  Use `pmcp harness` to manage a main runtime and its workers through a local CLI.
4
4
  Each runtime keeps its own conversation interface, OAuth login, folder trust and
5
- tool permissions. PMCP manages owned terminal processes, observations and
6
- explicit input delivery. These controls are available from version 0.12.0;
5
+ tool permissions. The one exception is a session pmcp-pty hosts from a
6
+ `[host]` you approved: pmcp-pty may choose the tool-dialog options its
7
+ `[[host.answers]]` list, and never login, auth, trust or hook-review dialogs
8
+ (see [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts)). PMCP manages owned
9
+ terminal processes, observations and explicit input delivery. These controls are available from version 0.12.0;
7
10
  check your installed release's `pmcp harness --help` before using them.
8
11
 
9
- The host currently needs Linux, tmux, util-linux flock and a working user systemd
10
- manager. Native executables must be on PATH. The terminal transport was tested
11
- with tmux 3.2a and controlled executable fixtures. That does not qualify every
12
- vendor's prompt state, automatic wake, authentication refresh or native children.
12
+ The host needs Linux or macOS and pmcp-pty (`crates/pmcp-pty`; set
13
+ PMCP_PTY_BIN to it or put it on PATH). Native executables must be on PATH. Each
14
+ group has its own pmcp-pty daemon on the group's socket: it owns every session's
15
+ PTY, reads its screen through a per-runtime profile and takes input only with
16
+ the session's identity and, while one is held, its lease. On Linux a working user
17
+ systemd manager also caps each session in its own scope inside the group's slice;
18
+ macOS has no equivalent, so sessions run uncapped there while the session count
19
+ still holds. Controlled executable fixtures do not qualify every vendor's prompt
20
+ state, automatic wake, authentication refresh or native children.
21
+
22
+ Groups created by releases before pmcp-pty ran their sessions in tmux. They are
23
+ not migrated: stop and clean them up with the older pmcp release that created
24
+ them, then create a new group.
13
25
 
14
26
  ## Check the host
15
27
 
@@ -24,17 +36,19 @@ provider feature. Use `pmcp doctor` separately for project configuration checks.
24
36
 
25
37
  Group creation checks required tools and contacts the user manager before it
26
38
  writes group state. Missing tools return native_host_tool_unavailable followed
27
- by the tool name; an unreachable manager returns native_user_manager_unavailable.
39
+ by the tool name (pmcp-pty, and on Linux systemctl or systemd-run); an
40
+ unreachable manager returns native_user_manager_unavailable.
28
41
  The doctor report lists prerequisites and does not certify cgroup delegation.
29
42
  An ordinary isolated Docker container usually lacks this user manager and a
30
43
  writable delegated cgroup subtree. Container resource limits alone do not
31
- qualify the native session controls; the current profile requires its Linux host.
44
+ qualify the native session controls; they need the Linux or macOS host itself.
32
45
 
33
46
  ## Choose native or Docker execution
34
47
 
35
- The default native profile starts executables on the Linux host. The optional
36
- Docker profile keeps the same host-side tmux and user-systemd controller, while
37
- each native executable runs in its own bounded container. Docker does not
48
+ The default native profile starts executables on the host, Linux or macOS. The
49
+ optional Docker profile needs Linux: it keeps the same host-side pmcp-pty and
50
+ user-systemd controller, while each native executable runs in its own bounded
51
+ container. Docker does not
38
52
  replace the host prerequisites above. Only a local Docker Engine is supported.
39
53
 
40
54
  Prepare an image locally with your runtime installed. PMCP requires its exact
@@ -68,7 +82,7 @@ permission bypass. Docker access itself is a privileged host capability.
68
82
 
69
83
  The session `memoryMb` reserves both runtime memory and 64 MiB for its host
70
84
  connection. Its Docker memory limit is therefore 64 MiB smaller. Leave additional
71
- headroom in the group budget for its controller and tmux server.
85
+ headroom in the group budget for its controller and pmcp-pty daemon.
72
86
  Session receipts include the owned container identity only for Docker execution.
73
87
  Unknown or changed container identity blocks cleanup and admission.
74
88
 
@@ -89,10 +103,10 @@ host proxy rejects private addresses and undeclared destinations. The declared
89
103
  Node executable must exist inside the image. PMCP stages a digest-checked opaque
90
104
  bridge and provides proxy environment variables to the native process. It does
91
105
  not intercept TLS or interpret OAuth. A runtime that ignores proxy variables
92
- cannot reach the provider through this profile. Actual Codex 0.161.0 login and
93
- main/worker responses have been qualified; other vendors and token refresh need
94
- their own validation. These two hosts are an observed test scope, not a promise
95
- that all future Codex features use only them.
106
+ cannot reach the provider through this profile. What has been measured through
107
+ it is in [Compatibility](compatibility.md#installation-and-packaging); these two
108
+ hosts are an observed test scope, not a promise that all future Codex features
109
+ use only them.
96
110
 
97
111
  ### Keep authenticated roles independent
98
112
 
@@ -153,8 +167,9 @@ pmcp harness group list
153
167
 
154
168
  The JSON receipt provides the private groupFile and generation. Set GROUP_FILE
155
169
  and GENERATION to those values for the examples below. Group state lives below
156
- XDG_STATE_HOME/pmcp/harness, or ~/.local/state/pmcp/harness. The tmux socket path
157
- must fit within 100 bytes; an unusually long state root is refused.
170
+ XDG_STATE_HOME/pmcp/harness, or ~/.local/state/pmcp/harness. pmcp keeps the group
171
+ socket path within 100 bytes, below the 104 bytes macOS and 108 bytes Linux allow for a
172
+ Unix socket path, so one state root works on both; an unusually long one is refused.
158
173
 
159
174
  Save `main-spec.json`:
160
175
 
@@ -199,7 +214,7 @@ pmcp harness session read --group-file "$GROUP_FILE" --session "$SESSION"
199
214
  pmcp harness attach open --group-file "$GROUP_FILE" --session "$SESSION"
200
215
  ```
201
216
 
202
- Attachment is read-only by default. Detach with tmux's Ctrl-b then d, or use
217
+ Attachment is read-only by default. Detach with Ctrl-\ pressed twice, or use
203
218
  attach detach with the target session and current generation. Detach preserves
204
219
  the runtime. Reading returns terminal text and does not infer model readiness.
205
220
 
@@ -215,18 +230,13 @@ pmcp harness session read --group-file "$GROUP_FILE" --session "$SESSION" --inpu
215
230
 
216
231
  lines accepts 1–2000 and maxBytes accepts 1–65536. Defaults remain 100 lines and
217
232
  16384 bytes. A bounded result reports truncated when it omits earlier content.
218
- During an alternate-screen application, alternate: true reads the saved normal
219
- screen; omitted or false reads the current screen. This returns the owned native
220
- pane's content, separate from a surrounding terminal's older shell output.
221
-
222
- On the tested tmux 3.2a, read-only native clients ignore typing, wheel reports
223
- and copy-mode keys; use session read for history without acquiring control.
224
- Inside another tmux with the same Ctrl-b prefix, Ctrl-b then Ctrl-b forwards
225
- one prefix to the inner layer. Ctrl-b then [ opens the outer copy mode, while
226
- Ctrl-b, Ctrl-b, d detaches the inner connection. Outer history is the rendered
227
- wrapper screen; session read retrieves the owned runtime's history.
228
- PMCP does not change the outer tmux configuration. Other terminal mouse and
229
- trackpad settings require their own qualification.
233
+ Lines come from the session's recent output with terminal escapes removed;
234
+ alternate: true returns the screen as it is now instead. Both read the owned
235
+ session only, separate from a surrounding terminal's older shell output.
236
+
237
+ A read-only attachment drops every keystroke; use session read for history
238
+ without acquiring control. Ctrl-\ followed by any other key is passed through,
239
+ so a nested terminal multiplexer keeps its own prefix.
230
240
 
231
241
  For bounded polling, session watch also takes an input file containing count
232
242
  (1–10) and intervalMs (100–2000). It returns snapshots rather than an endless
@@ -241,8 +251,10 @@ pmcp harness attach open --group-file "$GROUP_FILE" --generation "$GENERATION" -
241
251
 
242
252
  Set LEASE_FILE to the acquire receipt's private credential path. A writable
243
253
  attachment renews its 60-second lease and releases it after detach. Failed
244
- renewal disconnects the client. It does not stop the runtime. Another writable
245
- tmux client blocks CLI delivery even if it bypassed PMCP's lease.
254
+ renewal disconnects the client. It does not stop the runtime. pmcp-pty holds
255
+ the same lease token, so while it is held it refuses a writable attachment or
256
+ input without it, and a person typing in an attachment wins over program input
257
+ for five seconds after the last keystroke.
246
258
 
247
259
  ## Deliver input explicitly
248
260
 
@@ -256,7 +268,7 @@ pmcp harness control release --group-file "$GROUP_FILE" --generation "$GENERATIO
256
268
  ```
257
269
 
258
270
  Write and Enter submission are separate operations. Newlines, tabs, terminal
259
- control characters and input above 16 KiB are refused. A tmux paste flag alone
271
+ control characters and input above 16 KiB are refused. Bracketed paste alone
260
272
  cannot guarantee safe multiline delivery in a native approval menu.
261
273
 
262
274
  Inspect the native screen before writing or submitting. A control lease identifies
@@ -289,14 +301,50 @@ PMCP does not create another message engine or automatically type a wake prompt
289
301
  into a native menu. Follow the [mailbox guide](mailbox.md) for actor credentials
290
302
  and launcher-bound runtime attachments.
291
303
  There is no automatic delivery loop. Native readiness and approval stay with
292
- the operator and runtime; an input receipt does not establish prompt readiness.
304
+ you and the runtime; an input receipt does not establish prompt readiness.
305
+
306
+ ### Sessions pmcp-pty hosts
307
+
308
+ `[host]` in pmcp.toml lists long-running sessions for one shared pmcp-pty host
309
+ outside any group (see
310
+ [Sessions pmcp-pty hosts](project-configuration.md#sessions-pmcp-pty-hosts)).
311
+ After `pmcp project` and your own `pmcp harness host approve`:
312
+
313
+ `host up` and `host unit` need Linux with a user systemd manager. On macOS they
314
+ stop with `platform_unsupported`; use `pmcp tui` or a harness group there.
315
+
316
+ - `pmcp harness host up` starts pmcp-pty if its socket (`PMCP_PTY_SOCKET`, else
317
+ `$XDG_RUNTIME_DIR/pmcp-pty.sock`) does not answer, in a transient
318
+ `systemd-run --user --scope` capped at 4G and loading the approved copy with
319
+ `--host`. The binary is `PMCP_PTY_BIN`, else the first `pmcp-pty` on
320
+ `PATH`; without one, `up` stops at once and `pmcp doctor` says so, and a
321
+ start that never answers reports the scope's own output (kept in
322
+ `host-daemon.log` beside the journal). It starts each approved session that
323
+ is not running, labelled
324
+ `pmcp.host=<name>`, and leaves running ones alone. An exited session
325
+ restarts only with `restart = "on-exit"`, up to `max_restarts` since its
326
+ last fresh start; run `up` again to apply it, since nothing watches in the
327
+ background. Each start, restart and stop goes to `host-runs.jsonl` in the
328
+ project's pmcp state directory.
329
+ - `pmcp harness host down` stops the host's sessions (their whole process
330
+ trees) and forgets them, so the next `up` starts them fresh. pmcp-pty and
331
+ its other sessions keep running.
332
+ - `pmcp harness host status` reports the approval: `approved`, `differs` (a
333
+ newer projection waits for approval; the approved one keeps running),
334
+ `unapproved` or `unprojected`.
335
+ - `pmcp harness host unit` prints a systemd user unit that runs pmcp-pty with
336
+ the approved copy. Installing and enabling it is your step; pmcp
337
+ never writes or enables a unit.
338
+
339
+ `up` and `down` use only the approved copy, so a session or answer an agent
340
+ adds to pmcp.toml runs only after you approve it.
293
341
 
294
342
  ### A manual request and review workflow
295
343
 
296
344
  Mailbox actor names and harness session roles are separate. Creating a main or
297
345
  worker terminal does not register a mailbox actor or give it credentials. Use
298
- the mailbox guide to initialize the project and register main, worker and
299
- operator actors. Keep their credential files private. The following workflow
346
+ the mailbox guide to initialize the project and register `main`, `worker` and
347
+ `operator` actors. Keep their credential files private. The following workflow
300
348
  uses CLI actor files for manual coordination; it does not attach a vendor child
301
349
  or automatically configure a runtime's MCP server.
302
350
 
@@ -340,8 +388,8 @@ task state machine. A new attempt uses a new request and idempotency key; keep
340
388
  the previous result in its original thread. Exact send retries reuse their key
341
389
  and return the existing message; changed payloads are refused.
342
390
 
343
- The main can send its synthesis to operator as a reply to the reviewed result.
344
- After reading it, the operator may send a separate acceptance reply. ACK records
391
+ The main can send its synthesis to `operator` as a reply to the reviewed result.
392
+ After reading it, you may send a separate acceptance reply as `operator`. ACK records
345
393
  receipt handling only. Neither result text, ACK nor acceptance automatically
346
394
  submits a terminal draft, transfers control or executes a command.
347
395
 
@@ -354,15 +402,15 @@ reservations. Expanding grants requires a new group.
354
402
 
355
403
  session stop names one owned session. group stop explicitly stops its entire
356
404
  owned group and removes runtime budget properties. Both require the current
357
- generation. They do not target an existing external tmux session.
405
+ generation. They do not target an existing external terminal session.
358
406
 
359
407
  recovery inspect reports observations, leases, uncertain deliveries and
360
408
  unregistered owned sessions. recovery reconcile removes a writer lock only
361
409
  after its controller has exited and never resends input. Use recovery
362
410
  stop-orphan for a named unregistered session, or recovery replace-main with a
363
411
  new main specification after the previous main has stopped. Replacement changes
364
- the generation and invalidates old control credentials. Unknown server or pane
365
- identity fails closed; no session is silently adopted.
412
+ the generation and invalidates old control credentials. An unknown host instance
413
+ or session identity fails closed; no session is silently adopted.
366
414
 
367
415
  Include pending starts explicitly when inspecting a failed launch:
368
416
 
@@ -375,7 +423,7 @@ abort-start stops a named incomplete launch and marks any saved group reference
375
423
  as stopped. It neither adopts the session nor restarts it. A committed session
376
424
  uses session stop instead. If the start gate died before recording ownership,
377
425
  automatic cleanup is refused and admission remains blocked for administrative
378
- repair. Keep the private state directory as evidence; do not guess a pane target
426
+ repair. Keep the private state directory as evidence; do not guess a session id
379
427
  or resend an uncertain request.
380
428
 
381
429
  ## Layout planning
@@ -384,7 +432,7 @@ or resend an uncertain request.
384
432
  pmcp harness layout --columns 120 --rows 40
385
433
  ```
386
434
 
387
- This pure command needs no tmux, provider, project or network. It returns layout
435
+ This pure command needs no terminal host, provider, project or network. It returns layout
388
436
  A at 120 columns and 32 rows or larger: a main pane, worker dock and bottom
389
437
  coordination pane. Smaller terminals retain a full-width main. The minimum is
390
438
  40 columns by 12 rows; the maximum is 1000 in either dimension.