@pipod/cli 0.1.20 → 0.1.22

package/dist/key-encoding-guard-6UOKKTJQ.js

@@ -0,0 +1,41 @@
+// src/client/runtime/key-encoding-guard.ts
+import { decodeKittyPrintable, isKeyRelease } from "@earendil-works/pi-tui";
+var CONTROL_DELETE = 127;
+var DUPLICATE_WINDOW_MS = 50;
+function rawTextChar(data) {
+  if (data.length === 0 || data.includes("\x1B")) return void 0;
+  if ([...data].length !== 1) return void 0;
+  const codepoint = data.codePointAt(0);
+  if (codepoint < 32 || codepoint === CONTROL_DELETE) return void 0;
+  return data;
+}
+function encodingGuardInput(state, data, now) {
+  if (isKeyRelease(data)) {
+    state.pending = void 0;
+    return void 0;
+  }
+  const char = rawTextChar(data);
+  if (char !== void 0) {
+    const pending = state.pending;
+    state.pending = void 0;
+    if (pending !== void 0 && pending.char === char && now - pending.at <= DUPLICATE_WINDOW_MS) {
+      return { consume: true };
+    }
+    return void 0;
+  }
+  const printable = decodeKittyPrintable(data);
+  state.pending = printable === void 0 ? void 0 : { char: printable, at: now };
+  return void 0;
+}
+function wireKeyEncodingGuard(ui) {
+  const subscribe = ui?.onTerminalInput;
+  if (!subscribe) return () => {
+  };
+  const state = { pending: void 0 };
+  return subscribe((data) => encodingGuardInput(state, data, Date.now()));
+}
+export {
+  encodingGuardInput,
+  wireKeyEncodingGuard
+};
+//# sourceMappingURL=key-encoding-guard-6UOKKTJQ.js.map

