create-pmos 0.7.1 → 0.7.2

package/README.md

@@ -333,6 +333,35 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.7.2
+
+**A fix — read this if you use the Terminal Workspace on a machine with `tmux` installed.**
+
+0.7.0 and 0.7.1 both shipped a workspace terminal that renders **gibberish** there. Box-drawing
+characters, check marks, spinners, emoji and accented letters all arrived damaged, and the output
+lost its structure — which matters because agent CLIs print those constantly, so in practice most
+frames were affected. If your terminal has looked broken since 0.7.0, this is why, and it was our
+bug, not your setup.
+
+The cause: the workspace drives `tmux` in control mode, and that stream is **bytes**. `tmux` escapes
+only the control characters and the backslash — every byte of a UTF-8 character passes through raw.
+The workspace decoded that stream as text and then narrowed it back to bytes, which does not merely
+lose characters, it *manufactures* control codes out of the wreckage. `┌` became a **form feed**,
+which is why the layout collapsed and not just the glyphs.
+
+- **Fixed.** The control stream is now handled as bytes end to end, with a single UTF-8 decode in
+  one place. A character split across two `tmux` frames still survives.
+- **A second, smaller source of the same symptom, also fixed.** The scrollback ring trims from the
+  front once it fills, and it used to cut at an arbitrary offset — routinely *inside* an escape
+  sequence, so the leftover fragment replayed as literal rubble like `5;203m` when you reattached.
+  It now cuts at a line boundary.
+- **Nothing else changed.** 0.7.2 carries this fix and only this fix.
+
+**You were only affected if `tmux` is on your PATH.** The workspace falls back to a direct terminal
+when it is not, and that path never had the defect — which is exactly why this survived two
+releases. The regression test now reports which of the two transports it exercised, so a green run
+on a machine without `tmux` can no longer read as if it had covered the one that broke.
+
 ## What's new in 0.7.1
 
 **A correction to 0.7.0 — read this if you used the review surface.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@0c57593
+kernel-source: pmos@bd8056d
 assembled: 2026-07-28
 mode: vendor

package/workspace/lib/tmux-control.js

@@ -17,28 +17,55 @@
 // The protocol, as it actually arrives on the wire:
 //   \x1bP1000p                       DCS introducer, once, before the first line
 //   %begin <t> <n> <f> … %end        a command's reply is wrapped in a begin/end block
-//   %output %0 line-1\015\012…       pane bytes, NON-PRINTABLES OCTAL-ESCAPED (\015 = CR)
+//   %output %0 line-1\015\012…       pane bytes, with SOME bytes octal-escaped (\015 = CR)
 //   %exit [reason]                   the control client is going away
 //   %session-changed, %window-*, …   notifications we do not need
-// Lines are CRLF-terminated. Because every byte outside printable ASCII is octal-escaped, the
-// control stream itself is pure ASCII — so reading the client PTY as utf8 is safe, and the real
-// UTF-8 decoding happens HERE, after unescaping, with a streaming decoder (a multi-byte character
-// can be split across two %output frames).
+//
+// THE CONTROL STREAM IS BYTES, NOT TEXT. tmux escapes only `c < 0x20` and the backslash itself
+// (control.c); every byte >= 0x80 is written through RAW. So a `─` (E2 94 80) arrives on the wire
+// as three raw high bytes, NOT as three octal escapes. Reading the client PTY as a utf8 STRING and
+// then narrowing each code unit back to a byte therefore destroys every non-ASCII character —
+// U+2500 & 0xff = 0x00, U+250C & 0xff = 0x0C (a form feed), U+2713 & 0xff = 0x13 — which is
+// injected control codes and replacement characters in the pane: box-drawing rubble, mangled
+// layout, gibberish. Verified against tmux 3.4.
+//
+// So this parser works on BUFFERS end to end, and the single UTF-8 decode happens HERE, after
+// unescaping, with a per-pane streaming decoder (a multi-byte character can be split across two
+// %output frames). The caller must read the control client's PTY with `encoding: null`.
 
 const { StringDecoder } = require('string_decoder');
 
+const LF = 0x0a, CR = 0x0d, BACKSLASH = 0x5c, SPACE = 0x20, PCT = 0x25;
+const EMPTY = Buffer.alloc(0);
+const DCS = Buffer.from('\x1bP1000p', 'latin1');       // introducer, once, before the first line
+const ST = Buffer.from('\x1b\\', 'latin1');            // string terminator, may trail the last
+
+const isOct = (b) => b >= 0x30 && b <= 0x37;
+
+// A control-mode chunk is a byte stream. A string is accepted for ASCII test fixtures and is read
+// as latin1 — one code unit per byte — because that is the only faithful string view of bytes.
+const toBytes = (chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'latin1'));
+
+function startsWithAscii(buf, s) {
+  if (buf.length < s.length) return false;
+  for (let i = 0; i < s.length; i++) if (buf[i] !== s.charCodeAt(i)) return false;
+  return true;
+}
+
 // tmux escapes a byte as a backslash + exactly three octal digits (backslash itself is \134),
