@pipod/cli 0.1.15 → 0.1.17

package/docs/pod-list-pagination.md

@@ -0,0 +1,52 @@
+# Pod-list pagination
+
+`pipod ls` (also `pipod list`) reads every page before applying display filters or
+rendering the oldest-activity-first tree. Quiet output contains each full pod ID
+once. Project, template, account and machine-group scopes use the same page walk;
+so do short-ref/name resolution and bulk archive/restore/GC selection.
+
+## API contract
+
+`GET /v1/pods` returns `{ pods, nextCursor }`. A page contains at most `limit`
+pods (default 100, maximum 200). `nextCursor: null` means the last page, including
+an empty result. Otherwise pass that opaque string as `cursor` on the next request,
+keeping the same filters. Do not derive it from `lastActivityAt` or `createdAt`:
+the cursor retains PostgreSQL microseconds and the pod UUID tie-breaker. The
+order is descending `(COALESCE(last_activity_at, created_at), id)`.
+
+The cursor contains a boundary, not a row lookup, so deleting the boundary pod
+does not invalidate it. It is not an authorization grant: every page still
+applies the authenticated organization, owner and pod-token subtree restrictions.
+Malformed cursors and requests combining `cursor` with `before` return 400.
+
+`before` remains the legacy timestamp-only boundary. A new CLI falls back to it
+only when the response omits `nextCursor`; old clients continue working with new
+servers but cannot recover ties or microseconds using their old page walk. Both
+sides must be upgraded for lossless pagination of an unchanged roster.
+
+This is a live listing, not a database snapshot. Concurrent activity can move a
+pod ahead of an already-read boundary. The CLI deduplicates IDs if it sees a pod
+again and fails explicitly on a repeated cursor rather than reporting a silently
+truncated roster. Rerun a listing after concurrent activity for a fresh view.
+
+## Manual acceptance (no unit tests)
+
+Use an explicit disposable migrated database, never a production fixture insert.
+Run the actual pod routes over loopback HTTP and the built CLI by absolute path:
+
+- More than 400 pods with identical activity timestamps, including ties spanning
+  multiple pages; every matching ID appears exactly once.
+- Several distinct PostgreSQL timestamps within one millisecond; no IDs disappear
+  at the page boundary. Include null activity with creation-time fallback.
+- Empty, short, exact-multiple and final pages; authoritative `nextCursor` works
+  even with pages smaller than the CLI's requested maximum.
+- Account, project, template, state, owner, gone-row and pod-token subtree filters
+  remain in force on subsequent pages. Archived pods filling an early page do not
+  hide active pods on later pages. Check quiet and rendered output.
+- Delete the last pod of one page, then follow its cursor successfully.
+- Malformed cursor and simultaneous `cursor`/`before` return 400.
+- A legacy server omitting `nextCursor` is still traversed with `before`.
+  A server repeating a cursor fails without printing an incomplete quiet roster.
+
+Live rollout acceptance uses read-only listings. It must not manufacture hundreds
+of billable pods or change existing pods' timestamps to force a page boundary.

package/docs/workspace-seeding.md

@@ -74,6 +74,12 @@ starts at once; the server also opens the gate on its own after a timeout, so a
 dies mid-seed never strands the pod. Configured projects keep their post-start copy and do not
 arm the gate.
 
+A seed only ever fills an empty workdir. When init scripts (or the image) have already
+populated it by the time provisioning finishes, as a template whose init clones its
+repositories does, the server records the seed as `skipped` and starts Pi with the pod. The
+client then sends nothing: no clone request, no archive. Older servers leave the gate armed,
+and the client sends the seed for the routes to refuse.
+
 ## Older servers
 
 A server with a strict launch schema rejects the `workspaceSeed` flag; the client retries the
@@ -106,6 +112,7 @@ on the sandbox backend:
 8. **Nested pod launch** — from inside a pod, launch a child from a source-less directory;
    symlinks are skipped with a warning, files arrive.
 9. **Template/init-script collision** — `--template <one whose init script clones>`; expect
-   `workspace already populated … leaving it in place`.
+   `workspace already populated … nothing sent`, no archive build or upload, and the
+   pod's `workspaceSeed` reported `skipped`.
 10. **`--no-seed`, `--dry-run`, `fork`, `--on`** — none create a transfer; `--dry-run` prints
     the decision and creates no pod.

package/man/pipod-config.5

@@ -1,4 +1,4 @@
-.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.15"
+.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.17"
 .SH "NAME"
 \fBpipod-config\fR \- pi pod configuration files
 .SH SYNOPSIS

package/man/pipod.1

@@ -1,4 +1,4 @@
-.TH "PIPOD" "1" "October 2026" "0.1.15"
+.TH "PIPOD" "1" "October 2026" "0.1.17"
 .SH "NAME"
 \fBpipod\fR \- run pi coding\-agent sessions in server\-managed pods
 .SH SYNOPSIS
@@ -277,7 +277,8 @@ or \.pi\-pod/env\. Private\-remote
 credentials are forwarded only after a prompt (\fB\-\-yes\fP approves it) and are never stored\.
 \fB\-\-dry\-run\fP prints the decision without prompting or creating a pod\. Forks, reused pods,
 \fB\-\-on\fP co\-location, and \fB\-\-no\-seed\fP never seed\. A project with a \.pi\-pod/config\.json gets its
-workspace from its init scripts instead\.
+workspace from its init scripts instead\. When a template's init scripts have already
+populated the workspace, nothing is sent\.
 .P
 Arguments after \fB\-\-\fP go to pi: prompt words start the session, and \fB\-\-model\fP, \fB\-\-thinking\fP,
 and \fB\-\-tui\-mode\fP apply to this launch\. Per\-launch Pi resources (\fB\-\-extension\fP, \fB\-\-skill\fP,

package/man/pipod.1.md

@@ -266,7 +266,8 @@ or .pi-pod/env. Private-remote
 credentials are forwarded only after a prompt (`--yes` approves it) and are never stored.
 `--dry-run` prints the decision without prompting or creating a pod. Forks, reused pods,
 `--on` co-location, and `--no-seed` never seed. A project with a .pi-pod/config.json gets its
-workspace from its init scripts instead.
+workspace from its init scripts instead. When a template's init scripts have already
+populated the workspace, nothing is sent.
 
 Arguments after `--` go to pi: prompt words start the session, and `--model`, `--thinking`,
 and `--tui-mode` apply to this launch. Per-launch Pi resources (`--extension`, `--skill`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipod/cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Run pi coding-agent sessions in server-managed pods",
   "type": "module",
   "license": "AGPL-3.0-only",