package/dist/key-encoding-guard-6UOKKTJQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/runtime/key-encoding-guard.ts"],"sourcesContent":["/**\n * src/client/runtime/key-encoding-guard.ts — one press, one character, whichever encodings the\n * terminal reports it in.\n *\n * A terminal with the kitty keyboard protocol enabled describes a press on two paths: the key\n * event as a `CSI-u` sequence, and the text the key produced as raw bytes. Normally it uses one\n * or the other per press, and nothing here fires. Some terminals emit *both* for the same press\n * — the case upstream pi fixed for one shape and order in 0.70.4 (#3780, \"duplicate printable\n * characters from Kitty keyboard protocol CSI-u plus raw character input on layouts such as\n * Italian\"). pi-tui guards against it in `StdinBuffer.emitDataSequence`, which remembers the\n * codepoint of the last CSI-u printable and drops a raw character that repeats it.\n *\n * That recogniser is `parseUnmodifiedKittyPrintableCodepoint`, and it accepts only the bare\n * forms — `ESC[<cp>u`, `ESC[<cp>:<shifted>u`, `ESC[<cp>::<base>u`. Every form carrying a\n * *modifier parameter* is refused, while `decodeKittyPrintable` accepts those (it masks Caps\n * Lock and Num Lock: `KITTY_PRINTABLE_ALLOWED_MODIFIERS = shift | 64 | 128`). So the dedupe\n * silently stops working the moment the terminal puts a lock bit or a layout alternate in that\n * parameter — a Num Lock that is on by default, or the AltGr characters of a non-US layout —\n * and both copies insert: one press, two characters.\n *\n * The guard is fail-open by construction. A duplicate that escapes costs one character; a\n * keystroke spent on a wrong suppression costs the user's intent, and the second is the only\n * failure here that is not instantly visible and recoverable. So it drops a raw character only\n * when all of these hold: a `CSI-u` printable for exactly that character arrived immediately\n * before it; it is the one drop that `CSI-u` is owed (a second matching character is a second\n * press); and it lands within {@link DUPLICATE_WINDOW_MS}, which the two encodings of a single\n * press always meet because the terminal writes them together. A release rearms nothing: it\n * clears the memory instead, so the release event that follows a press can never make the next\n * deliberate press of the same key disappear.\n *\n * Reads and repeats are left alone on purpose. `key-repeat-guard.ts` owns repeats, and a\n * terminal that reports repeats as CSI-u event-type 2 is only deduped against its own text.\n */\n\nimport { decodeKittyPrintable, isKeyRelease } from \"@earendil-works/pi-tui\";\nimport type { HostUiContext, TerminalInputHandler } from \"./bridge.js\";\n\nconst CONTROL_DELETE = 0x7f;\n/**\n * How long the raw half of a dual-encoded press may trail its CSI-u half. Both halves are\n * written by the terminal as one keystroke, so they arrive within a read or two; the window\n * exists only to bound the damage of a terminal that mixes encodings per press — the one way a\n * deliberate press could sit close enough behind a CSI-u to be mistaken for its text.\n */\nconst DUPLICATE_WINDOW_MS = 50;\n\ninterface EncodingState {\n  /** The printable a CSI-u just delivered, and when — still owed exactly one raw drop. */\n  pending: { char: string; at: number } | undefined;\n}\n\n/** The single printable character this chunk carries as plain text, if it is that. */\nfunction rawTextChar(data: string): string | undefined {\n  // An escape sequence is not text: the CSI-u half of the pair arrives in this shape.\n  if (data.length === 0 || data.includes(\"\\x1b\")) return undefined;\n  if ([...data].length !== 1) return undefined;\n  const codepoint = data.codePointAt(0)!;\n  if (codepoint < 32 || codepoint === CONTROL_DELETE) return undefined;\n  return data;\n}\n\n/**\n * One terminal-input step ahead of the focused component. Consumes only the second encoding of\n * a press the terminal already reported as a key event.\n */\nexport function encodingGuardInput(\n  state: EncodingState,\n  data: string,\n  now: number,\n): { consume: true } | undefined {\n  // A release is not a press: it must never arm a drop, or the key's next press would vanish.\n  if (isKeyRelease(data)) {\n    state.pending = undefined;\n    return undefined;\n  }\n\n  const char = rawTextChar(data);\n  if (char !== undefined) {\n    const pending = state.pending;\n    state.pending = undefined;\n    if (pending !== undefined && pending.char === char && now - pending.at <= DUPLICATE_WINDOW_MS) {\n      return { consume: true };\n    }\n    return undefined;\n  }\n\n  // `decodeKittyPrintable` is the editor's own reading of a key event, including the modifier\n  // combinations the stock dedupe refuses — which is exactly the gap this guard fills.\n  const printable = decodeKittyPrintable(data);\n  state.pending = printable === undefined ? undefined : { char: printable, at: now };\n  return undefined;\n}\n\n/**\n * Wire the guard into the bound TUI. Returns an unsubscribe; call it before re-wiring, since\n * `clearExtensionTerminalInputListeners()` drops the listener on every session rebind.\n *\n * Registered ahead of the repeat guard: the repeat guard consumes CSI-u repeats, and this one\n * needs to see a repeat's key event to recognise the text copy that follows it.\n */\nexport function wireKeyEncodingGuard(ui: HostUiContext | null | undefined): () => void {\n  const subscribe: ((handler: TerminalInputHandler) => () => void) | undefined = ui?.onTerminalInput;\n  if (!subscribe) return () => {};\n  const state: EncodingState = { pending: undefined };\n  return subscribe((data) => encodingGuardInput(state, data, Date.now()));\n}\n"],"mappings":";AAkCA,SAAS,sBAAsB,oBAAoB;AAGnD,IAAM,iBAAiB;AAOvB,IAAM,sBAAsB;AAQ5B,SAAS,YAAY,MAAkC;AAErD,MAAI,KAAK,WAAW,KAAK,KAAK,SAAS,MAAM,EAAG,QAAO;AACvD,MAAI,CAAC,GAAG,IAAI,EAAE,WAAW,EAAG,QAAO;AACnC,QAAM,YAAY,KAAK,YAAY,CAAC;AACpC,MAAI,YAAY,MAAM,cAAc,eAAgB,QAAO;AAC3D,SAAO;AACT;AAMO,SAAS,mBACd,OACA,MACA,KAC+B;AAE/B,MAAI,aAAa,IAAI,GAAG;AACtB,UAAM,UAAU;AAChB,WAAO;AAAA,EACT;AAEA,QAAM,OAAO,YAAY,IAAI;AAC7B,MAAI,SAAS,QAAW;AACtB,UAAM,UAAU,MAAM;AACtB,UAAM,UAAU;AAChB,QAAI,YAAY,UAAa,QAAQ,SAAS,QAAQ,MAAM,QAAQ,MAAM,qBAAqB;AAC7F,aAAO,EAAE,SAAS,KAAK;AAAA,IACzB;AACA,WAAO;AAAA,EACT;AAIA,QAAM,YAAY,qBAAqB,IAAI;AAC3C,QAAM,UAAU,cAAc,SAAY,SAAY,EAAE,MAAM,WAAW,IAAI,IAAI;AACjF,SAAO;AACT;AASO,SAAS,qBAAqB,IAAkD;AACrF,QAAM,YAAyE,IAAI;AACnF,MAAI,CAAC,UAAW,QAAO,MAAM;AAAA,EAAC;AAC9B,QAAM,QAAuB,EAAE,SAAS,OAAU;AAClD,SAAO,UAAU,CAAC,SAAS,mBAAmB,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC;AACxE;","names":[]}

