@pipod/cli 0.1.12 → 0.1.14

package/docs/config-simplification.md

@@ -35,7 +35,7 @@ drops everything a bundle payload must not contain: the rejected keys
 `envFile`/`initScript`/`bakeScript`; `pi.hostConfig.skills`/`extensions`) plus
 client-only metadata (`$schema`, `secretResolver`, `pi.chords`/`pi.sessionNaming`/`pi.podExtensions`).
 Covered paths: project/user/org-dir compilation, the launch bootstrap preview,
-`templates create/edit --config`, and `settings user|org edit|set` — the settings
+`templates create/edit --config`, and `settings user|org|template edit|set` — the settings
 verbs validate the edited config locally first (types and retired keys fail
 before any write request) and throw on non-bundle keys with the fix, so an
 explicit `set reuse true` fails visibly rather than vanishing.
@@ -126,11 +126,11 @@ ignored, except `--dry-run`/`--on`-with-fork which are usage errors.
   server scripts with no local file warn instead of writing.
 - `diff [layer]`: same sources, secrets by name only; exit 1 on drift (`--dir`
   for org and policy; no `-y` — it never writes).
-- `settings <user|org> [show|edit|set <key> <json-value>]`: config-only
-  compare-and-swap edits (scripts/Pi files untouched — that is `push`).
-  `show` prints JSON; `edit` uses `$VISUAL`/`$EDITOR`; `set` takes a dotted key
-  plus a JSON value. Templates are not a settings scope (hint points at
-  `templates`).
+- `settings [user|org|policy|template [<name>]] [show|edit|set <key> <json-value>|unset <key>]`:
+  config-only compare-and-swap edits of the layers `push` replaces whole
+  (scripts/Pi files untouched — that is `push`). `show` prints JSON; `edit` uses
+  `$VISUAL`/`$EDITOR`; `set` takes a dotted key plus a JSON value. `template`
+  without a name is the project's pin. The policy is checked by the server only.
 - `login`: Zitadel PKCE in the browser; where none can open (SSH, headless), the
   device flow with a code finished on another device. `--server`, `--issuer`
   (self-hosted), `--org` (domain pin), `--device` (force the code), `--token`

package/man/pipod-config.5

@@ -1,4 +1,4 @@
-.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.12"
+.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.14"
 .SH "NAME"
 \fBpipod-config\fR \- pi pod configuration files
 .SH SYNOPSIS
@@ -7,6 +7,7 @@
 \|\.pi\-pod/config\.json          a project: the source of its template
 ~/\.pi\-pod/config\.json        this machine's preferences, and your user layer
 ~/\.pi\-pod/org/config\.json    the organization layer
+~/\.pi\-pod/org/policy\.json    the organization policy (POLICY KEYS)
 .fi
 .RE
 .SH DESCRIPTION
@@ -14,11 +15,23 @@
 Each file is one settings layer's config, written as JSON with comments allowed\. The server
 merges the layers for each launch (\fBpipod help layers\fP), so a file names only what its layer
 must decide; anything left out comes from the layers below it\. The keys are the same in every
-file\. \fBpipod push\fP uploads a file and \fBpipod settings <user|org> set <key> <value>\fP changes
-one key on the server\.
+file but policy\.json, which holds limits on the merged result instead\. \fBpipod push\fP uploads a
+file and \fBpipod settings <layer> set <key> <value>\fP changes one key on the server\.
 .P
 A key of the wrong type fails the command that reads it, naming the key\. An unknown key is
 ignored with a warning\.
+.SH SESSION PROXIES
+.P
+Session WebSockets honor \fBWSS_PROXY\fP (\fBWS_PROXY\fP for plain WebSockets), generic
+\fBALL_PROXY\fP settings, and then fall back to \fBHTTPS_PROXY\fP (\fBHTTP_PROXY\fP for plain
+WebSockets)\. Lowercase names take precedence over uppercase names; npm proxy
+settings follow \fBproxy\-from\-env\fP conventions\. \fBNO_PROXY\fP supports hostnames,
+domain suffixes, optional ports, and \fB*\fP for direct connections\.
+.P
+Proxy URLs must use HTTP or HTTPS\. Session connections use CONNECT tunnels and
+retain TLS certificate verification for both the proxy and the destination\.
+These variables apply to initial attachment and reconnection, without requiring
+\fBNODE_USE_ENV_PROXY\fP\|\. With no matching proxy setting, sessions connect directly\.
 .SH POD KEYS
 .P
 These travel to the server and decide what a pod gets\. The defaults are the built\-in layer's\.
