pi-link 0.1.12 → 0.1.14-beta.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
 
 ---
 
+## 0.1.14-beta.0 — 2026-05-04
+
+### Added
+
+- **`--link-name <name>` flag for link-only startup naming.** Run `pi --link-name worker` to join the link as `worker` while leaving Pi's normal session selection/resume behavior untouched. This restores link-name startup naming in a cleaner form than the previous session-coupled implementation: it sets only the pi-link identity, with hub collision handling unchanged. Use `pi-link <name>` when you want the combined session-by-name + link-name workflow. Empty or whitespace-only `--link-name` values are rejected with a clear error. The `pi-link` wrapper itself does not accept `--link-name` — its rejection message now points to either `pi-link <name>` (combined) or `pi --link-name <name>` (direct, link-only).
+
+### Changed
+
+- **`link-name` session entries no longer accumulate on no-op restarts.** Both `pi-link <name>` and `pi --link-name <name>` skip the append when the saved name already matches. Sessions opened and exited without any persisted activity will no longer bump `pi-link list` recency from the same-name startup alone; recency still updates on messages, tool calls, edits, and real link-name changes.
+
+---
+
+## 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

package/README.md

@@ -133,16 +133,19 @@ Every other terminal sees:
 
 ## Configuration
 
-Link is **off by default**. Without `--link` or `pi-link`, the extension is completely silent — no status bar, no connections, no warnings.
+Link is **off by default**. Without `--link`, `--link-name`, or `pi-link`, the extension is completely silent — no status bar, no connections, no warnings.
 
