pi-link 0.1.16 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
 
 ---
 
+## 0.2.0 — 2026-07-17
+
+### Added
+
+- **`pi-link --version` prints the installed package version.** It writes the bare semver to stdout and exits successfully, so users can identify the installed build during testing.
+
+### Breaking
+
+- **Removed the deprecated `pi-link list` and `pi-link resolve <name>` command forms.** They now error with migration guidance; use `pi-link --list` and `pi-link --resolve <name>` instead. The canonical flag forms are unchanged.
+
+### Changed
+
+- **The wrapper no longer reserves legacy `--all` / `-a` flags.** Before a session name, they receive the normal unknown-argument error; after a session name, they pass through to Pi unchanged. Use `--global` / `-g` for pi-link's cross-directory session lookup.
+
+### Fixed
+
+- **Malformed saved link names no longer crash startup.** A non-string `link-name` session entry is ignored and naming falls through to the session name or random default; well-formed name precedence is unchanged.
+
+---
+
+## 0.1.17 — 2026-07-01
+
+### Changed
+
+- **`link_send` now rejects self-targets.** Sending to your own link name returns an immediate `self_target` error instead of delivering the message back to yourself, matching the existing `link_prompt` and `link_compact` behavior.
+
+### Fixed
+
+- **Disconnected link tool calls are now marked as errors.** `notConnectedResult()` tags `error: "not_connected"`, so callers and renderers treat a disconnected call as a failure instead of a success-looking result.
+- **Hub ignores duplicate `register` messages.** A second `register` on an already-registered client socket is now dropped instead of re-running the join flow (which could reassign the name and emit a spurious re-join).
+- **`link_prompt` and `link_compact` honor an already-aborted signal.** Both tools now check `signal.aborted` at the top of `execute` and return an `error: "aborted"` result immediately, rather than starting work that was cancelled before it began.
+
+### Internal
+
+- Removed the unused `ExtensionContext` parameter from `shouldConnect()`.
+- Clarified the keepalive comment: it presumes `sendUserMessage()` starts a run, with the sender's 30-minute hard ceiling as the backstop if it ever doesn't.
+
+---
+
 ## 0.1.16 — 2026-06-09
 
 ### Added

package/README.md

@@ -220,8 +220,6 @@ Resume: pi-link <name>
 
 For scripting, `pi-link --resolve <name>` prints just the session path (machine-readable, no other output). Exit codes: `0` on single match, `1` if ambiguous (multiple matches printed to stderr), `2` if not found.
 
-> The legacy subcommand forms `pi-link list` and `pi-link resolve <name>` still work but print a stderr deprecation warning and will be removed in a future release. Switch to the flag forms above.
-
 ---
 
 ## LLM Tools
@@ -255,7 +253,7 @@ Note: `triggerTurn` does **not** cause the response to come back to the caller -
 
 > **Broadcast note:** Sending to `"*"` delivers to **all other terminals** - the sender is excluded.
 
-Pre-validates the target name against the local terminal list before sending, catching typos early. See [Message Routing](#message-routing--error-handling) for delivery semantics.
+Pre-validates the target name against the local terminal list before sending, catching typos early. See [Message Routing](#message-routing--error-handling) for delivery semantics. **Self-target rejection** - sending to yourself (`to` equals your own name) returns an immediate error.
 
 ### `link_prompt`
 

package/bin/pi-link.mjs

@@ -8,9 +8,7 @@
 //   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).
-//
-// Deprecated subcommand forms `pi-link list` / `pi-link resolve <name>` still
-// work for one release with a stderr warning.
+//   pi-link --version            Print the installed pi-link version.
 
 import { readdir, stat } from "fs/promises";
 import { createReadStream, existsSync, readFileSync } from "fs";
@@ -19,6 +17,12 @@ import { join } from "path";
 import { homedir } from "os";
 import { spawn } from "child_process";
 
+// Canonicalize a link/session name: trim + collapse internal whitespace.
+// Must match the extension's normalizeName (index.ts).
+function normalizeName(s) {
+  return s.trim().replace(/\s+/g, " ");
+}
+
 // ── 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>.
@@ -88,11 +92,11 @@ async function getSessionMeta(filePath) {
         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;
+        sessionName = normalizeName(entry.name) || 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, " ");
+          const n = normalizeName(entry.data.name);
           if (n) linkName = n;
         }
       } else if (entry.type === "message" || entry.type === "user" || entry.type === "assistant") {
@@ -237,20 +241,9 @@ function renderTable(rows, columns) {
 
 const rawArgs = 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). Called from Phase 6 (mode entry) and Phase 7 (after
+// conflicts with it). Called from Phase 4 (mode entry) and Phase 5 (after
 // launcher name), so it fires on both `pi-link --session foo` and
 // `pi-link foo --session bar` with the friendly message.
 function rejectManagedFlag(token) {
@@ -288,22 +281,27 @@ function printHelp() {
   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("       pi-link --version");
   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.");
 }
 
-function printDeprecationWarning(form) {
-  const canonical = form === "list" ? "--list" : "--resolve";
-  console.error(
-    `Warning: 'pi-link ${form}' is deprecated. Use 'pi-link ${canonical}' instead. ` +
-    `(Subcommand form will be removed in a future release.)`,
-  );
+function printVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
+    );
+    console.log(pkg.version ?? "unknown");
+  } catch {
+    console.log("unknown");
+  }
 }
 
 function describeMode(mode) {
   switch (mode) {
     case "help": return "--help";
+    case "version": return "--version";
     case "list": return "--list";
     case "resolve": return "--resolve";
     case "launcher": return "session name";
@@ -313,23 +311,19 @@ function describeMode(mode) {
 
 // ── Parser ─────────────────────────────────────────────────────────────────
 //
-// Single sequential pass populates `state`; dispatcher reads it. Phases (per
-// PLAN-cli-flags.md):
-//   1. Renamed-flag rejection (always-on for --all/-a)
-//   2. Global flags (--global, --help, --)
-//   3. Mode-selecting flags (--list, --resolve, --resolve=<name>)
-//   4. Deprecated subcommands (list, resolve <name>) — only at mode-null position
-//   5. Mode-specific extra-token rejection (with deprecated-resolve leniency)
-//   6. Launcher mode entry (mode null + bare positional)
-//   7. Launcher passthrough (mode launcher) with orphan-positional rejection
+// Single sequential pass populates `state`; dispatcher reads it. Phases:
+//   1. Global flags (--global, --help, --version, --)
+//   2. Mode-selecting flags (--list, --resolve, --resolve=<name>)
+//   3. Mode-specific extra-token rejection
+//   4. Launcher mode entry (mode null + bare positional)
+//   5. Launcher passthrough (mode launcher) with orphan-positional rejection
 
 const state = {
-  mode: null, // null | "help" | "list" | "resolve" | "launcher"
+  mode: null, // null | "help" | "version" | "list" | "resolve" | "launcher"
   resolveName: null,
   launcherName: null,
   global: false,
   piPassthrough: [],
-  deprecated: null, // null | "list" | "resolve"
 };
 
 function setMode(mode) {
@@ -344,10 +338,7 @@ let lastWasFlag = false;
 for (let i = 0; i < rawArgs.length; i++) {
   const a = rawArgs[i];
 
-  // Phase 1: renamed-flag rejection.
-  rejectRenamedFlag(a);
-
-  // Phase 2: global flags / scope-affecting tokens.
+  // Phase 1: global flags / scope-affecting tokens.
   if (a === "--global" || a === "-g") {
     state.global = true;
     lastWasFlag = false;
@@ -357,6 +348,10 @@ for (let i = 0; i < rawArgs.length; i++) {
     setMode("help"); // errors if combined with another mode
     continue;
   }
+  if (a === "--version") {
+    setMode("version"); // errors if combined with another mode
+    continue;
+  }
   if (a === "--") {
     // `--` only meaningful in launcher mode (separates pi flags from positionals).
     if (state.mode !== "launcher") {
@@ -369,7 +364,7 @@ for (let i = 0; i < rawArgs.length; i++) {
     break;
   }
 
-  // Phase 3: mode-selecting flags.
+  // Phase 2: mode-selecting flags.
   if (a === "--list") {
     setMode("list");
     continue;
@@ -392,57 +387,36 @@ for (let i = 0; i < rawArgs.length; i++) {
     continue;
   }
 
-  // Phase 4: deprecated subcommands (only at mode-null position).
-  if (state.mode === null && (a === "list" || a === "resolve")) {
-    state.deprecated = a;
-    if (a === "list") {
-      setMode("list");
-    } else {
-      setMode("resolve");
-      const next = rawArgs[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
-        state.resolveName = next;
-        i++;
-      }
-      // else: leave null; Phase 5 leniency or post-parse validation handles it.
-    }
-    continue;
-  }
-
-  // Phase 5: mode-specific extra-token rejection.
+  // Phase 3: mode-specific extra-token rejection.
   if (state.mode === "help") {
     fail(`--help does not accept arguments: ${a}`);
   }
+  if (state.mode === "version") {
+    fail(`--version does not accept arguments: ${a}`);
+  }
   if (state.mode === "list") {
     fail(`--list does not accept argument: ${a}\n  Usage: pi-link --list [--global|-g]`);
   }
   if (state.mode === "resolve") {
-    // Deprecated-form leniency: `pi-link resolve --global foo` was order-independent;
-    // if we entered via deprecated path and haven't bound a name yet, take this.
-    if (
-      state.deprecated === "resolve" &&
-      state.resolveName === null &&
-      !a.startsWith("-")
-    ) {
-      state.resolveName = a;
-      continue;
-    }
     fail(`--resolve accepts exactly one name; got extra: ${a}`);
   }
 
-  // Phase 6: launcher mode entry. state.mode === null here, no name set yet.
-  // (lastWasFlag is still false here — only Phase 7 sets it, and Phase 7 requires launcher mode.)
+  // Phase 4: launcher mode entry. state.mode === null here, no name set yet.
+  // (lastWasFlag is still false here — only Phase 5 sets it, and Phase 5 requires launcher mode.)
   if (state.mode === null) {
     rejectManagedFlag(a);
     if (a.startsWith("-")) {
       fail(`Unknown argument: ${a}\n  Usage: pi-link <name> [--global|-g] [pi flags...]`);
     }
+    if (a === "list" || a === "resolve") {
+      fail(`'pi-link ${a}' was removed. Use 'pi-link --${a}'.`);
+    }
     state.mode = "launcher";
     state.launcherName = a;
     continue;
   }
 
-  // Phase 7: launcher mode, name set. Tokens go to passthrough or get rejected.
+  // Phase 5: launcher mode, name set. Tokens go to passthrough or get rejected.
   rejectManagedFlag(a);
   if (a.startsWith("-")) {
     state.piPassthrough.push(a);
@@ -466,24 +440,20 @@ if (state.mode === "resolve") {
   if (state.resolveName === null) {
     fail(`--resolve requires a name argument.\n  Usage: pi-link --resolve <name> [--global|-g]`);
   }
-  const normalized = state.resolveName.trim().replace(/\s+/g, " ");
+  const normalized = normalizeName(state.resolveName);
   if (!normalized) {
     fail(`--resolve requires a non-empty name argument.\n  Usage: pi-link --resolve <name> [--global|-g]`);
   }
   state.resolveName = normalized;
 }
 if (state.mode === "launcher") {
-  const normalized = state.launcherName.trim().replace(/\s+/g, " ");
+  const normalized = normalizeName(state.launcherName);
   if (!normalized) {
     fail(`session name cannot be empty.\n  Usage: pi-link <name> [--global|-g] [pi flags...]`);
   }
   state.launcherName = normalized;
 }
 
-if (state.deprecated) {
-  printDeprecationWarning(state.deprecated);
-}
-
 // ── Dispatch ───────────────────────────────────────────────────────────────
 
 switch (state.mode) {
@@ -492,6 +462,10 @@ switch (state.mode) {
     printHelp();
     process.exit(0);
     break; // unreachable; present to satisfy no-fallthrough lints
+  case "version":
+    printVersion();
+    process.exit(0);
+    break; // unreachable; present to satisfy no-fallthrough lints
   case "list":
     await runList(state);
     break;
@@ -517,18 +491,18 @@ async function runList(state) {
   }
   const columns = state.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: "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 },
-      ];
+      { 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("");

package/index.ts

@@ -433,7 +433,7 @@ export default function (pi: ExtensionAPI) {
 
   // ── Connection intent ──────────────────────────────────────────────────
 
-  function shouldConnect(_ctx: ExtensionContext): boolean {
+  function shouldConnect(): boolean {
     const data = latestCustomData("link-active") as
       | { active?: boolean }
       | undefined;
@@ -775,7 +775,9 @@ export default function (pi: ExtensionAPI) {
           });
         } else {
           pendingRemotePrompt = { id: msg.id, from: msg.from };
-          // Keepalive: periodic status push so sender knows we're alive
+          // Keepalive: periodic status push so sender knows we're alive.
+          // Keepalive presumes sendUserMessage() starts a run (platform contract);
+          // if it ever doesn't, the sender's 30 min hard ceiling is the backstop.
           if (keepaliveTimer) clearInterval(keepaliveTimer);
           keepaliveTimer = setInterval(
             () => pushStatus(true),
@@ -848,6 +850,7 @@ export default function (pi: ExtensionAPI) {
 
       // First message must be register
       if (msg.type === "register") {
+        if (clientName) return; // already registered — ignore duplicate
         clientName = uniqueName(msg.name);
         hubClients.set(clientWs, clientName);
         if (msg.cwd) hubTerminalCwds.set(clientName, msg.cwd);
@@ -1225,9 +1228,11 @@ export default function (pi: ExtensionAPI) {
       if (fromEnv && !pi.getSessionName()) pi.setSessionName(flagName);
     } else {
       const saved = latestCustomData("link-name") as
-        | { name?: string }
+        | { name?: unknown }
         | undefined;
-      const savedName = normalizeName(saved?.name);
+      const savedName = normalizeName(
+        typeof saved?.name === "string" ? saved.name : undefined,
+      );
       if (savedName) {
         preferredName = savedName;
         terminalName = preferredName;
@@ -1237,7 +1242,7 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    if (flagName || shouldConnect(_ctx)) scheduleStartupConnect();
+    if (flagName || shouldConnect()) scheduleStartupConnect();
   });
 
   pi.on("session_shutdown", async () => {
@@ -1317,7 +1322,7 @@ export default function (pi: ExtensionAPI) {
   }
 
   function notConnectedResult() {
-    return textResult("Not connected to link");
+    return textResult("Not connected to link", { error: "not_connected" });
   }
 
   function truncatePreview(text: string, max = 60) {
@@ -1377,6 +1382,12 @@ export default function (pi: ExtensionAPI) {
 
       // Pre-validate target exists locally (best-effort, catches typos and definitely-absent names)
       if (params.to !== "*") {
+        if (params.to === terminalName) {
+          return textResult("Cannot send to yourself", {
+            to: params.to,
+            error: "self_target",
+          });
+        }
         const miss = targetNotFound(params.to);
         if (miss) return miss;
       }
@@ -1439,6 +1450,13 @@ export default function (pi: ExtensionAPI) {
     }),
 
     async execute(_toolCallId, params, signal) {
+      if (signal?.aborted) {
+        return textResult("Compact request aborted", {
+          to: params.to,
+          error: "aborted",
+        });
+      }
+
       if (role === "disconnected") return notConnectedResult();
 
       if (params.to === terminalName) {
@@ -1496,7 +1514,7 @@ export default function (pi: ExtensionAPI) {
           instructions: params.instructions,
         });
 
-        if (!delivered && pendingCompactResponses.has(requestId)) {
+        if (!delivered) {
           const pending = cleanupPendingCompact(requestId);
           if (pending) {
             pending.resolve(
@@ -1537,6 +1555,13 @@ export default function (pi: ExtensionAPI) {
     }),
 
     async execute(_toolCallId, params, signal) {
+      if (signal?.aborted) {
+        return textResult("Prompt request aborted", {
+          to: params.to,
+          error: "aborted",
+        });
+      }
+
       if (role === "disconnected") return notConnectedResult();
 
       if (params.to === terminalName) {
@@ -1598,7 +1623,7 @@ export default function (pi: ExtensionAPI) {
           prompt: params.prompt,
         });
 
-        if (!delivered && pendingPromptResponses.has(requestId)) {
+        if (!delivered) {
           const pending = cleanupPending(requestId);
           if (pending) {
             pending.resolve(

package/package.json

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

@@ -48,7 +48,7 @@ Synchronous RPC. Send a prompt, wait for the response.
 
 ### `link_send`
 
-Fire-and-forget. Send to one terminal or `to: "*"` to broadcast to every other connected terminal; there is no exclusion filter.
+Fire-and-forget. Send to one terminal or `to: "*"` to broadcast to every other connected terminal; there is no exclusion filter. Sending to yourself is rejected. A send to a name that isn't connected fails with an error listing who _is_ connected — delivery failure is visible to the sender, not silent.
 
 Set `triggerTurn: true` to queue async work on the receiver. The sender does **not** get an automatic response back.
 
@@ -69,7 +69,7 @@ Use `triggerTurn: false` for fire-and-forget status notifications only — when
 
 ### `link_compact`
 
-Blocks until the target finishes compacting, then returns. Ask another terminal to compact its context window into a summary, freeing space. `link_list` exposes context usage; `link_compact` is the lever when you decide a terminal should free context — and because the call only returns once compaction is done, you can immediately hand it more work with `link_send`/`link_prompt` (no sleep, no busy-bounce). Busy targets (mid-turn or already compacting) decline; retry when `link_list` shows them idle. You decide the threshold; pi-link just runs the compaction you ask for. Its optional `instructions` add an extra focus to that summary.
+Blocks until the target finishes compacting, then returns (3 min ceiling — the call then errors for you, though the target may still finish compacting on its own; check it before assuming failure). Ask another terminal to compact its context window into a summary, freeing space. `link_list` exposes context usage; `link_compact` is the lever when you decide a terminal should free context — and because the call only returns once compaction is done, you can immediately hand it more work with `link_send`/`link_prompt` (no sleep, no busy-bounce). Busy targets (mid-turn or already compacting) decline; retry when `link_list` shows them idle. You decide the threshold; pi-link just runs the compaction you ask for. Its optional `instructions` add an extra focus to that summary.
 
 ---