pi-link 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -6,6 +6,32 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
 
 ---
 
+## 0.1.13 — 2026-05-03
+
+### Fixed
+
+- **`pi-link resolve <name>` now rejects whitespace-only names.** Previously a name that normalized to empty (e.g. `pi-link resolve "   "`) fell through to session lookup and silently reported no match. The empty-name check that already covered `pi-link <name>` now also runs in `resolve`, printing usage and exiting non-zero.
+- **README wording: session-dir lookup phrasing tightened** to say "matches Pi's lookup order" instead of "mirrors Pi's".
+
+---
+
+## 0.1.12 — 2026-05-03
+
+### Changed
+
+- **TypeBox import migrated from `@sinclair/typebox` to `typebox`.** Pi 0.69.0 renamed the package; both names still resolve to the same module via Pi's loader alias, so behavior is unchanged. Aligns with Pi's preferred naming and futureproofs against alias removal. README's "Provided by Pi" table updated to match.
+
+### Fixed
+
+- **`pi-link list/resolve/<name>` now respect Pi's session-dir configuration.** The CLI hardcoded `~/.pi/agent/sessions` and ignored Pi's actual lookup chain, so users with a custom session location saw "no sessions" from `list`/`resolve` and — worse — `pi-link <name>` silently started a new session instead of resuming the existing one, fragmenting history into orphans across the real session dir. Resolution now matches Pi's lookup order (minus `--session-dir`, which the CLI rejects): `PI_CODING_AGENT_SESSION_DIR` → `<cwd>/.pi/settings.json` `sessionDir` → `<agentDir>/settings.json` `sessionDir` → default `<agentDir>/sessions/<encoded-cwd>`. `<agentDir>` follows `PI_CODING_AGENT_DIR`. Tilde expansion (`~`, `~/...`) matches Pi's `expandTildePath`. Custom layouts are scanned flat; default keeps the encoded-cwd subdirs. Malformed `settings.json` warns to stderr and falls through. Empty env vars and empty/non-string `sessionDir` values are treated as absent.
+- **`pi-link <name>` now rejects Pi-managed flags even when passed as the first token.** Previously `pi-link --link-name foo` or `pi-link --session path` silently treated the flag as a session name. The validation that already covered later flags now also runs on the first token, with the same error messages.
+- **`pi-link <name>` and `pi-link resolve <name>` now scope name lookup to the current cwd by default; `--global` / `-g` widens to any cwd.** Previously both commands scanned every session everywhere, so `pi-link work` from `~/projects/A` would silently resume `~/projects/B`'s `work` session if no local match existed — mixing one cwd's files into another cwd's session history. By default only current-cwd matches are considered; `--global` restores cross-cwd lookup, with duplicate exact names still failing with candidates. When `pi-link <name>` finds no local match but matches exist elsewhere, it warns and points at `--global` instead of silently jumping. `--global` may be passed before or after the name. `pi-link resolve` now also rejects extra positional arguments and unknown flags. **Breaking change**: `pi-link list --all` is renamed to `pi-link list --global` (`-a` → `-g`) for consistency across the three commands. As a transition aid, `--all` / `-a` are explicitly rejected with a pointer to the new flag name (mirroring the `--link-name was removed` treatment) so users with muscle memory get a clear hint instead of a generic "Unknown argument".
+- **Hub now uses its authoritative socket→name mapping when forwarding chat/prompt messages.** Previously the hub forwarded `chat`, `prompt_request`, and `prompt_response` with whatever `from` the client claimed, while normalizing `status_update` against its socket→name mapping. The asymmetry meant a client with a stale or optimistic local `terminalName` could leak the wrong sender to other terminals — and under a rename-to-taken-name race, prompt responses could route back to the wrong terminal entirely. Hub now spread-normalizes `from` for all routed client messages, matching the existing `status_update` pattern.
+- **`/link-name` no longer updates local `terminalName` before the hub confirms the rename.** Previously the client branch optimistically set `terminalName = newName` before reconnect, so during the close→reconnect→welcome window `/link` and `link_list` would report the requested name even if the hub later deduped it. Local identity now stays at the pre-rename value until `welcome` arrives. Notification wording updated from "Reconnecting as" to "Reconnecting, requesting" to reflect that the hub may assign a different name.
+- **Hub promotion now preserves a pending client rename request.** Same-release follow-up to the previous bullet: with `terminalName` no longer updated optimistically, a client whose previous hub vanished mid-rename and who then wins hub promotion via `startHub` would otherwise have announced under the old local name. A `pendingClientRename` flag, set in `/link-name` and cleared on `welcome`, lets `startHub` adopt the requested name only when a rename was in flight. Hub-assigned deduped names from prior welcomes are otherwise preserved — no general `preferredName` replay.
+
+---
+
 ## 0.1.11 — 2026-04-27
 
 ### Added

package/README.md

@@ -103,7 +103,7 @@ Here's a concrete example of two terminals collaborating. Open two separate `pi
 
 ```
 > /link-name researcher
-✓ Reconnecting as "researcher" (hub may assign a different name if taken)...
+✓ Reconnecting, requesting "researcher" (hub may assign a different name if taken)...
 ```
 
 **Now ask Terminal 1's LLM to delegate work:**