@@ -101,6 +114,36 @@ pi\.podExtensions         a pod's Pi extensions run on this machine, as you, to
 $schema                  ignored
 .fi
 .RE
+.SH POLICY KEYS
+.P
+policy\.json holds the organization's policy: limits the server applies after every other
+layer, whatever a person's settings, template, or launch ask for\. Every key is optional, and
+one left out sets no limit\. The server checks every change to it and names any key or value it
+refuses\.
+.RS 2
+.nf
+maxIdleTimeoutMinutes          the longest idleTimeoutMinutes a pod gets; a longer one,
+                               or 0, becomes this
+maxArchiveAfterMinutes         the same for archiveAfterMinutes
+maxConcurrentPods              pods the whole organization may have awake at once; the
+                               server's own limit per person still applies
+allowedProviders               the providers a launch may use; others are refused
+requireTemplate                true: every launch must use a template
+requireEgressMode              "allowlist": a pod set to "open" gets "allowlist" instead
+forbiddenEgressHosts           hosts removed from every egress\.allow
+nestedPods\.enabled             false: pods may not launch pods or schedule jobs
+                               (default true)
+nestedPods\.maxDepth            how deep pods may launch pods, 0 to 8 (default 2)
+nestedPods\.maxChildrenPerPod   awake child pods per pod, 0 to 100 (default 5)
+nestedPods\.maxPodsPerLineage   awake pods in one family of pods, 1 to 500 (default 10)
+nestedPods\.allowFileSend       false: pods may not send files to other pods (default true)
+nestedPods\.allowFileReceive    false: pods may not copy files out of other pods
+                               (default true)
+notifications\.redacted         true: push notifications leave out pod names and summaries
+.fi
+.RE
+.P
+Each clamp a launch gets is reported by \fBpipod doctor\fP and \fBpipod \-\-dry\-run\fP\|\.
 .SH SCRIPTS
 .P
 A layer's two scripts sit beside its config: \.pi\-pod/init\.sh and \.pi\-pod/bake\.sh in a
@@ -143,6 +186,14 @@ pipod settings org set resources\.memoryGB 8
 pipod settings org set idleTimeoutMinutes 30
 .fi
 .RE
+.P
+An organization policy that caps idle time and keeps pods from launching pods:
+.RS 2
+.nf
+pipod settings policy set maxIdleTimeoutMinutes 60
+pipod settings policy set nestedPods\.enabled false
+.fi
+.RE
 .SH RETIRED KEYS
 .P
 \fBenvFile\fP, \fBinitScript\fP, \fBbakeScript\fP, and \fBreuse\fP fail with a message saying what replaced

package/man/pipod-config.5.md

@@ -6,6 +6,7 @@
 .pi-pod/config.json          a project: the source of its template
 ~/.pi-pod/config.json        this machine's preferences, and your user layer
 ~/.pi-pod/org/config.json    the organization layer
+~/.pi-pod/org/policy.json    the organization policy (POLICY KEYS)
 ```
 
 ## DESCRIPTION
@@ -13,12 +14,25 @@
 Each file is one settings layer's config, written as JSON with comments allowed. The server
 merges the layers for each launch (`pipod help layers`), so a file names only what its layer
 must decide; anything left out comes from the layers below it. The keys are the same in every
-file. `pipod push` uploads a file and `pipod settings <user|org> set <key> <value>` changes
-one key on the server.
+file but policy.json, which holds limits on the merged result instead. `pipod push` uploads a
+file and `pipod settings <layer> set <key> <value>` changes one key on the server.
 
 A key of the wrong type fails the command that reads it, naming the key. An unknown key is
 ignored with a warning.
 
+## SESSION PROXIES
+
+Session WebSockets honor `WSS_PROXY` (`WS_PROXY` for plain WebSockets), generic
+`ALL_PROXY` settings, and then fall back to `HTTPS_PROXY` (`HTTP_PROXY` for plain
+WebSockets). Lowercase names take precedence over uppercase names; npm proxy
+settings follow `proxy-from-env` conventions. `NO_PROXY` supports hostnames,
+domain suffixes, optional ports, and `*` for direct connections.
+
+Proxy URLs must use HTTP or HTTPS. Session connections use CONNECT tunnels and
+retain TLS certificate verification for both the proxy and the destination.
+These variables apply to initial attachment and reconnection, without requiring
+`NODE_USE_ENV_PROXY`. With no matching proxy setting, sessions connect directly.
+
 ## POD KEYS
 
 These travel to the server and decide what a pod gets. The defaults are the built-in layer's.
@@ -98,6 +112,36 @@ pi.podExtensions         a pod's Pi extensions run on this machine, as you, to r
 $schema                  ignored
 ```
 
