pi-link 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -6,6 +6,31 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
 
 ---
 
+## 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
+
+- **`pi-link list` command.** Lists pi-link sessions in the current cwd. Use `--all` (or `-a`) to list sessions across all directories — adds a CWD column with `~` substituted for `$HOME`. Shows name, last-modified time, message count, and short ID. Sessions are detected by presence of a `link-name` entry. ANSI styling (bold headers, dim secondary columns) in TTY; plain when piped (`NO_COLOR` honored).
+
+---
+
 ## 0.1.10 — 2026-04-26
 
 ### Changed

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:**
@@ -142,7 +142,7 @@ Link is **off by default**. Without `--link` or `pi-link`, the extension is comp
 | `/link-connect`    | Opt-in mid-session (no flag needed) | Yes                              |
 | `/link-disconnect` | Opt-out mid-session                 | Suppressed until `/link-connect` |
 
-**Name precedence:** `PI_LINK_NAME` env (set by `pi-link`) > saved `/link-name` > Pi session name > random `t-xxxx`.
+**Name precedence:** `pi-link <name>` > saved `/link-name` > Pi session name > random `t-xxxx`.
 
 `/link-connect` and `/link-disconnect` save their intent to the session — resume later and the connection state is restored without needing the flag. Explicit user intent takes precedence over `--link`.
 
@@ -157,13 +157,44 @@ 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 launches `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 mirrors Pi's: `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.
 
-`pi-link resolve <name>` is also available for machine-readable output (prints just the session path).
+- **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 --global` (or `-g`) lists them across all directories. Sorted by last activity.
+
+```
+$ pi-link list
+NAME             MODIFIED  MESSAGES  ID
+opus@pi-link     2m ago    4632      6332faab
+gpt@pi-link      5m ago    1493      20d43841
+
+Resume: pi-link <name>
+```
+
+With `--global`:
+
+```
+$ 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
+
+Resume: pi-link <name>
+```
+
+`--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).
 
 ---
 
@@ -399,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`
 
@@ -432,7 +463,7 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 
 ### Protocol
 
-The wire protocol consists of **9 message types**, all serialized as JSON over WebSocket frames. Cwd-related fields are optional for backward compatibility.
+The wire protocol consists of **9 message types**, all serialized as JSON over WebSocket frames. Cwd-related fields are optional.
 
 | Type              | Direction       | Purpose                                                                 |
 | ----------------- | --------------- | ----------------------------------------------------------------------- |

package/bin/pi-link.mjs

@@ -3,88 +3,263 @@
 // 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 resolve <name>      Print just the session path (machine-readable).
+//   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 } from "fs";
+import { createReadStream, existsSync, readFileSync } 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");
+// ── 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 name;
+  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" && typeof entry.cwd === "string") cwd = entry.cwd;
-      if (entry.type === "session_info" && typeof entry.name === "string") {
-        name = entry.name.trim().replace(/\s+/g, " ") || undefined;
+      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
+      // skip malformed lines (incl. partial last line of active sessions)
     }
   }
-  return { name, cwd };
+  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;
 }
 
-async function findSessionsByName(targetName) {
-  let cwdDirs;
+// 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 {
-    cwdDirs = await readdir(SESSIONS_DIR, { withFileTypes: true });
+    const meta = await getSessionMeta(filePath);
+    const stats = await stat(filePath);
+    return { ...meta, modified: stats.mtime, path: filePath };
   } catch {
-    return [];
+    return null;
   }
+}
 
-  const matches = [];
-
-  for (const dir of cwdDirs) {
-    if (!dir.isDirectory()) continue;
-    const dirPath = join(SESSIONS_DIR, dir.name);
+// 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 [];
+  }
 
-    let files;
-    try {
-      files = await readdir(dirPath);
-    } catch {
-      continue;
+  const tasks = [];
+  if (isCustom) {
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+      tasks.push(loadSessionRecord(join(dir, entry.name)));
     }
-
-    for (const file of files) {
-      if (!file.endsWith(".jsonl")) continue;
-      const filePath = join(dirPath, file);
-      try {
-        const { name, cwd } = await getSessionMeta(filePath);
-        if (name === targetName) {
-          const stats = await stat(filePath);
-          matches.push({ path: filePath, cwd: cwd || "?", modified: stats.mtime });
-        }
-      } catch {
-        continue;
+  } 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)));
       }
     }
   }
 
-  // Local-first: current cwd matches before others, then by modified time
-  const localCwd = process.cwd();
-  matches.sort((a, b) => {
-    const aLocal = a.cwd === localCwd ? 1 : 0;
-    const bLocal = b.cwd === localCwd ? 1 : 0;
-    if (aLocal !== bLocal) return bLocal - aLocal;
-    return b.modified.getTime() - a.modified.getTime();
-  });
-  return matches;
+  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) {
@@ -95,40 +270,104 @@ function printCandidates(name, matches) {
   process.exit(1);
 }
 
-if (command === "resolve") {
-  const name = args[0]?.trim().replace(/\s+/g, " ");
-  if (!name) {
-    console.error("Usage: pi-link resolve <name>");
+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 matches = await findSessionsByName(name);
+  const name = positional[0].trim().replace(/\s+/g, " ");
+  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 <name> [flags...] — resolve and launch Pi
-  const name = command.trim().replace(/\s+/g, " ");
+  // 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> [pi flags...]");
+    console.error("Usage: pi-link <name> [--global|-g] [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);
-    }
-    if (key === "--link-name") {
-      console.error("Error: --link-name was removed. Use: pi-link <name>");
-      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 matches = await findSessionsByName(name);
+  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);
   }
@@ -138,14 +377,20 @@ if (command === "resolve") {
     console.error(`Resuming session: ${matches[0].path}`);
     piArgs.push("--session", matches[0].path);
   } else {
-    console.error("No existing session found. Starting new session.");
+    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", ...args);
+  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 },
@@ -159,6 +404,11 @@ if (command === "resolve") {
     process.exit(1);
   });
 } else {
-  console.error("Usage: pi-link <name> [pi flags...]\n       pi-link resolve <name>");
+  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();
@@ -915,7 +927,9 @@ export default function (pi: ExtensionAPI) {
     ctx = _ctx;
     currentCwd = _ctx.cwd;
 
-    // Resolve terminal name: PI_LINK_NAME env > saved link-name > session name > random
+    // Resolve terminal name: PI_LINK_NAME env > saved link-name > session name > random.
+    // PI_LINK_NAME is an internal handoff from the `pi-link` CLI launcher.
+    // Consumed once here and removed from process.env so spawned children don't inherit it.
     const rawLinkName = process.env.PI_LINK_NAME;
     delete process.env.PI_LINK_NAME;
     const flagName = rawLinkName?.trim().replace(/\s+/g, " ") || undefined;
@@ -1393,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.10",
+  "version": "0.1.12",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",

package/skills/pi-link-coordination/SKILL.md

@@ -31,6 +31,8 @@ Pick one mode per terminal per task. Mixing sync and async on the same terminal
 
 Returns connected terminals with names, live status (`idle`, `thinking`, `tool:<name>`), and working directory (cwd). Use before delegating when availability or path context is uncertain. Your own entry is marked `(you)` — use this to discover your link name when replying to broadcast tasks.
 
+Only currently connected terminals are visible. If a target is missing, it is offline; messages to offline terminals are not queued.
+
 ### `link_prompt`
 
 Synchronous RPC. Send a prompt, wait for the response.