package/docs/keyboard-input.md

@@ -1,9 +1,9 @@
 # Keyboard input in the attached TUI
 
-Two input defects turn one key press into several characters or into escape-sequence
-gibberish. Both live in the local byte path — nothing typed crosses the wire — and both are
-fixed in `src/client/runtime/` rather than by pinning a different pi-tui, because the pinned
-version is what pods and the launcher share.
+Three input defects turn one key press into several characters, the same character twice, or
+into escape-sequence gibberish. All live in the local byte path — nothing typed crosses the
+wire — and all are fixed in `src/client/runtime/` rather than by pinning a different pi-tui,
+because the pinned version is what pods and the launcher share.
 
 ## The path
 
@@ -11,6 +11,7 @@ version is what pods and the launcher share.
 terminal ──bytes──▶ ProcessTerminal ──▶ StdinBuffer ──▶ TUI input listeners ──▶ Editor
                                                                 │
                                                     chords · disconnected-quit ·
+                                                    key-encoding guard ·
                                                     key-repeat guard
 ```
 
@@ -69,6 +70,34 @@ reply may be missed and the theme falls back, which is cosmetic; the prompt stay
 Upstream pi-tui 1.4.0 still flushes these fragments (it only rescues recognizable terminal
 *replies*), so a version bump would not fix this.
 
+## 3. A press reported in both encodings types once (`key-encoding-guard.ts`)
+
+A terminal with the kitty keyboard protocol enabled may describe one press twice: the key
+event as a `CSI-u` sequence **and** the text it produced as raw bytes. pi-tui already guards
+this in `StdinBuffer.emitDataSequence` — it remembers the codepoint of the last CSI-u
+printable and drops a raw character that repeats it — but its recogniser
+(`parseUnmodifiedKittyPrintableCodepoint`) accepts only `ESC[<cp>u`, `ESC[<cp>:<shifted>u` and
+`ESC[<cp>::<base>u`, and refuses every form carrying a *modifier parameter*. `decodeKittyPrintable`
+accepts those, masking Caps Lock and Num Lock (`KITTY_PRINTABLE_ALLOWED_MODIFIERS = shift | 64
+| 128`). So the stock dedupe stops working the moment the terminal puts a modifier bit in that
+parameter — measured here with the lock bits a machine carries without anyone noticing, a Num
+Lock that is on by default (`input:numlock_by_default = true`) or a Caps Lock — and both copies
+insert. Upstream pi fixed the same class of report for one terminal order and shape in
+0.70.4 (#3780, "duplicate printable characters from Kitty keyboard protocol CSI-u plus raw
+character input on layouts such as Italian"); the pinned pi-tui still has the gap.
+
+The guard consumes a raw character only when a CSI-u printable for exactly that character
+arrived immediately before it, only once per CSI-u, and only within 50 ms — the two halves of
+one press are written together, so they always meet that window. It is fail-open by
+construction: an escaped duplicate costs one visible, recoverable character, while a wrong
+suppression would silently eat a keystroke. A release clears the memory rather than arming it,
+so the release event that follows a press can never make the next deliberate press of that key
+disappear. Releases and repeats otherwise stay with `key-repeat-guard.ts`, which owns them.
+
+Left open deliberately: the reversed order (raw text first, then the CSI-u). No observed
+terminal writes it, and deduping it would mean dropping a key *event* on suspicion — the one
+direction where a mistake loses input.
+
 ## Accepted rows
 
 Measured with a pty harness against pi 1.0.2 + pi-tui 1.0.2 (the pinned pair), driving
@@ -81,6 +110,14 @@ inside pi's own `InteractiveMode`:
 | release split past the flush (`\x1b[104;1:` … `3u`) | `h3u` | `h` |
 | press split past the flush | `;1:1u` | that key |
 | OSC reply fragment, then tap `j` | keystroke lost | `j` |
+| Num Lock bit on the CSI-u (`\x1b[97;129u` then `a`) | `aa` | `a` |
+| layout base + Num Lock (`\x1b[97:97:97;129u` then `a`) | `aa` | `a` |
+| symbol press with Num Lock (`\x1b[64;129u` then `@`) | `@@` | `@` |
+| Caps Lock bit (`\x1b[65;65u` then `A`) | `AA` | `A` |
+| both halves in one read (`\x1b[104;129uh`) | `hh` | `h` |
+| stock dedupe already covers it: `\x1b[64:64:50u` then `@` | `@` | `@` |
+| CSI-u half lost, same key 200 ms later | `aa` | `aa` |
+| release between the halves, then that key again | press kept | unchanged |
 
 Everything else must stay exactly as it was, and does: a tap inserts one character, two
 deliberate taps of the same key insert two, held Backspace and arrows still repeat, a
@@ -88,4 +125,4 @@ bracketed paste arrives verbatim, a legacy terminal without releases is untouche
 stray fragment (`\x1b[1` followed later by another key) costs neither keystroke.
 
 `PI_TUI_ESC_TIMEOUT` only widens the lone-ESC window, not the 50 ms sequence window, so it is
-not a workaround for either defect.
+not a workaround for any of these defects.

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.22"
 .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.22"
 .SH "NAME"
 \fBpipod\fR \- run pi coding\-agent sessions in server\-managed pods
 .SH SYNOPSIS
@@ -713,8 +713,9 @@ Quitting detaches: the pod keeps running until the server's idle policy reaps
 it or `pipod stop` stops it\. Raw pod shells are not available\.
 Attaching to an archived pod offers to restore it first\.
 
-Holding a character key types it once: key repeat stays available for
-Backspace, Tab and the arrow keys, where it is useful while editing\.
+Holding a character key types it once, and a press the terminal reports in both of its
+encodings types once too: key repeat stays available for Backspace, Tab and the arrow keys,
+where it is useful while editing\.
 
 After \-\-:
   <prompt…>              Words are sent to the session as a startup prompt

package/man/pipod.1.md

@@ -703,8 +703,9 @@ Quitting detaches: the pod keeps running until the server's idle policy reaps
 it or `pipod stop` stops it. Raw pod shells are not available.
 Attaching to an archived pod offers to restore it first.
 
-Holding a character key types it once: key repeat stays available for
-Backspace, Tab and the arrow keys, where it is useful while editing.
+Holding a character key types it once, and a press the terminal reports in both of its
+encodings types once too: key repeat stays available for Backspace, Tab and the arrow keys,
+where it is useful while editing.
 
 After --:
   <prompt…>              Words are sent to the session as a startup prompt

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@pipod/cli",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@pipod/cli",
-      "version": "0.1.20",
+      "version": "0.1.22",
       "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.22",
   "description": "Run pi coding-agent sessions in server-managed pods",
   "type": "module",
   "license": "AGPL-3.0-only",