+## POLICY KEYS
+
+policy.json holds the organization's policy: limits the server applies after every other
+layer, whatever a person's settings, template, or launch ask for. Every key is optional, and
+one left out sets no limit. The server checks every change to it and names any key or value it
+refuses.
+
+```
+maxIdleTimeoutMinutes          the longest idleTimeoutMinutes a pod gets; a longer one,
+                               or 0, becomes this
+maxArchiveAfterMinutes         the same for archiveAfterMinutes
+maxConcurrentPods              pods the whole organization may have awake at once; the
+                               server's own limit per person still applies
+allowedProviders               the providers a launch may use; others are refused
+requireTemplate                true: every launch must use a template
+requireEgressMode              "allowlist": a pod set to "open" gets "allowlist" instead
+forbiddenEgressHosts           hosts removed from every egress.allow
+nestedPods.enabled             false: pods may not launch pods or schedule jobs
+                               (default true)
+nestedPods.maxDepth            how deep pods may launch pods, 0 to 8 (default 2)
+nestedPods.maxChildrenPerPod   awake child pods per pod, 0 to 100 (default 5)
+nestedPods.maxPodsPerLineage   awake pods in one family of pods, 1 to 500 (default 10)
+nestedPods.allowFileSend       false: pods may not send files to other pods (default true)
+nestedPods.allowFileReceive    false: pods may not copy files out of other pods
+                               (default true)
+notifications.redacted         true: push notifications leave out pod names and summaries
+```
+
+Each clamp a launch gets is reported by `pipod doctor` and `pipod --dry-run`.
+
 ## SCRIPTS
 
 A layer's two scripts sit beside its config: .pi-pod/init.sh and .pi-pod/bake.sh in a