@@ -157,16 +157,18 @@ pi-link worker-1                # resume or create session "worker-1"
 pi-link worker-1 --model sonnet # with extra Pi flags
 ```
 
-How it works: `pi-link worker-1` scans `~/.pi/agent/sessions/`, finds the session named "worker-1", and spawns `pi --session <path> --link`.
+How it works: `pi-link worker-1` scans Pi's session directory, finds the session named "worker-1", and spawns `pi --session <path> --link`. Session-dir resolution matches Pi's lookup order: `PI_CODING_AGENT_SESSION_DIR` env > `<cwd>/.pi/settings.json` `sessionDir` > `<agentDir>/settings.json` `sessionDir` > default `<agentDir>/sessions/`. `<agentDir>` follows `PI_CODING_AGENT_DIR` and defaults to `~/.pi/agent/`.
 
-- **One match** → resumes that session
-- **No match** → creates a new session
-- **Multiple matches** → prints candidates to stderr, exits 1
+Lookup is **scoped to the current cwd by default**; pass `--global` (`-g`) to consider sessions in any cwd.
+
+- **One match in scope** → resumes that session
+- **No match in scope** → creates a new session in the current cwd. If matches exist outside the scope, prints a hint pointing at `--global`.
+- **Multiple matches in scope** → prints candidates to stderr, exits 1
 - **Conflicting flags** (`--session`, `--continue`, `--resume`, `--fork`, etc.) → rejected with an error
 
 ### Discovering sessions
 
-`pi-link list` shows pi-link sessions in the current cwd; `pi-link list --all` (or `-a`) lists them across all directories. Sorted by last activity.
+`pi-link list` shows pi-link sessions in the current cwd; `pi-link list --global` (or `-g`) lists them across all directories. Sorted by last activity.
 
 ```
 $ pi-link list
@@ -177,10 +179,10 @@ gpt@pi-link      5m ago    1493      20d43841
 Resume: pi-link <name>
 ```
 
-With `--all`:
+With `--global`:
 
 ```
-$ pi-link list --all
+$ pi-link list --global
 NAME             CWD                   MODIFIED  MESSAGES  ID
 opus@pi-link     ~/my-project          2m ago    4632      6332faab
 gpt@pi-link      ~/other-project       5m ago    1493      20d43841