-// so there is no two-character `\\` case to handle — only the octal form.
-function unescapeToBytes(s) {
-  const out = Buffer.allocUnsafe(s.length);
+// so there is no two-character `\\` case to handle — only the octal form. Every other byte,
+// INCLUDING the raw >= 0x80 bytes of a UTF-8 sequence, passes through untouched.
+function unescapeToBytes(input) {
+  const buf = toBytes(input);
+  const out = Buffer.allocUnsafe(buf.length);
   let n = 0;
-  for (let i = 0; i < s.length; i++) {
-    const c = s.charCodeAt(i);
-    if (c === 0x5c && i + 3 < s.length) {                       // '\'
-      const oct = s.slice(i + 1, i + 4);
-      if (/^[0-7]{3}$/.test(oct)) { out[n++] = parseInt(oct, 8) & 0xff; i += 3; continue; }
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === BACKSLASH && i + 3 < buf.length && isOct(buf[i + 1]) && isOct(buf[i + 2]) && isOct(buf[i + 3])) {
+      out[n++] = (((buf[i + 1] - 0x30) << 6) | ((buf[i + 2] - 0x30) << 3) | (buf[i + 3] - 0x30)) & 0xff;
+      i += 3;
+      continue;
     }
-    out[n++] = c & 0xff;
+    out[n++] = buf[i];
   }
   return out.subarray(0, n);
 }
@@ -49,51 +76,68 @@ function unescapeToBytes(s) {
  * @param {(paneId: string, text: string) => void} h.onOutput  decoded pane bytes
  * @param {(reason: string) => void} [h.onExit]                %exit seen
  * @param {(lines: string[], isError: boolean) => void} [h.onBlock]  a %begin…%end command reply
- * @returns {{feed: (chunk: string) => void}}
+ * @returns {{feed: (chunk: Buffer|string) => void}}
  */
 function createParser({ onOutput, onExit, onBlock } = {}) {
-  let pending = '';                       // partial line carried between chunks
+  let pending = EMPTY;                    // partial line carried between chunks, as BYTES
   let inBlock = false;
   let block = [];
   const decoders = new Map();             // paneId → StringDecoder, for split multi-byte chars
 
   function line(raw) {
     // The DCS introducer rides in front of the very first line; the terminator can trail the last.
-    let l = raw.replace(/^\x1bP1000p/, '').replace(/\x1b\\$/, '');
+    let l = raw;
+    if (startsWithAscii(l, '\x1bP1000p')) l = l.subarray(DCS.length);
+    if (l.length >= ST.length && l[l.length - 2] === ST[0] && l[l.length - 1] === ST[1]) {
+      l = l.subarray(0, l.length - ST.length);
+    }
     if (inBlock) {
-      if (l.startsWith('%end') || l.startsWith('%error')) {
+      // A command reply is text (it is what tmux printed for `capture-pane` and friends), so it
+      // decodes as UTF-8 in one shot — a reply line always arrives whole.
+      if (startsWithAscii(l, '%end') || startsWithAscii(l, '%error')) {
         inBlock = false;
-        if (onBlock) onBlock(block, l.startsWith('%error'));
+        if (onBlock) onBlock(block, startsWithAscii(l, '%error'));
         block = [];
-      } else block.push(l);
+      } else block.push(l.toString('utf8'));
       return;
     }
-    if (l.startsWith('%begin')) { inBlock = true; block = []; return; }
-    if (l.startsWith('%output ')) {
-      // %output %<pane> <escaped bytes>   — the data may legitimately be empty
-      const m = /^%output (%\d+) ?([\s\S]*)$/.exec(l);
-      if (!m || !onOutput) return;
-      const pane = m[1];
+    if (startsWithAscii(l, '%begin')) { inBlock = true; block = []; return; }
+    if (startsWithAscii(l, '%output ')) {
+      // %output %<pane> <bytes>   — the data may legitimately be empty. The header is pure ASCII,
+      // so it is scanned by byte offset; everything after the separating space is PANE BYTES and is
+      // never treated as text until the decoder below.
+      if (!onOutput) return;
+      let j = 8;                                             // past '%output '
+      if (l[j] !== PCT) return;                              // '%' of the pane id
+      let k = j + 1;
+      while (k < l.length && l[k] >= 0x30 && l[k] <= 0x39) k++;
+      if (k === j + 1) return;                               // no digits — not a pane id
+      const pane = l.subarray(j, k).toString('latin1');
+      const data = l[k] === SPACE ? l.subarray(k + 1) : l.subarray(k);
       let dec = decoders.get(pane);
       if (!dec) { dec = new StringDecoder('utf8'); decoders.set(pane, dec); }
-      const text = dec.write(unescapeToBytes(m[2]));
+      const text = dec.write(unescapeToBytes(data));
       if (text) onOutput(pane, text);
       return;
     }
-    if (l.startsWith('%exit')) { if (onExit) onExit(l.slice(5).trim()); return; }
+    if (startsWithAscii(l, '%exit')) { if (onExit) onExit(l.subarray(5).toString('utf8').trim()); return; }
     // every other %notification (session-changed, window-add, layout-change, …) is not needed here
   }
 
   return {
     feed(chunk) {
-      pending += chunk;
-      let i;
-      while ((i = pending.indexOf('\n')) !== -1) {
-        let l = pending.slice(0, i);
-        pending = pending.slice(i + 1);
-        if (l.endsWith('\r')) l = l.slice(0, -1);
-        line(l);
+      const b = toBytes(chunk);
+      pending = pending.length ? Buffer.concat([pending, b]) : b;
+      // %output data never contains a raw LF — tmux escapes every byte below 0x20 — so splitting
+      // the stream on LF can never cut a frame in half.
+      let start = 0, i;
+      while ((i = pending.indexOf(LF, start)) !== -1) {
+        const end = i > start && pending[i - 1] === CR ? i - 1 : i;
+        line(pending.subarray(start, end));
+        start = i + 1;
       }
+      // Copy the remainder rather than holding a subarray: a subarray pins the whole parent chunk.
+      pending = start >= pending.length ? EMPTY : (start ? Buffer.from(pending.subarray(start)) : pending);
     },
   };
 }

package/workspace/server.js

@@ -898,9 +898,27 @@ function heartbeat() {
 }
 try { const _hb = setInterval(heartbeat, LIVENESS_MS); if (_hb.unref) _hb.unref(); } catch {}
 
+// Trim the ring from the FRONT at a LINE boundary. A blind slice cuts wherever the byte count
+// lands — which is routinely INSIDE an escape sequence, and the truncated tail then replays as
+// literal rubble ("5;203m") the next time a client attaches and we write the buffer to xterm.js;
+// or BETWEEN the halves of a surrogate pair, and the lone surrogate becomes U+FFFD on the JSON hop
+// to the browser. Neither is recoverable downstream. An escape sequence never spans a newline, so
+// moving the cut forward to just past the next one makes both impossible. If the kept region has no
+// newline near its head (one enormous line) the raw cut stands, stepping off a lone low surrogate.
+const TRIM_SCAN = 8192;                                // how far past the cut to look for a boundary
+function trimBuf(buf, limit) {
+  if (buf.length <= limit) return buf;
+  let cut = buf.length - limit;
+  const nl = buf.indexOf('\n', cut);
+  if (nl !== -1 && nl - cut <= TRIM_SCAN) return buf.slice(nl + 1);
+  const c = buf.charCodeAt(cut);
+  if (c >= 0xdc00 && c <= 0xdfff) cut++;               // never start on a low surrogate
+  return buf.slice(cut);
+}
+
 function appendBuf(s, data) {
   s.buf += data;
-  if (s.buf.length > SCROLLBACK) s.buf = s.buf.slice(s.buf.length - SCROLLBACK);
+  if (s.buf.length > SCROLLBACK) s.buf = trimBuf(s.buf, SCROLLBACK);
   // Parser 2's whole input: the moment output last arrived. `quiet` is derived from this, never
   // from reading the bytes — which is why it is the only one of the five that cannot misread.
   s.lastOutputAt = Date.now();
@@ -1005,7 +1023,7 @@ function seedFromPaneHistory(s, name) {
   if (r.status !== 0 || !r.stdout) return false;
   const text = r.stdout.replace(/\s+$/, '').replace(/\r?\n/g, '\r\n');
   if (!text) return false;
-  s.buf = text + '\r\n';
+  s.buf = trimBuf(text + '\r\n', SCROLLBACK);          // 5000 lines of history can overrun the ring
   s.parsed = null;
   return true;
 }
@@ -1022,8 +1040,14 @@ function attachPty(s, { seed = false } = {}) {
   const startedMs = Date.now();
   let p;
   try {
+    // `encoding: null` is LOAD-BEARING, not a style choice. A control-mode stream is BYTES: tmux
+    // escapes only c < 0x20 and the backslash, so every byte of a UTF-8 sequence rides through raw.
+    // Letting node-pty decode it to a string first and re-narrowing to bytes in the parser destroyed
+    // every non-ASCII character — box drawing became NULs and form feeds, ✓ became 0x13, emoji and
+    // accents became U+FFFD. The parser owns the one and only decode. See lib/tmux-control.js.
     p = pty.spawn(TMUX, ['-L', TMUX_SOCK, '-CC', 'attach-session', '-t', name],
-      { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd, env: sessionEnv() });
+      { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd,
+        env: sessionEnv(), encoding: null });
   } catch (e) {
     // A broken node-pty (e.g. a non-executable spawn-helper) throws synchronously here. This must
     // NOT propagate: on the startup first-shell it would crash the whole server and blank the
@@ -2210,6 +2234,9 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // the legacy-scrollback migration, exported so the suite can assert BOTH halves: the tmux
   // client's preamble is stripped, an inner TUI's own alt-screen use is not.
   stripLegacyClientScreen,
+  // the scrollback ring's front trim, exported pure so the suite can assert that a cut never lands
+  // inside an escape sequence or between the halves of a surrogate pair.
+  trimBuf, SCROLLBACK,
   // the liveness heartbeat's guard, exported pure so the "idle machine stays idle" half can be
   // asserted without a server that has no clients (the suite always has both).
   shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS };