pi-link 0.1.13 → 0.1.14-beta.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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

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`.
 
@@ -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

@@ -245,13 +245,19 @@ function rejectRenamedFlag(token) {
   }
 }
 
-// Reject Pi flags that pi-link manages, plus the removed --link-name extension flag.
+// 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 was removed. Use: pi-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)) {

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.13",
+  "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",