-| Method             | When                                | Auto-reconnect?                  |
-| ------------------ | ----------------------------------- | -------------------------------- |
-| `pi-link <name>`   | Resume/create named session         | Yes                              |
-| `pi --link`        | Connect on startup (random name)    | Yes                              |
-| `/link-connect`    | Opt-in mid-session (no flag needed) | Yes                              |
-| `/link-disconnect` | Opt-out mid-session                 | Suppressed until `/link-connect` |
+| Method                  | When                                                             | Auto-reconnect?                  |
+| ----------------------- | ---------------------------------------------------------------- | -------------------------------- |
+| `pi-link <name>`        | Resume/create named session                                      | Yes                              |
+| `pi --link-name <name>` | Connect with a specific link name; Pi session behavior unchanged | Yes                              |
+| `pi --link`             | Connect on startup (random name)                                 | Yes                              |
+| `/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>` > saved `/link-name` > Pi session name > random `t-xxxx`.
+`pi --link-name <name>` sets only the pi-link terminal name; Pi's session selection/resume runs as normal. Use this when you want a stable link identity without coupling it to a same-named session. Use `pi-link <name>` when you want the combined session-by-name + link-name workflow. The `pi-link` wrapper itself does not accept `--link-name`.
+
+**Name precedence:** `pi --link-name` > `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,7 +160,7 @@ 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'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/`.
+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/`.
 
 Lookup is **scoped to the current cwd by default**; pass `--global` (`-g`) to consider sessions in any cwd.
 
@@ -168,7 +171,7 @@ Lookup is **scoped to the current cwd by default**; pass `--global` (`-g`) to co
 
 ### 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` shows pi-link sessions in the current cwd; `pi-link list --global` (or `-g`) lists them across all directories. Sorted by last activity — starting a session with the same name it already has does not bump recency; only real activity (messages, tool calls, edits, name changes) does.
 
 ```
 $ pi-link list

package/bin/pi-link.mjs

@@ -1,414 +1,424 @@
-#!/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, " ");
-  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);
-}
+#!/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 --link-name (which exists at the
+// `pi` level for link-only naming, but the wrapper's combined-mode contract
+// conflicts with it).
+// 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 is not accepted by the pi-link wrapper.\n" +
+      "  Use 'pi-link <name>' for combined link+session,\n" +
+      "  or run 'pi --link-name <name>' directly to set link name without session resolution.",
+    );
+    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

@@ -2,7 +2,7 @@
  * Pi Link — WebSocket-based inter-terminal communication
  *
  * Connects multiple Pi terminals over a local WebSocket link.
- * Opt-in via --link flag, pi-link CLI, or /link-connect command.
+ * Opt-in via --link flag, --link-name flag, pi-link CLI, or /link-connect command.
  * First terminal to connect becomes the hub; others join as clients.
  * Hub loss triggers automatic promotion of a surviving client.
  *
@@ -115,6 +115,12 @@ export default function (pi: ExtensionAPI) {
     default: false,
   });
 
+  pi.registerFlag("link-name", {
+    description:
+      "Set the pi-link terminal name on startup (link identity only; does not affect session)",
+    type: "string",
+  });
+
   // ── State ────────────────────────────────────────────────────────────────
 
   let role: "hub" | "client" | "disconnected" = "disconnected";
@@ -927,18 +933,56 @@ export default function (pi: ExtensionAPI) {
     ctx = _ctx;
     currentCwd = _ctx.cwd;
 
-    // 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;
+    // Resolve terminal name. Precedence:
+    //   --link-name flag  >  PI_LINK_NAME env  >  saved link-name  >  session name  >  random
+    //
+    // --link-name is the public CLI surface (link identity only, never touches session name).
+    // PI_LINK_NAME is the internal handoff from the `pi-link` wrapper, which DOES
+    // seed session name when absent (the wrapper's combined-mode contract).
+    // PI_LINK_NAME is consumed once and removed from process.env so spawned children don't inherit it.
+    const cliRaw = pi.getFlag("link-name");
+    let cliFlagName: string | undefined;
+    if (typeof cliRaw === "string") {
+      cliFlagName = cliRaw.trim().replace(/\s+/g, " ");
+      if (!cliFlagName) {
+        console.error("Error: --link-name requires a non-empty value.");
+        process.exit(1);
+      }
+    }
+
+    const envRaw = process.env.PI_LINK_NAME;
     delete process.env.PI_LINK_NAME;
-    const flagName = rawLinkName?.trim().replace(/\s+/g, " ") || undefined;
+    const envFlagName = envRaw?.trim().replace(/\s+/g, " ") || undefined;
+
+    const flagName = cliFlagName ?? envFlagName;
+    const fromEnv = !cliFlagName && !!envFlagName;
 
     if (flagName) {
       preferredName = flagName;
       terminalName = flagName;
-      pi.appendEntry("link-name", { name: flagName });
-      if (!pi.getSessionName()) pi.setSessionName(flagName);
+
+      // Skip append if the saved name already matches; persistence is needed
+      // only for first-time set or actual change. Reduces session-file growth
+      // on repeated startups (common in automation).
+      let latestSaved: string | undefined;
+      const entries = _ctx.sessionManager.getEntries();
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i] as {
+          type: string;
+          customType?: string;
+          data?: { name?: unknown };
+        };
+        if (e.type !== "custom" || e.customType !== "link-name") continue;
+        if (typeof e.data?.name === "string") latestSaved = e.data.name;
+        break;
+      }
+      if (latestSaved?.trim().replace(/\s+/g, " ") !== flagName) {
+        pi.appendEntry("link-name", { name: flagName });
+      }
+
+      // Critical: only the env path (wrapper combined mode) seeds session name.
+      // Public --link-name is link-only.
+      if (fromEnv && !pi.getSessionName()) pi.setSessionName(flagName);
     } else {
       const saved = _ctx.sessionManager
         .getEntries()

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "pi-link",
-  "version": "0.1.12",
+  "version": "0.1.14-beta.0",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",
   "bin": {
-    "pi-link": "./bin/pi-link.mjs"
+    "pi-link": "bin/pi-link.mjs"
   },
   "repository": {
     "type": "git",