@@ -188,7 +190,9 @@ gpt@pi-link      ~/other-project       5m ago    1493      20d43841
 Resume: pi-link <name>
 ```
 
-`--all` adds a `CWD` column with `~` substituted for `$HOME`. Output is plain when piped (`NO_COLOR` honored).
+`--global` adds a `CWD` column with `~` substituted for `$HOME`. Output is plain when piped (`NO_COLOR` honored).
+
+`pi-link <name>` and `pi-link resolve <name>` follow the same scoping: local cwd by default, `--global` (or `-g`) widens. When `pi-link <name>` finds no local match but matches exist elsewhere, it warns and points at `--global` instead of silently jumping cwds.
 
 For scripting, `pi-link resolve <name>` prints just the session path (machine-readable, no other output).
 
@@ -426,7 +430,7 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 | ------------------------------- | ------------------------------------------------ |
 | `@mariozechner/pi-coding-agent` | Pi SDK types (ExtensionAPI, ExtensionContext)    |
 | `@mariozechner/pi-tui`          | TUI Text widget for custom message rendering     |
-| `@sinclair/typebox`             | JSON Schema type definitions for tool parameters |
+| `typebox`                       | JSON Schema type definitions for tool parameters |
 
 ### `package.json`
 
@@ -527,8 +531,6 @@ Default names are random 4-character hex IDs: `t-a1b2`, `t-c3d4`, etc.
 
 **Persistence:** `/link-name` saves the preferred name to the session via `pi.appendEntry("link-name", { name })`. On session resume, the saved name is restored and requested from the hub. Only explicit `/link-name` calls persist - hub-assigned variants like `"builder-2"` are not saved. On reconnect, the terminal always requests the preferred name, not the last runtime name.
 
-**Internal handoff (`PI_LINK_NAME`):** the `pi-link` launcher passes the chosen name to Pi via the `PI_LINK_NAME` environment variable. The extension reads it once on `session_start` and immediately removes it from `process.env` so child processes don't inherit it. This is an internal mechanism — don't set `PI_LINK_NAME` manually; use `pi-link <name>` to start a session or `/link-name` to rename mid-session.
-
 **Rename guards:**
 
 - If you're already using the requested name, `/link-name` returns early (`"Already using..."`).

package/bin/pi-link.mjs

@@ -1,299 +1,418 @@
-#!/usr/bin/env node
-
-// pi-link CLI — launch Pi with session resume by name
-//
-// Usage:
-//   pi-link <name> [flags...]   Resume or create a named session, connected to link.
-//   pi-link list [--all|-a]     List pi-link sessions in current cwd (or everywhere).
-//   pi-link resolve <name>      Print just the session path (machine-readable).
-
-import { readdir, stat } from "fs/promises";
-import { createReadStream } from "fs";
-import { createInterface } from "readline";
-import { join } from "path";
-import { homedir } from "os";
-import { spawn } from "child_process";
-
-const SESSIONS_DIR = join(homedir(), ".pi", "agent", "sessions");
-
-// Reads a session JSONL file and returns its display name, cwd, id, link
-// status, and message count.
-//
-// Name precedence: latest valid `link-name` custom entry wins as the
-// authoritative pi-link name. `session_info.name` is only a fallback for
-// sessions that never set a link-name. Historical link-names are not aliases.
-async function getSessionMeta(filePath) {
-  let linkName;
-  let sessionName;
-  let cwd;
-  let id;
-  let hasLinkName = false;
-  let messages = 0;
-  const rl = createInterface({ input: createReadStream(filePath, "utf-8"), crlfDelay: Infinity });
-  for await (const line of rl) {
-    if (!line) continue;
-    try {
-      const entry = JSON.parse(line);
-      if (entry.type === "session") {
-        if (typeof entry.cwd === "string") cwd = entry.cwd;
-        if (typeof entry.id === "string") id = entry.id;
-      } else if (entry.type === "session_info" && typeof entry.name === "string") {
-        sessionName = entry.name.trim().replace(/\s+/g, " ") || undefined;
-      } else if (entry.type === "custom" && entry.customType === "link-name") {
-        hasLinkName = true;
-        if (entry.data && typeof entry.data.name === "string") {
-          const n = entry.data.name.trim().replace(/\s+/g, " ");
-          if (n) linkName = n;
-        }
-      } else if (entry.type === "message" || entry.type === "user" || entry.type === "assistant") {
-        messages++;
-      }
-    } catch {
-      // skip malformed lines (incl. partial last line of active sessions)
-    }
-  }
-  return { name: linkName ?? sessionName, cwd, id, hasLinkName, messages };
-}
-
-function normalizePath(p) {
-  let s = p.replace(/[/\\]+/g, "/").replace(/\/+$/, "");
-  if (process.platform === "win32") s = s.toLowerCase();
-  return s;
-}
-
-// Replace $HOME with ~ in display paths. Comparison is normalized
-// (case-insensitive on Windows) but display preserves original casing.
-function displayPath(p) {
-  if (!p) return p;
-  const home = homedir();
-  const normP = normalizePath(p);
-  const normHome = normalizePath(home);
-  if (normP === normHome) return "~";
-  if (normP.startsWith(normHome + "/")) return "~" + p.slice(home.length).replace(/\\/g, "/");
-  return p;
-}
-
-const useAnsi =
-  !!process.stdout.isTTY &&
-  process.env.NO_COLOR === undefined &&
-  process.env.TERM !== "dumb";
-const bold = (s) => (useAnsi ? `\x1b[1m${s}\x1b[22m` : s);
-const dim = (s) => (useAnsi ? `\x1b[2m${s}\x1b[22m` : s);
-
-function relTime(d) {
-  const sec = Math.max(0, Math.floor((Date.now() - d.getTime()) / 1000));
-  if (sec < 60) return `${sec}s ago`;
-  const min = Math.floor(sec / 60);
-  if (min < 60) return `${min}m ago`;
-  const hr = Math.floor(min / 60);
-  if (hr < 24) return `${hr}h ago`;
-  const day = Math.floor(hr / 24);
-  if (day < 30) return `${day}d ago`;
-  return d.toISOString().slice(0, 10);
-}
-
-// Walks SESSIONS_DIR in parallel, returning meta + mtime + path for every
-// readable session. Callers filter and sort. Errors on individual files/dirs
-// are silently skipped — active or partially-written sessions are tolerated.
-async function scanSessions() {
-  let cwdDirs;
-  try {
-    cwdDirs = await readdir(SESSIONS_DIR, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-
-  const tasks = [];
-  for (const dir of cwdDirs) {
-    if (!dir.isDirectory()) continue;
-    const dirPath = join(SESSIONS_DIR, dir.name);
-    let files;
-    try { files = await readdir(dirPath); } catch { continue; }
-    for (const file of files) {
-      if (!file.endsWith(".jsonl")) continue;
-      const filePath = join(dirPath, file);
-      tasks.push((async () => {
-        try {
-          const meta = await getSessionMeta(filePath);
-          const stats = await stat(filePath);
-          return { ...meta, modified: stats.mtime, path: filePath };
-        } catch {
-          return null;
-        }
-      })());
-    }
-  }
-
-  return (await Promise.all(tasks)).filter((s) => s !== null);
-}
-
-// Find sessions whose current display name matches `targetName`. Local cwd
-// matches sort first, then by recency. Falls back to `session_info.name` for
-// sessions without a link-name (so `pi-link <name>` can attach link to a
-// previously-unlinked named session).
-async function findSessionsByName(targetName) {
-  const localCwd = normalizePath(process.cwd());
-  return (await scanSessions())
-    .filter((s) => s.name === targetName)
-    .map((s) => ({ path: s.path, cwd: s.cwd || "?", modified: s.modified }))
-    .sort((a, b) => {
-      const aLocal = normalizePath(a.cwd) === localCwd ? 1 : 0;
-      const bLocal = normalizePath(b.cwd) === localCwd ? 1 : 0;
-      if (aLocal !== bLocal) return bLocal - aLocal;
-      return b.modified.getTime() - a.modified.getTime();
-    });
-}
-
-// List pi-link sessions (those with at least one link-name entry). Default
-// scope is current cwd; `all` widens to every directory.
-async function listSessions({ all }) {
-  const localCwd = normalizePath(process.cwd());
-  return (await scanSessions())
-    .filter((s) => s.hasLinkName)
-    .filter((s) => all || (s.cwd && normalizePath(s.cwd) === localCwd))
-    .map((s) => ({
-      name: s.name || "(unnamed)",
-      cwd: s.cwd || "?",
-      id: s.id ? s.id.slice(0, 8) : "?",
-      messages: s.messages,
-      modified: s.modified,
-      path: s.path,
-    }))
-    .sort((a, b) => b.modified.getTime() - a.modified.getTime());
-}
-
-// Renders a plain-text table. Widths are computed from unstyled cells; ANSI
-// styles are applied after padding so column alignment is preserved when piped
-// or styled. Mark a column with `dim: true` to render its cells dim.
-function renderTable(rows, columns) {
-  const widths = columns.map((c) => Math.max(c.header.length, ...rows.map((r) => String(c.get(r)).length)));
-  const padCell = (text, i) => (i === columns.length - 1 ? text : text.padEnd(widths[i]));
-  const styleBody = (text, i) => (columns[i].dim ? dim(text) : text);
-  const headerLine = columns.map((c, i) => bold(padCell(c.header, i))).join("  ");
-  const bodyLines = rows.map((r) =>
-    columns.map((c, i) => styleBody(padCell(String(c.get(r)), i), i)).join("  "),
-  );
-  return [headerLine, ...bodyLines].join("\n");
-}
-
-// ── CLI ────────────────────────────────────────────────────────────────────
-
-const [command, ...args] = process.argv.slice(2);
-
-function printCandidates(name, matches) {
-  console.error(`Multiple sessions named "${name}":\n`);
-  for (const m of matches) {
-    console.error(`  ${m.modified.toISOString().slice(0, 19)}  cwd: ${m.cwd}`);
-    console.error(`  ${m.path}\n`);
-  }
-  console.error(`Use: pi --session <path> --link`);
-  process.exit(1);
-}
-
-if (command === "list") {
-  let all = false;
-  for (const a of args) {
-    if (a === "--all" || a === "-a") all = true;
-    else {
-      console.error(`Unknown argument: ${a}`);
-      console.error("Usage: pi-link list [--all|-a]");
-      process.exit(1);
-    }
-  }
-  const sessions = await listSessions({ all });
-  if (sessions.length === 0) {
-    console.log(all ? "No pi-link sessions found." : "No pi-link sessions found in this cwd.");
-    console.log("Start one: pi-link <name>");
-    process.exit(0);
-  }
-  const columns = all
-    ? [
-        { header: "NAME", get: (s) => s.name },
-        { header: "CWD", get: (s) => displayPath(s.cwd) },
-        { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
-        { header: "MESSAGES", get: (s) => s.messages, dim: true },
-        { header: "ID", get: (s) => s.id, dim: true },
-      ]
-    : [
-        { header: "NAME", get: (s) => s.name },
-        { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
-        { header: "MESSAGES", get: (s) => s.messages, dim: true },
-        { header: "ID", get: (s) => s.id, dim: true },
-      ];
-  console.log(renderTable(sessions, columns));
-  if (process.stdout.isTTY) {
-    console.log("");
-    console.log(dim("Resume: pi-link <name>"));
-  }
-} else if (command === "resolve") {
-  const name = args[0]?.trim().replace(/\s+/g, " ");
-  if (!name) {
-    console.error("Usage: pi-link resolve <name>");
-    process.exit(1);
-  }
-  const matches = await findSessionsByName(name);
-  if (matches.length === 1) {
-    process.stdout.write(matches[0].path);
-  } else if (matches.length > 1) {
-    printCandidates(name, matches);
-  }
-} else if (command && command !== "--help" && command !== "-h") {
-  // pi-link <name> [flags...] — resolve and launch Pi
-  const name = command.trim().replace(/\s+/g, " ");
-  if (!name) {
-    console.error("Usage: pi-link <name> [pi flags...]");
-    process.exit(1);
-  }
-
-  // Reject conflicting flags
-  for (const flag of args) {
-    const key = flag.split("=")[0];
-    if (["--session", "--continue", "-c", "--resume", "-r", "--fork", "--no-session", "--session-dir"].includes(key)) {
-      console.error(`Error: ${key} is managed by pi-link. Remove it.`);
-      process.exit(1);
-    }
-    // Catch the removed extension flag before forwarding args to Pi.
-    if (key === "--link-name") {
-      console.error("Error: --link-name was removed. Use: pi-link <name>");
-      process.exit(1);
-    }
-  }
-
-  const matches = await findSessionsByName(name);
-  if (matches.length > 1) {
-    printCandidates(name, matches);
-  }
-
-  const piArgs = [];
-  if (matches.length === 1) {
-    console.error(`Resuming session: ${matches[0].path}`);
-    piArgs.push("--session", matches[0].path);
-  } else {
-    console.error("No existing session found. Starting new session.");
-  }
-  piArgs.push("--link", ...args);
-
-  const isWin = process.platform === "win32";
-  const cmd = isWin ? "cmd.exe" : "pi";
-  const cmdArgs = isWin ? ["/d", "/c", "pi", ...piArgs] : piArgs;
-
-  // PI_LINK_NAME is the internal handoff to the pi-link extension on the Pi side.
-  // The extension consumes and deletes it on startup; never expose this as a public API.
-  const child = spawn(cmd, cmdArgs, {
-    stdio: "inherit",
-    env: { ...process.env, PI_LINK_NAME: name },
-  });
-  child.once("exit", (code, signal) => {
-    if (code !== null) process.exit(code);
-    process.exit(signal === "SIGINT" ? 130 : 1);
-  });
-  child.once("error", (err) => {
-    console.error(`Failed to start pi: ${err.message}`);
-    process.exit(1);
-  });
-} else {
-  console.error("Usage: pi-link <name> [pi flags...]");
-  console.error("       pi-link list [--all|-a]");
-  console.error("       pi-link resolve <name>");
-  process.exit(0);
-}
+#!/usr/bin/env node
+
+// pi-link CLI — launch Pi with session resume by name
+//
+// Usage:
+//   pi-link <name> [--global|-g] [flags...]
+//                                Resume or create a named session, connected to link.
+//   pi-link list [--global|-g]   List pi-link sessions in current cwd (or everywhere).
+//   pi-link resolve <name> [--global|-g]
+//                                Print just the session path (machine-readable).
+
+import { readdir, stat } from "fs/promises";
+import { createReadStream, existsSync, readFileSync } from "fs";
+import { createInterface } from "readline";
+import { join } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+
+// ── Pi config resolution ───────────────────────────────────────────────────
+// Match Pi's session-dir lookup order so list/resolve/<name> see what Pi sees.
+// Custom sessionDir → flat layout; default → <agentDir>/sessions/<encoded-cwd>.
+
+// Match Pi's expandTildePath: only `~` and `~/...`.
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function readSessionDirFromSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch (err) {
+    console.error(`pi-link: ignored ${settingsPath}: ${err.message}`);
+    return undefined;
+  }
+  const value = parsed?.sessionDir;
+  if (typeof value !== "string" || value.trim() === "") return undefined;
+  return value;
+}
+
+// PI_CODING_AGENT_DIR also relocates global settings.json to <agentDir>/settings.json.
+function resolveAgentDir() {
+  const env = process.env.PI_CODING_AGENT_DIR;
+  if (env) return expandTilde(env);
+  return join(homedir(), ".pi", "agent");
+}
+
+// Returns { dir, isCustom }. isCustom drives layout in scanSessions:
+// true → flat <dir>/*.jsonl, false → <dir>/<encoded-cwd>/*.jsonl.
+function resolveSessionDir(cwd, agentDir) {
+  const env = process.env.PI_CODING_AGENT_SESSION_DIR;
+  if (env) return { dir: expandTilde(env), isCustom: true };
+
+  const projectDir = readSessionDirFromSettings(join(cwd, ".pi", "settings.json"));
+  if (projectDir) return { dir: expandTilde(projectDir), isCustom: true };
+
+  const globalDir = readSessionDirFromSettings(join(agentDir, "settings.json"));
+  if (globalDir) return { dir: expandTilde(globalDir), isCustom: true };
+
+  return { dir: join(agentDir, "sessions"), isCustom: false };
+}
+
+// Reads a session JSONL file and returns its display name, cwd, id, link
+// status, and message count.
+//
+// Name precedence: latest valid `link-name` custom entry wins as the
+// authoritative pi-link name. `session_info.name` is only a fallback for
+// sessions that never set a link-name. Historical link-names are not aliases.
+async function getSessionMeta(filePath) {
+  let linkName;
+  let sessionName;
+  let cwd;
+  let id;
+  let hasLinkName = false;
+  let messages = 0;
+  const rl = createInterface({ input: createReadStream(filePath, "utf-8"), crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (entry.type === "session") {
+        if (typeof entry.cwd === "string") cwd = entry.cwd;
+        if (typeof entry.id === "string") id = entry.id;
+      } else if (entry.type === "session_info" && typeof entry.name === "string") {
+        sessionName = entry.name.trim().replace(/\s+/g, " ") || undefined;
+      } else if (entry.type === "custom" && entry.customType === "link-name") {
+        hasLinkName = true;
+        if (entry.data && typeof entry.data.name === "string") {
+          const n = entry.data.name.trim().replace(/\s+/g, " ");
+          if (n) linkName = n;
+        }
+      } else if (entry.type === "message" || entry.type === "user" || entry.type === "assistant") {
+        messages++;
+      }
+    } catch {
+      // skip malformed lines (incl. partial last line of active sessions)
+    }
+  }
+  return { name: linkName ?? sessionName, cwd, id, hasLinkName, messages };
+}
+
+function normalizePath(p) {
+  let s = p.replace(/[/\\]+/g, "/").replace(/\/+$/, "");
+  if (process.platform === "win32") s = s.toLowerCase();
+  return s;
+}
+
+// Replace $HOME with ~ in display paths. Comparison is normalized
+// (case-insensitive on Windows) but display preserves original casing.
+function displayPath(p) {
+  if (!p) return p;
+  const home = homedir();
+  const normP = normalizePath(p);
+  const normHome = normalizePath(home);
+  if (normP === normHome) return "~";
+  if (normP.startsWith(normHome + "/")) return "~" + p.slice(home.length).replace(/\\/g, "/");
+  return p;
+}
+
+const useAnsi =
+  !!process.stdout.isTTY &&
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb";
+const bold = (s) => (useAnsi ? `\x1b[1m${s}\x1b[22m` : s);
+const dim = (s) => (useAnsi ? `\x1b[2m${s}\x1b[22m` : s);
+
+function relTime(d) {
+  const sec = Math.max(0, Math.floor((Date.now() - d.getTime()) / 1000));
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  if (day < 30) return `${day}d ago`;
+  return d.toISOString().slice(0, 10);
+}
+
+async function loadSessionRecord(filePath) {
+  try {
+    const meta = await getSessionMeta(filePath);
+    const stats = await stat(filePath);
+    return { ...meta, modified: stats.mtime, path: filePath };
+  } catch {
+    return null;
+  }
+}
+
+// Returns meta + mtime + path for every readable session in `dir`. Custom
+// layout is flat (<dir>/*.jsonl); default layout has one subdir level per
+// encoded cwd (<dir>/<sub>/*.jsonl). Errors on individual files/dirs are
+// silently skipped — active or partially-written sessions are tolerated.
+async function scanSessions(dir, isCustom) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const tasks = [];
+  if (isCustom) {
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+      tasks.push(loadSessionRecord(join(dir, entry.name)));
+    }
+  } else {
+    for (const sub of entries) {
+      if (!sub.isDirectory()) continue;
+      const subPath = join(dir, sub.name);
+      let files;
+      try { files = await readdir(subPath); } catch { continue; }
+      for (const file of files) {
+        if (!file.endsWith(".jsonl")) continue;
+        tasks.push(loadSessionRecord(join(subPath, file)));
+      }
+    }
+  }
+
+  return (await Promise.all(tasks)).filter((s) => s !== null);
+}
+
+// Find sessions whose current display name matches `targetName`. Returns both
+// local-cwd matches and all matches (cross-cwd) so the caller can default to
+// local while still surfacing a hint when non-local matches exist. Falls back
+// to `session_info.name` for sessions without a link-name (so `pi-link <name>`
+// can attach link to a previously-unlinked named session).
+async function findSessionsByName(targetName, dir, isCustom) {
+  const localCwd = normalizePath(process.cwd());
+  const all = (await scanSessions(dir, isCustom))
+    .filter((s) => s.name === targetName)
+    .map((s) => ({ path: s.path, cwd: s.cwd || "?", modified: s.modified }))
+    .sort((a, b) => b.modified.getTime() - a.modified.getTime());
+  const local = all.filter((s) => normalizePath(s.cwd) === localCwd);
+  return { local, all };
+}
+
+// List pi-link sessions (those with at least one link-name entry). Default
+// scope is current cwd; `all` widens to every directory.
+async function listSessions({ all, dir, isCustom }) {
+  const localCwd = normalizePath(process.cwd());
+  return (await scanSessions(dir, isCustom))
+    .filter((s) => s.hasLinkName)
+    .filter((s) => all || (s.cwd && normalizePath(s.cwd) === localCwd))
+    .map((s) => ({
+      name: s.name || "(unnamed)",
+      cwd: s.cwd || "?",
+      id: s.id ? s.id.slice(0, 8) : "?",
+      messages: s.messages,
+      modified: s.modified,
+      path: s.path,
+    }))
+    .sort((a, b) => b.modified.getTime() - a.modified.getTime());
+}
+
+// Renders a plain-text table. Widths are computed from unstyled cells; ANSI
+// styles are applied after padding so column alignment is preserved when piped
+// or styled. Mark a column with `dim: true` to render its cells dim.
+function renderTable(rows, columns) {
+  const widths = columns.map((c) => Math.max(c.header.length, ...rows.map((r) => String(c.get(r)).length)));
+  const padCell = (text, i) => (i === columns.length - 1 ? text : text.padEnd(widths[i]));
+  const styleBody = (text, i) => (columns[i].dim ? dim(text) : text);
+  const headerLine = columns.map((c, i) => bold(padCell(c.header, i))).join("  ");
+  const bodyLines = rows.map((r) =>
+    columns.map((c, i) => styleBody(padCell(String(c.get(r)), i), i)).join("  "),
+  );
+  return [headerLine, ...bodyLines].join("\n");
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+const [command, ...args] = process.argv.slice(2);
+
+// Reject pi-link flags renamed in 0.1.12 with a clear pointer to the new name.
+// Same intent as `rejectManagedFlag` (specific message > generic "Unknown argument")
+// but for our own renames, not Pi-managed flags.
+function rejectRenamedFlag(token) {
+  if (token === "--all" || token === "-a") {
+    const replacement = token === "-a" ? "-g" : "--global";
+    console.error(`Error: ${token} was renamed to ${replacement}.`);
+    process.exit(1);
+  }
+}
+
+// Reject Pi flags that pi-link manages, plus the removed --link-name extension flag.
+// Runs on both the first token (so `pi-link --session foo` errors clearly) and on each
+// flag in args (so `pi-link foo --session bar` does too).
+function rejectManagedFlag(token) {
+  const key = token.split("=")[0];
+  if (key === "--link-name") {
+    console.error("Error: --link-name was removed. Use: pi-link <name>");
+    process.exit(1);
+  }
+  if (["--session", "--continue", "-c", "--resume", "-r", "--fork", "--no-session", "--session-dir"].includes(key)) {
+    console.error(`Error: ${key} is managed by pi-link. Remove it.`);
+    process.exit(1);
+  }
+}
+
+function printCandidates(name, matches) {
+  console.error(`Multiple sessions named "${name}":\n`);
+  for (const m of matches) {
+    console.error(`  ${m.modified.toISOString().slice(0, 19)}  cwd: ${m.cwd}`);
+    console.error(`  ${m.path}\n`);
+  }
+  console.error(`Use: pi --session <path> --link`);
+  process.exit(1);
+}
+
+if (command === "list") {
+  let global = false;
+  for (const a of args) {
+    rejectRenamedFlag(a);
+    if (a === "--global" || a === "-g") global = true;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      console.error("Usage: pi-link list [--global|-g]");
+      process.exit(1);
+    }
+  }
+  const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());
+  const sessions = await listSessions({ all: global, dir, isCustom });
+  if (sessions.length === 0) {
+    console.log(global ? "No pi-link sessions found." : "No pi-link sessions found in this cwd.");
+    console.log("Start one: pi-link <name>");
+    process.exit(0);
+  }
+  const columns = global
+    ? [
+        { header: "NAME", get: (s) => s.name },
+        { header: "CWD", get: (s) => displayPath(s.cwd) },
+        { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
+        { header: "MESSAGES", get: (s) => s.messages, dim: true },
+        { header: "ID", get: (s) => s.id, dim: true },
+      ]
+    : [
+        { header: "NAME", get: (s) => s.name },
+        { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
+        { header: "MESSAGES", get: (s) => s.messages, dim: true },
+        { header: "ID", get: (s) => s.id, dim: true },
+      ];
+  console.log(renderTable(sessions, columns));
+  if (process.stdout.isTTY) {
+    console.log("");
+    console.log(dim("Resume: pi-link <name>"));
+  }
+} else if (command === "resolve") {
+  let global = false;
+  const positional = [];
+  for (const a of args) {
+    rejectRenamedFlag(a);
+    if (a === "--global" || a === "-g") global = true;
+    else if (a.startsWith("-")) {
+      console.error(`Unknown argument: ${a}`);
+      console.error("Usage: pi-link resolve <name> [--global|-g]");
+      process.exit(1);
+    } else positional.push(a);
+  }
+  if (positional.length !== 1) {
+    console.error("Usage: pi-link resolve <name> [--global|-g]");
+    process.exit(1);
+  }
+  const name = positional[0].trim().replace(/\s+/g, " ");
+  if (!name) {
+    console.error("Usage: pi-link resolve <name> [--global|-g]");
+    process.exit(1);
+  }
+  const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());
+  const { local, all } = await findSessionsByName(name, dir, isCustom);
+  const matches = global ? all : local;
+  if (matches.length === 1) {
+    process.stdout.write(matches[0].path);
+  } else if (matches.length > 1) {
+    printCandidates(name, matches);
+  }
+} else if (command && command !== "--help" && command !== "-h") {
+  // pi-link [--global|-g] <name> [pi flags...] — resolve and launch Pi.
+  // Walk every token in one pass: pull out --global wherever it appears, treat
+  // the first non-flag token as the name, reject managed flags, forward the rest.
+  let global = false;
+  let name = null;
+  const piPassthrough = [];
+  for (const token of [command, ...args]) {
+    rejectRenamedFlag(token);
+    if (token === "--global" || token === "-g") { global = true; continue; }
+    rejectManagedFlag(token);
+    if (name === null) {
+      // Before the name is set, an unknown leading flag is almost certainly a
+      // user mistake (`pi-link --model gpt-4 foo`) — don't silently treat it
+      // as a session name. After the name is set, anything goes (forwarded to Pi).
+      if (token.startsWith("-")) {
+        console.error(`Unknown argument before name: ${token}`);
+        console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
+        process.exit(1);
+      }
+      name = token;
+    } else piPassthrough.push(token);
+  }
+  if (!name) {
+    console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
+    process.exit(1);
+  }
+  name = name.trim().replace(/\s+/g, " ");
+  if (!name) {
+    console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
+    process.exit(1);
+  }
+
+  const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());
+  const { local, all } = await findSessionsByName(name, dir, isCustom);
+  const matches = global ? all : local;
+  if (matches.length > 1) {
+    printCandidates(name, matches);
+  }
+
+  const piArgs = [];
+  if (matches.length === 1) {
+    console.error(`Resuming session: ${matches[0].path}`);
+    piArgs.push("--session", matches[0].path);
+  } else {
+    if (!global && all.length > local.length) {
+      const elsewhere = all.length - local.length;
+      console.error(`No "${name}" in this cwd. (${elsewhere} match${elsewhere === 1 ? "" : "es"} in other cwds — use --global to consider ${elsewhere === 1 ? "it" : "them"}.)`);
+    }
+    console.error("Starting new session.");
+  }
+  piArgs.push("--link", ...piPassthrough);
+
+  const isWin = process.platform === "win32";
+  const cmd = isWin ? "cmd.exe" : "pi";
+  const cmdArgs = isWin ? ["/d", "/c", "pi", ...piArgs] : piArgs;
+
+  // PI_LINK_NAME is the internal handoff to the pi-link extension on the Pi side.
+  // The extension consumes and deletes it on startup; never expose this as a public API.
+  const child = spawn(cmd, cmdArgs, {
+    stdio: "inherit",
+    env: { ...process.env, PI_LINK_NAME: name },
+  });
+  child.once("exit", (code, signal) => {
+    if (code !== null) process.exit(code);
+    process.exit(signal === "SIGINT" ? 130 : 1);
+  });
+  child.once("error", (err) => {
+    console.error(`Failed to start pi: ${err.message}`);
+    process.exit(1);
+  });
+} else {
+  console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
+  console.error("       pi-link list [--global|-g]");
+  console.error("       pi-link resolve <name> [--global|-g]");
+  console.error("");
+  console.error("By default, name lookup is scoped to the current cwd.");
+  console.error("--global / -g widens the search to sessions in any cwd.");
+  process.exit(0);
+}

package/index.ts

@@ -15,7 +15,7 @@ import type {
   ExtensionContext,
 } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 import * as crypto from "node:crypto";
 import * as os from "node:os";
 
@@ -120,6 +120,9 @@ export default function (pi: ExtensionAPI) {
   let role: "hub" | "client" | "disconnected" = "disconnected";
   let terminalName = `t-${crypto.randomUUID().slice(0, 4)}`;
   let preferredName: string | null = null;
+  // True between a client `/link-name` close and the next welcome/promotion.
+  // Lets `startHub` adopt the requested name if it wins promotion before welcome.
+  let pendingClientRename = false;
   let connectedTerminals: string[] = [];
   let ctx: ExtensionContext | undefined;
   let disposed = false;
@@ -481,6 +484,7 @@ export default function (pi: ExtensionAPI) {
       // ── Client receives after registering ──
       case "welcome":
         terminalName = msg.name;
+        pendingClientRename = false;
         connectedTerminals = msg.terminals;
         terminalStatuses.clear();
         terminalCwds.clear();
@@ -676,13 +680,15 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      // Route chat / prompt messages
+      // Route chat / prompt messages.
+      // Normalize `from` to the hub's authoritative socket→name mapping,
+      // mirroring the status_update path above. Don't trust the client.
       if (
         msg.type === "chat" ||
         msg.type === "prompt_request" ||
         msg.type === "prompt_response"
       ) {
-        routeMessage(msg);
+        routeMessage({ ...msg, from: clientName });
       }
     });
 
@@ -725,6 +731,12 @@ export default function (pi: ExtensionAPI) {
           return;
         }
         wss = server;
+        // If a client `/link-name` was in flight when the previous hub vanished,
+        // this terminal is now establishing hub identity, so honor that pending
+        // request. Otherwise keep the last hub-assigned identity — don't replay
+        // a stale `preferredName` that may already have been deduped.
+        if (pendingClientRename && preferredName) terminalName = preferredName;
+        pendingClientRename = false;
         role = "hub";
         connectedTerminals = [terminalName];
         updateStatus();
@@ -1395,13 +1407,13 @@ export default function (pi: ExtensionAPI) {
         savePreference();
         _ctx.ui.notify(`Renamed to "${newName}"`, "info");
       } else if (role === "client") {
-        // Reconnect with new name — hub will enforce uniqueness via register
+        // Don't update terminalName here — welcome will assign authoritatively
+        // after reconnect. Hub may dedupe newName to newName-2 if taken.
         savePreference();
-        terminalName = newName;
+        pendingClientRename = true;
         ws?.close();
-        // Reconnect will happen via the onClose handler → scheduleReconnect
         _ctx.ui.notify(
-          `Reconnecting as "${newName}" (hub may assign a different name if taken)...`,
+          `Reconnecting, requesting "${newName}" (hub may assign a different name if taken)...`,
           "info",
         );
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",