@pipod/cli 0.1.21 → 0.1.23

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/dist/{stdin-fragment-guard-SPIJC7GT.js → stdin-fragment-guard-DHHVSIXM.js}

@@ -14,6 +14,7 @@ var LONE_ESCAPE = "\x1B";
 var PASTE_START = "\x1B[200~";
 var CSI_START = "\x1B[";
 var NEGOTIATION_PREFIX = /^\x1b\[\?[\d;]*$/;
+var SGR_MOUSE_REPORT = /^\x1b\[<\d+;\d+;\d+[Mm]/;
 var PATCHED = /* @__PURE__ */ Symbol.for("pi-pod.stdin-fragment-guard");
 var dropped = 0;
 var held = /* @__PURE__ */ new WeakMap();
@@ -46,7 +47,7 @@ function guardStdinFragments() {
     held.delete(this);
     const text = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
     const rejoined = fragment + text;
-    if (isKey(rejoined)) {
+    if (isKey(rejoined) || SGR_MOUSE_REPORT.test(rejoined)) {
       process.call(this, rejoined);
       return;
     }
@@ -58,4 +59,4 @@ function guardStdinFragments() {
 export {
   guardStdinFragments
 };
-//# sourceMappingURL=stdin-fragment-guard-SPIJC7GT.js.map
+//# sourceMappingURL=stdin-fragment-guard-DHHVSIXM.js.map

package/dist/stdin-fragment-guard-DHHVSIXM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/runtime/stdin-fragment-guard.ts"],"sourcesContent":["/**\n * src/client/runtime/stdin-fragment-guard.ts — an incomplete escape fragment is never typed.\n *\n * pi-tui's StdinBuffer splits stdin into whole key sequences; whatever it cannot complete after\n * a short wait is flushed as keyboard input (50 ms for a partial sequence, 10 ms for a lone\n * ESC). That timeout exists so a real Escape key press is not held forever, but it also turns a\n * *fragment* into text: a key release arriving in two pieces types its tail — \"3\", \"u\" — at the\n * cursor, and behind a multiplexer a split is routine (measured: tmux forwards a split\n * verbatim). The same window swallows keystrokes that land while an unterminated terminal reply\n * is buffered.\n *\n * At the moment of the flush the distinction is exact: the buffer is either a lone ESC (a key)\n * or an unterminated escape sequence (never a key). Dropping the latter would leave its tail to\n * be typed instead, so the fragment is held for exactly one more read: if the bytes that follow\n * complete a key or fullscreen mouse report, the input is delivered as if it had never split.\n * Otherwise the fragment is discarded and those bytes are read on their own. Bounded by\n * construction — a held\n * fragment never survives the next chunk, so a stray fragment cannot swallow typing. Upstream\n * pi-tui still flushes these fragments (1.4.0 only rescues recognizable terminal *replies*), so\n * a version bump cannot fix it for us.\n *\n * This patches a pinned dependency's class, not our own code: it is deliberately narrow (only\n * the timeout flush and the read that may complete it), feature-detected, applied once, and\n * coupled to pi-tui 1.0.2's StdinBuffer contract. Re-check it on a pi-tui bump (the pin is\n * enforced by `npm run lint`).\n */\nimport {\n  decodeKittyPrintable,\n  isKeyRelease,\n  isKeyRepeat,\n  parseKey,\n  StdinBuffer,\n} from \"@earendil-works/pi-tui\";\nimport { debug } from \"../../log.js\";\n\nconst LONE_ESCAPE = \"\\x1b\";\n/** Pasted runs arrive complete; never drop a chunk that carries one. */\nconst PASTE_START = \"\\x1b[200~\";\n/**\n * pi-tui's terminal reassembles these *above* the buffer: a split kitty-flags or DA1 reply is\n * held there for its own window and joined to the next bytes. Leaving them untouched keeps that\n * working — the fragment guard only owns what nothing else would interpret.\n */\nconst CSI_START = \"\\x1b[\";\nconst NEGOTIATION_PREFIX = /^\\x1b\\[\\?[\\d;]*$/;\n/** A complete SGR mouse report; following reports/keystrokes belong to the same read. */\nconst SGR_MOUSE_REPORT = /^\\x1b\\[<\\d+;\\d+;\\d+[Mm]/;\n/** Set on the patched method so a second import (or a re-wire) cannot double-wrap it. */\nconst PATCHED = Symbol.for(\"pi-pod.stdin-fragment-guard\");\n/** Count of fragments dropped this process — reported only through debug logging. */\nlet dropped = 0;\n\n/** The fragment a timed-out flush released, waiting for the read that may complete it. */\nconst held = new WeakMap<StdinBuffer, string>();\n\ntype Flush = (this: StdinBuffer) => string[];\ntype Process = (this: StdinBuffer, data: string | Uint8Array) => void;\n\n/** True when `data` is one complete key, whatever the terminal encoded it as. */\nfunction isKey(data: string): boolean {\n  return (\n    parseKey(data) !== undefined ||\n    decodeKittyPrintable(data) !== undefined ||\n    isKeyRelease(data) ||\n    isKeyRepeat(data)\n  );\n}\n\n/**\n * Install the guard once per process. Safe to call from every session start: the prototype is\n * shared by the TUI pi builds and by this launcher, so one patch covers both.\n */\nexport function guardStdinFragments(): void {\n  const prototype = StdinBuffer.prototype as unknown as Record<PropertyKey, unknown> & {\n    flush: Flush;\n  };\n  if (prototype[PATCHED] === true) return;\n\n  const flush = prototype.flush;\n  const process = prototype.process;\n  if (typeof flush !== \"function\" || typeof process !== \"function\") return;\n  prototype[PATCHED] = true;\n  prototype.flush = function guardedFlush(this: StdinBuffer): string[] {\n    return flush.call(this).filter((sequence) => {\n      if (!sequence.startsWith(LONE_ESCAPE) || sequence === LONE_ESCAPE) return true;\n      if (sequence.includes(PASTE_START)) return true;\n      if (sequence === CSI_START || NEGOTIATION_PREFIX.test(sequence)) return true;\n      // A complete sequence would have been emitted already; anything here that does not parse\n      // is the unterminated remainder the timeout released.\n      if (parseKey(sequence) !== undefined) return true;\n      held.set(this, sequence);\n      return false;\n    });\n  };\n\n  prototype.process = function guardedProcess(this: StdinBuffer, data: string | Uint8Array): void {\n    const fragment = held.get(this);\n    if (fragment === undefined) {\n      process.call(this, data);\n      return;\n    }\n    held.delete(this);\n    const text = typeof data === \"string\" ? data : Buffer.from(data).toString(\"utf8\");\n    const rejoined = fragment + text;\n    // Fullscreen owns mouse input too. Dropping a timed-out report's head would type its\n    // coordinates into the editor. Let StdinBuffer split any coalesced input after the report.\n    if (isKey(rejoined) || SGR_MOUSE_REPORT.test(rejoined)) {\n      process.call(this, rejoined);\n      return;\n    }\n    // The tail never came: drop the fragment, keep the user's bytes intact.\n    dropped += 1;\n    debug(`stdin fragment guard: dropped ${JSON.stringify(fragment)} (${dropped} this session)`);\n    process.call(this, data);\n  };\n}\n"],"mappings":";;;;;AA0BA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP,IAAM,cAAc;AAEpB,IAAM,cAAc;AAMpB,IAAM,YAAY;AAClB,IAAM,qBAAqB;AAE3B,IAAM,mBAAmB;AAEzB,IAAM,UAAU,uBAAO,IAAI,6BAA6B;AAExD,IAAI,UAAU;AAGd,IAAM,OAAO,oBAAI,QAA6B;AAM9C,SAAS,MAAM,MAAuB;AACpC,SACE,SAAS,IAAI,MAAM,UACnB,qBAAqB,IAAI,MAAM,UAC/B,aAAa,IAAI,KACjB,YAAY,IAAI;AAEpB;AAMO,SAAS,sBAA4B;AAC1C,QAAM,YAAY,YAAY;AAG9B,MAAI,UAAU,OAAO,MAAM,KAAM;AAEjC,QAAM,QAAQ,UAAU;AACxB,QAAM,UAAU,UAAU;AAC1B,MAAI,OAAO,UAAU,cAAc,OAAO,YAAY,WAAY;AAClE,YAAU,OAAO,IAAI;AACrB,YAAU,QAAQ,SAAS,eAA0C;AACnE,WAAO,MAAM,KAAK,IAAI,EAAE,OAAO,CAAC,aAAa;AAC3C,UAAI,CAAC,SAAS,WAAW,WAAW,KAAK,aAAa,YAAa,QAAO;AAC1E,UAAI,SAAS,SAAS,WAAW,EAAG,QAAO;AAC3C,UAAI,aAAa,aAAa,mBAAmB,KAAK,QAAQ,EAAG,QAAO;AAGxE,UAAI,SAAS,QAAQ,MAAM,OAAW,QAAO;AAC7C,WAAK,IAAI,MAAM,QAAQ;AACvB,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AAEA,YAAU,UAAU,SAAS,eAAkC,MAAiC;AAC9F,UAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,QAAI,aAAa,QAAW;AAC1B,cAAQ,KAAK,MAAM,IAAI;AACvB;AAAA,IACF;AACA,SAAK,OAAO,IAAI;AAChB,UAAM,OAAO,OAAO,SAAS,WAAW,OAAO,OAAO,KAAK,IAAI,EAAE,SAAS,MAAM;AAChF,UAAM,WAAW,WAAW;AAG5B,QAAI,MAAM,QAAQ,KAAK,iBAAiB,KAAK,QAAQ,GAAG;AACtD,cAAQ,KAAK,MAAM,QAAQ;AAC3B;AAAA,IACF;AAEA,eAAW;AACX,UAAM,iCAAiC,KAAK,UAAU,QAAQ,CAAC,KAAK,OAAO,gBAAgB;AAC3F,YAAQ,KAAK,MAAM,IAAI;AAAA,EACzB;AACF;","names":[]}

package/docs/fullscreen.md

@@ -0,0 +1,57 @@
+# Fullscreen Pi in pipod
+
+Pipod uses its bundled Pi renderer locally; fullscreen does not need a different pod image
+or a remote terminal. Launch or attach with an explicit layout:
+
+```sh
+pipod -- --tui-mode fullscreen
+pipod attach <pod> -- --tui-mode fullscreen
+pipod attach <pod> -- --tui-mode regular
+```
+
+The override applies only to this client. Without it, Pi uses the derived pod/host display
+settings. Fullscreen keeps the editor and footer fixed while the transcript scrolls in the
+alternate screen; regular mode uses the terminal's scrollback. `/settings` can switch layouts
+without disconnecting. Display changes made there are session-local, not saved account or
+template configuration.
+
+## Mouse preferences
+
+The pod's display projection includes `tuiMode`, `fullscreenExitOutput`,
+`fullscreenScrollbar`, `fullscreenCopyOnSelect` (boolean), and
+`fullscreenWheelScrollLines` (`"auto"` or an integer from 1 through 100). Invalid pod values
+are ignored; command-valued settings never cross this boundary. Host-only preferences remain
+local. Both the server's manifest producer and the CLI validator need the new fields for pod
+copy/scroll preferences to reach an attached client. An already-running shim keeps its old
+projection until restarted; a server source update alone does not change it.
+
+## Input compatibility
+
+Fullscreen captures mouse reports. A wheel/click/drag/release report split across reads,
+past pi-tui's sequence timeout, must still reach the renderer as one report—not type its
+coordinates into the editor. The [stdin fragment guard](keyboard-input.md) rejoins a complete
+SGR mouse report and preserves any following input in the same read. A malformed fragment
+still cannot swallow the next ordinary keystroke. This retains the existing bound: recovery
+covers the next read, not arbitrarily delayed multi-fragment streams.
+
+## Manual acceptance
+
+Use a real pod in an agent-owned tmux session. Build and invoke the checkout by absolute path;
+do not accidentally verify a globally installed CLI instead. Keep and archive only the pod
+you create. No model call is needed: `!` shell commands can generate transcript content.
+
+Check the alternate-screen/mouse flags, not only visible text. Exercise:
+
+- Startup and reattach with both explicit layouts and the default.
+- Narrow/wide terminal resizes; editor/footer stay visible and input remains usable.
+- Transcript keyboard and wheel scrolling, including split SGR reports ending in `M` and `m`.
+- A completed report followed by printable input in the same read; only the printable input
+  enters the editor. Malformed fragments must not discard ordinary typing.
+- `/settings` layout switching and the detach chord afterward.
+- Detach/quit returns to the main screen with mouse reporting off, and leaves the pod running.
+- Real generated shim → validated manifest → Pi's file-backed SettingsManager: both copy
+  booleans, `"auto"`, numeric wheel bounds, invalid values, and unchanged host-only settings.
+
+When sending a partial mouse report through tmux, use `send-keys -H` for its hex bytes. A
+trailing semicolon in a `send-keys -l` argument is a tmux command separator and can be removed,
+turning a valid intended report into malformed diagnostic input.

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
 ```
 
@@ -57,9 +58,12 @@ reply is buffered.
 
 At the flush the distinction is exact: the buffer is a lone ESC (a key) or an unterminated
 escape sequence (never a key). The guard holds the fragment for exactly the next read and
-rejoins it only if the two together parse as one key — a split release then behaves as if it
-had never split. Otherwise the fragment is discarded and the user's bytes are read on their
-own, so a stray fragment cannot swallow the next keystroke.
+rejoins it only if the two together parse as one key or start with a complete SGR mouse report
+(`ESC [ < button ; column ; row M/m`). Fullscreen mode captures wheel, click, drag and release
+reports: treating them as non-keys dropped the report's head and typed its coordinates into
+the editor. Any input coalesced after the completed report goes through `StdinBuffer` normally.
+Otherwise the fragment is discarded and the user's bytes are read on their own, so a stray
+fragment cannot swallow the next keystroke.
 
 Fragments shaped like pi-tui's own keyboard-protocol replies are left untouched: the terminal
 reassembles those above the buffer already, and the guard must not starve that path. A split
@@ -69,6 +73,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 +113,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 +128,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/man/pipod-config.5

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

package/man/pipod.1

@@ -1,4 +1,4 @@
-.TH "PIPOD" "1" "November 2026" "0.1.21"
+.TH "PIPOD" "1" "November 2026" "0.1.23"
 .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.21",
+  "version": "0.1.23",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@pipod/cli",
-      "version": "0.1.21",
+      "version": "0.1.23",
       "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.21",
+  "version": "0.1.23",
   "description": "Run pi coding-agent sessions in server-managed pods",
   "type": "module",
   "license": "AGPL-3.0-only",

package/dist/stdin-fragment-guard-SPIJC7GT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/client/runtime/stdin-fragment-guard.ts"],"sourcesContent":["/**\n * src/client/runtime/stdin-fragment-guard.ts — an incomplete escape fragment is never typed.\n *\n * pi-tui's StdinBuffer splits stdin into whole key sequences; whatever it cannot complete after\n * a short wait is flushed as keyboard input (50 ms for a partial sequence, 10 ms for a lone\n * ESC). That timeout exists so a real Escape key press is not held forever, but it also turns a\n * *fragment* into text: a key release arriving in two pieces types its tail — \"3\", \"u\" — at the\n * cursor, and behind a multiplexer a split is routine (measured: tmux forwards a split\n * verbatim). The same window swallows keystrokes that land while an unterminated terminal reply\n * is buffered.\n *\n * At the moment of the flush the distinction is exact: the buffer is either a lone ESC (a key)\n * or an unterminated escape sequence (never a key). Dropping the latter would leave its tail to\n * be typed instead, so the fragment is held for exactly one more read: if the bytes that follow\n * complete a key, the key is delivered as if it had never been split; if they do not, the\n * fragment is discarded and those bytes are read on their own. Bounded by construction — a held\n * fragment never survives the next chunk, so a stray fragment cannot swallow typing. Upstream\n * pi-tui still flushes these fragments (1.4.0 only rescues recognizable terminal *replies*), so\n * a version bump cannot fix it for us.\n *\n * This patches a pinned dependency's class, not our own code: it is deliberately narrow (only\n * the timeout flush and the read that may complete it), feature-detected, applied once, and\n * coupled to pi-tui 1.0.2's StdinBuffer contract. Re-check it on a pi-tui bump (the pin is\n * enforced by `npm run lint`).\n */\nimport {\n  decodeKittyPrintable,\n  isKeyRelease,\n  isKeyRepeat,\n  parseKey,\n  StdinBuffer,\n} from \"@earendil-works/pi-tui\";\nimport { debug } from \"../../log.js\";\n\nconst LONE_ESCAPE = \"\\x1b\";\n/** Pasted runs arrive complete; never drop a chunk that carries one. */\nconst PASTE_START = \"\\x1b[200~\";\n/**\n * pi-tui's terminal reassembles these *above* the buffer: a split kitty-flags or DA1 reply is\n * held there for its own window and joined to the next bytes. Leaving them untouched keeps that\n * working — the fragment guard only owns what nothing else would interpret.\n */\nconst CSI_START = \"\\x1b[\";\nconst NEGOTIATION_PREFIX = /^\\x1b\\[\\?[\\d;]*$/;\n/** Set on the patched method so a second import (or a re-wire) cannot double-wrap it. */\nconst PATCHED = Symbol.for(\"pi-pod.stdin-fragment-guard\");\n/** Count of fragments dropped this process — reported only through debug logging. */\nlet dropped = 0;\n\n/** The fragment a timed-out flush released, waiting for the read that may complete it. */\nconst held = new WeakMap<StdinBuffer, string>();\n\ntype Flush = (this: StdinBuffer) => string[];\ntype Process = (this: StdinBuffer, data: string | Uint8Array) => void;\n\n/** True when `data` is one complete key, whatever the terminal encoded it as. */\nfunction isKey(data: string): boolean {\n  return (\n    parseKey(data) !== undefined ||\n    decodeKittyPrintable(data) !== undefined ||\n    isKeyRelease(data) ||\n    isKeyRepeat(data)\n  );\n}\n\n/**\n * Install the guard once per process. Safe to call from every session start: the prototype is\n * shared by the TUI pi builds and by this launcher, so one patch covers both.\n */\nexport function guardStdinFragments(): void {\n  const prototype = StdinBuffer.prototype as unknown as Record<PropertyKey, unknown> & {\n    flush: Flush;\n  };\n  if (prototype[PATCHED] === true) return;\n\n  const flush = prototype.flush;\n  const process = prototype.process;\n  if (typeof flush !== \"function\" || typeof process !== \"function\") return;\n  prototype[PATCHED] = true;\n  prototype.flush = function guardedFlush(this: StdinBuffer): string[] {\n    return flush.call(this).filter((sequence) => {\n      if (!sequence.startsWith(LONE_ESCAPE) || sequence === LONE_ESCAPE) return true;\n      if (sequence.includes(PASTE_START)) return true;\n      if (sequence === CSI_START || NEGOTIATION_PREFIX.test(sequence)) return true;\n      // A complete sequence would have been emitted already; anything here that does not parse\n      // is the unterminated remainder the timeout released.\n      if (parseKey(sequence) !== undefined) return true;\n      held.set(this, sequence);\n      return false;\n    });\n  };\n\n  prototype.process = function guardedProcess(this: StdinBuffer, data: string | Uint8Array): void {\n    const fragment = held.get(this);\n    if (fragment === undefined) {\n      process.call(this, data);\n      return;\n    }\n    held.delete(this);\n    const text = typeof data === \"string\" ? data : Buffer.from(data).toString(\"utf8\");\n    const rejoined = fragment + text;\n    if (isKey(rejoined)) {\n      process.call(this, rejoined);\n      return;\n    }\n    // The tail never came: drop the fragment, keep the user's bytes intact.\n    dropped += 1;\n    debug(`stdin fragment guard: dropped ${JSON.stringify(fragment)} (${dropped} this session)`);\n    process.call(this, data);\n  };\n}\n"],"mappings":";;;;;AAyBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGP,IAAM,cAAc;AAEpB,IAAM,cAAc;AAMpB,IAAM,YAAY;AAClB,IAAM,qBAAqB;AAE3B,IAAM,UAAU,uBAAO,IAAI,6BAA6B;AAExD,IAAI,UAAU;AAGd,IAAM,OAAO,oBAAI,QAA6B;AAM9C,SAAS,MAAM,MAAuB;AACpC,SACE,SAAS,IAAI,MAAM,UACnB,qBAAqB,IAAI,MAAM,UAC/B,aAAa,IAAI,KACjB,YAAY,IAAI;AAEpB;AAMO,SAAS,sBAA4B;AAC1C,QAAM,YAAY,YAAY;AAG9B,MAAI,UAAU,OAAO,MAAM,KAAM;AAEjC,QAAM,QAAQ,UAAU;AACxB,QAAM,UAAU,UAAU;AAC1B,MAAI,OAAO,UAAU,cAAc,OAAO,YAAY,WAAY;AAClE,YAAU,OAAO,IAAI;AACrB,YAAU,QAAQ,SAAS,eAA0C;AACnE,WAAO,MAAM,KAAK,IAAI,EAAE,OAAO,CAAC,aAAa;AAC3C,UAAI,CAAC,SAAS,WAAW,WAAW,KAAK,aAAa,YAAa,QAAO;AAC1E,UAAI,SAAS,SAAS,WAAW,EAAG,QAAO;AAC3C,UAAI,aAAa,aAAa,mBAAmB,KAAK,QAAQ,EAAG,QAAO;AAGxE,UAAI,SAAS,QAAQ,MAAM,OAAW,QAAO;AAC7C,WAAK,IAAI,MAAM,QAAQ;AACvB,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AAEA,YAAU,UAAU,SAAS,eAAkC,MAAiC;AAC9F,UAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,QAAI,aAAa,QAAW;AAC1B,cAAQ,KAAK,MAAM,IAAI;AACvB;AAAA,IACF;AACA,SAAK,OAAO,IAAI;AAChB,UAAM,OAAO,OAAO,SAAS,WAAW,OAAO,OAAO,KAAK,IAAI,EAAE,SAAS,MAAM;AAChF,UAAM,WAAW,WAAW;AAC5B,QAAI,MAAM,QAAQ,GAAG;AACnB,cAAQ,KAAK,MAAM,QAAQ;AAC3B;AAAA,IACF;AAEA,eAAW;AACX,UAAM,iCAAiC,KAAK,UAAU,QAAQ,CAAC,KAAK,OAAO,gBAAgB;AAC3F,YAAQ,KAAK,MAAM,IAAI;AAAA,EACzB;AACF;","names":[]}