@@ -140,6 +184,13 @@ pipod settings org set resources.memoryGB 8
 pipod settings org set idleTimeoutMinutes 30
 ```
 
+An organization policy that caps idle time and keeps pods from launching pods:
+
+```
+pipod settings policy set maxIdleTimeoutMinutes 60
+pipod settings policy set nestedPods.enabled false
+```
+
 ## RETIRED KEYS
 
 `envFile`, `initScript`, `bakeScript`, and `reuse` fail with a message saying what replaced

package/man/pipod.1

@@ -1,4 +1,4 @@
-.TH "PIPOD" "1" "October 2026" "0.1.12"
+.TH "PIPOD" "1" "October 2026" "0.1.14"
 .SH "NAME"
 \fBpipod\fR \- run pi coding\-agent sessions in server\-managed pods
 .SH SYNOPSIS
@@ -138,8 +138,9 @@ pipod push org
 .P
 Values for secrets the whole organization shares: \fBpipod secrets set org <NAME>\fP (person)\.
 .P
-Organization policy (limits rather than defaults) needs the policy:write permission\. Its source
-is policy\.json beside the organization layer's files:
+Organization policy (limits rather than defaults) needs the policy:write permission\. Change
+one limit with \fBpipod settings policy set <key> <value>\fP (its keys are in pipod\-config(5)), or
+the whole policy from its source, policy\.json beside the organization layer's files:
 .RS 2
 .nf
 pipod pull policy                # writes ~/\.pi\-pod/org/policy\.json
@@ -240,9 +241,10 @@ org        ~/\.pi\-pod/org/: config\.json, init\.sh, bake\.sh, pi/, env
 user       ~/\.pi\-pod/config\.json and ~/\.pi/agent/
            pipod pull|diff|push user; pipod settings user set
 template   a project: \.pi\-pod/config\.json, init\.sh, bake\.sh, env, and \.pi/
-           pipod pull|diff|push [template [<name>]]; pipod templates
+           pipod pull|diff|push [template [<name>]]; pipod settings template set;
+           pipod templates
 policy     ~/\.pi\-pod/org/policy\.json
-           pipod pull|diff|push policy                           (policy:write)
+           pipod pull|diff|push policy; pipod settings policy set (policy:write)
 .fi
 .RE
 .P
@@ -589,17 +591,23 @@ or \fBsync\fP reads a dotenv file kept at mode 600\. op:// references resolve th
 .SS pipod settings
 .RS 2
 .nf
-Usage: pipod settings <user|org> [show | edit | set <key> <value> | unset <key>]
+Usage: pipod settings [user | org | policy | template [<name>]]
+                      [show | edit | set <key> <value> | unset <key>]
 
-Show or edit a persistent settings bundle on the server: your own user bundle,
-or the org\-wide defaults (org scope needs the org:manage permission)\. Edits
-change only the config; scripts and Pi files stay as they are — replace the
-whole bundle from local files with `pipod push user` or `pipod push org`\.
-Edits use compare\-and\-swap on the bundle version, so concurrent changes fail
-cleanly instead of overwriting each other\.
+Show or edit one server layer's config directly, the same layers `pipod push`
+replaces whole:
+  user               Your own settings (the default)
+  org                The organization's defaults (needs org:manage)
+  policy             The organization's policy (needs policy:write)
+  template [<name>]  A template; without <name>, the one this project pins
+
+Edits change only the config; scripts and Pi files stay as they are — replace
+a whole layer from local files with `pipod push`\. Edits use compare\-and\-swap
+on the layer's version, so concurrent changes fail cleanly instead of
+overwriting each other\.
 
 Actions:
-  show                    Print the settings bundle as JSON (default)
+  show                    Print the layer as JSON (default)
   edit                    Edit the config in $VISUAL/$EDITOR, then save
   set <key> <value>       Set one dotted key to a JSON value, or to the text as
                           a string: pipod settings user set pi\.model provider/model
@@ -607,9 +615,11 @@ Actions:
 .fi
 .RE
 .P
-Keys are those of pipod\-config(5)\. \fBset\fP changes the server only: a later \fBpipod push\fP of the
-same layer replaces it with the local source, so after a \fBset\fP, run \fBpipod pull\fP before
-editing that source\.
+Keys are those of pipod\-config(5): its pod keys for user, org, and template, and its policy
+keys for policy, which the server checks\. \fBset\fP changes the server only: a later \fBpipod push\fP
+of the same layer replaces it with the local source, so after a \fBset\fP, run \fBpipod pull\fP before
+editing that source\. A template named like an action (show, edit, set, unset) is named by its
+id instead\.
 .SS pipod jobs
 .RS 2
 .nf

package/man/pipod.1.md

@@ -140,8 +140,9 @@ pipod push org
 
 Values for secrets the whole organization shares: `pipod secrets set org <NAME>` (person).
 
-Organization policy (limits rather than defaults) needs the policy:write permission. Its source
-is policy.json beside the organization layer's files:
+Organization policy (limits rather than defaults) needs the policy:write permission. Change
+one limit with `pipod settings policy set <key> <value>` (its keys are in pipod-config(5)), or
+the whole policy from its source, policy.json beside the organization layer's files:
 
 ```
 pipod pull policy                # writes ~/.pi-pod/org/policy.json
@@ -229,9 +230,10 @@ org        ~/.pi-pod/org/: config.json, init.sh, bake.sh, pi/, env
 user       ~/.pi-pod/config.json and ~/.pi/agent/
            pipod pull|diff|push user; pipod settings user set
 template   a project: .pi-pod/config.json, init.sh, bake.sh, env, and .pi/
-           pipod pull|diff|push [template [<name>]]; pipod templates
+           pipod pull|diff|push [template [<name>]]; pipod settings template set;
+           pipod templates
 policy     ~/.pi-pod/org/policy.json
-           pipod pull|diff|push policy                           (policy:write)
+           pipod pull|diff|push policy; pipod settings policy set (policy:write)
 ```
 
 What belongs where: the organization layer holds what everyone needs (pod size, network
@@ -580,26 +582,34 @@ or `sync` reads a dotenv file kept at mode 600. op:// references resolve through
 ### pipod settings
 
 ```
