@pipod/cli 0.1.20 → 0.1.21

package/docs/pod-list-pagination.md

@@ -3,7 +3,8 @@
 `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.
+so does bulk archive/restore/GC selection. Short-ref/name resolution uses the
+bounded lookup below; only an older server without that route uses pagination.
 
 ## API contract
 
@@ -29,6 +30,32 @@ 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.
 
+## Pod-reference lookup
+
+`GET /v1/pods/by-ref/:ref` resolves a short reference or exact name within the
+caller's own pods, including archived pods but excluding gone rows. Pod tokens
+are additionally limited to their own subtree. Matching uses the same shared
+parser as the CLI: case-sensitive exact names precede hexadecimal references;
+`p-`/`j-` references match UUID tails, and bare hex matches legacy leading prefixes
+or tails. Short hex references require at least four characters. Exact names can
+still contain text that would otherwise be an invalid short reference.
+
+The response is `{ pod, matches, total }`. A unique result includes one full pod;
+no match returns `pod: null, matches: [], total: 0`. Ambiguity returns no full pod,
+the exact total, and at most twenty `{ id, name, state }` choices. It never sends
+the account's launch reports just to resolve one reference. All values are bound
+SQL parameters, and lookup does not grant permission to perform an action.
+
+A full UUID continues to use the ordinary single-pod route. Only a 404 from the
+new route triggers the CLI's old-server pagination fallback; auth, validation,
+network and server failures do not. Missing matches on a supporting server are
+200 responses, not capability failures.
+
+Attach also shares one in-flight semantic model catalog between catalog and
+thinking-level consumers and overlaps independent auth/thinking initialization.
+It still validates readiness, settings and extension trust before accepting input;
+there is no persistent model cache or new classic-RPC passthrough.
+
 ## Manual acceptance (no unit tests)
 
 Use an explicit disposable migrated database, never a production fixture insert.
@@ -45,6 +72,14 @@ Run the actual pod routes over loopback HTTP and the built CLI by absolute path:
   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.
+- Resolve short refs and names against more than 800 history rows without any
+  roster requests. Check exact-name precedence, case-insensitive hex, minimum
+  length, prefix/tail collisions, archived/gone rows, owner/org isolation and
+  pod-token lineage. Ambiguity must return the exact count but at most twenty
+  metadata choices, never a full report for each match.
+- A missing lookup route falls back to the old paginated selection. A missing
+  match, invalid reference, 401/403, network failure or 5xx must not trigger that
+  fallback. Full UUIDs still go directly to the single-pod route.
 - A legacy server omitting `nextCursor` is still traversed with `before`.
   A server repeating a cursor fails without printing an incomplete quiet roster.
 

package/man/pipod-config.5

@@ -1,4 +1,4 @@
-.TH "PIPOD\-CONFIG" "5" "October 2026" "0.1.20"
+.TH "PIPOD\-CONFIG" "5" "November 2026" "0.1.21"
 .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.20"
+.TH "PIPOD" "1" "November 2026" "0.1.21"
 .SH "NAME"
 \fBpipod\fR \- run pi coding\-agent sessions in server\-managed pods
 .SH SYNOPSIS

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@pipod/cli",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@pipod/cli",
-      "version": "0.1.20",
+      "version": "0.1.21",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "@earendil-works/pi-coding-agent": "1.0.2",

package/package.json

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