pi-link 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -6,6 +6,14 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
 
 ---
 
+## 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

@@ -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,40 @@ 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/agent/sessions/`, finds the session named "worker-1", and spawns `pi --session <path> --link`.
 
 - **One match** → resumes that session
 - **No match** → creates a new session
 - **Multiple matches** → prints candidates to stderr, exits 1
+- **Conflicting flags** (`--session`, `--continue`, `--resume`, `--fork`, etc.) → rejected with an error
 
-`pi-link resolve <name>` is also available for machine-readable output (prints just the session path).
+### 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
+NAME             MODIFIED  MESSAGES  ID
+opus@pi-link     2m ago    4632      6332faab
+gpt@pi-link      5m ago    1493      20d43841
+
+Resume: pi-link <name>
+```
+
+With `--all`:
+
+```
+$ pi-link list --all
+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>
+```
+
+`--all` adds a `CWD` column with `~` substituted for `$HOME`. Output is plain when piped (`NO_COLOR` honored).
+
+For scripting, `pi-link resolve <name>` prints just the session path (machine-readable, no other output).
 
 ---
 
@@ -432,7 +459,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                                                                 |
 | ----------------- | --------------- | ----------------------------------------------------------------------- |
@@ -500,6 +527,8 @@ 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

@@ -4,6 +4,7 @@
 //
 // 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";
@@ -15,26 +16,86 @@ 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 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 };
 }
 
-async function findSessionsByName(targetName) {
+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 });
@@ -42,43 +103,77 @@ async function findSessionsByName(targetName) {
     return [];
   }
 
-  const matches = [];
-
+  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;
-    }
-
+    try { files = await readdir(dirPath); } catch { continue; }
     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) {
+      tasks.push((async () => {
+        try {
+          const meta = await getSessionMeta(filePath);
           const stats = await stat(filePath);
-          matches.push({ path: filePath, cwd: cwd || "?", modified: stats.mtime });
+          return { ...meta, modified: stats.mtime, path: filePath };
+        } catch {
+          return null;
         }
-      } catch {
-        continue;
-      }
+      })());
     }
   }
 
-  // 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`. 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 ────────────────────────────────────────────────────────────────────
@@ -95,7 +190,42 @@ function printCandidates(name, matches) {
   process.exit(1);
 }
 
-if (command === "resolve") {
+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>");
@@ -122,6 +252,7 @@ if (command === "resolve") {
       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);
@@ -146,6 +277,8 @@ if (command === "resolve") {
   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 +292,8 @@ 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> [pi flags...]");
+  console.error("       pi-link list [--all|-a]");
+  console.error("       pi-link resolve <name>");
   process.exit(0);
 }

package/index.ts

@@ -915,7 +915,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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.