-Usage: pipod settings <user|org> [show | edit | set <key> <value> | unset <key>]
+Usage: pipod settings [user | org | policy | template [<name>]]
+                      [show | edit | set <key> <value> | unset <key>]
 
-Show or edit a persistent settings bundle on the server: your own user bundle,
-or the org-wide defaults (org scope needs the org:manage permission). Edits
-change only the config; scripts and Pi files stay as they are — replace the
-whole bundle from local files with `pipod push user` or `pipod push org`.
-Edits use compare-and-swap on the bundle version, so concurrent changes fail
-cleanly instead of overwriting each other.
+Show or edit one server layer's config directly, the same layers `pipod push`
+replaces whole:
+  user               Your own settings (the default)
+  org                The organization's defaults (needs org:manage)
+  policy             The organization's policy (needs policy:write)
+  template [<name>]  A template; without <name>, the one this project pins
+
+Edits change only the config; scripts and Pi files stay as they are — replace
+a whole layer from local files with `pipod push`. Edits use compare-and-swap
+on the layer's version, so concurrent changes fail cleanly instead of
+overwriting each other.
 
 Actions:
-  show                    Print the settings bundle as JSON (default)
+  show                    Print the layer as JSON (default)
   edit                    Edit the config in $VISUAL/$EDITOR, then save
   set <key> <value>       Set one dotted key to a JSON value, or to the text as
                           a string: pipod settings user set pi.model provider/model
   unset <key>             Remove one dotted key, so the layers below decide it
 ```
 
-Keys are those of pipod-config(5). `set` changes the server only: a later `pipod push` of the
-same layer replaces it with the local source, so after a `set`, run `pipod pull` before
-editing that source.
+Keys are those of pipod-config(5): its pod keys for user, org, and template, and its policy
+keys for policy, which the server checks. `set` changes the server only: a later `pipod push`
+of the same layer replaces it with the local source, so after a `set`, run `pipod pull` before
+editing that source. A template named like an action (show, edit, set, unset) is named by its
+id instead.
 
 ### pipod jobs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipod/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Run pi coding-agent sessions in server-managed pods",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -34,7 +34,7 @@
     "build:man": "marked-man --no-breaks man/pipod.1.md -o man/pipod.1 && marked-man --no-breaks man/pipod-config.5.md -o man/pipod-config.5",
     "typecheck": "tsc --noEmit",
     "lint": "node --import tsx scripts/check-runtime-surface.ts",
-    "test:integration": "node --import tsx --test --test-concurrency=1 test/integration/account-cli.test.ts test/integration/account-login-me-http.test.ts test/integration/billing-cli.test.ts test/integration/capacity-wait-http.test.ts test/integration/cli-main.test.ts test/integration/local-extensions.test.ts test/integration/nested-pods.test.ts test/integration/oidc-security.test.ts test/integration/secrets-cli.test.ts test/integration/workspace-seeding.test.ts test/integration/workstation-wake-http.test.ts",
+    "test:integration": "node --import tsx --test --test-concurrency=1 test/integration/account-cli.test.ts test/integration/account-login-me-http.test.ts test/integration/billing-cli.test.ts test/integration/capacity-wait-http.test.ts test/integration/cli-main.test.ts test/integration/local-extensions.test.ts test/integration/nested-pods.test.ts test/integration/oidc-security.test.ts test/integration/secrets-cli.test.ts test/integration/session-websocket-proxy.test.ts test/integration/workspace-seeding.test.ts test/integration/workstation-wake-http.test.ts",
     "check": "npm run lint && npm run typecheck",
     "prepublishOnly": "npm run build"
   },
@@ -42,11 +42,14 @@
     "@earendil-works/pi-coding-agent": "1.0.2",
     "@earendil-works/pi-tui": "1.0.2",
     "cron-parser": "^5.10.0",
+    "https-proxy-agent": "^9.1.0",
     "jose": "^5.10.0",
+    "proxy-from-env": "^1.1.0",
     "ws": "^8.22.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/proxy-from-env": "^1.0.4",
     "@types/ws": "^8.18.1",
     "marked-man": "^2.1.1",
     "tsup": "^8.3.5",