fellow-agents 0.0.16 → 0.0.19

package/dist/commands/start.js

@@ -97,14 +97,20 @@ export async function start(opts) {
     // 5. Install AI skills (SKILL.md files) to known CLI paths
     console.log("[5/8] Installing skills...");
     const skillResult = installSkills();
-    if (skillResult.written.length > 0) {
-        console.log(`  Installed ${skillResult.written.length} skill file(s)`);
+    const skillTotal = skillResult.written.length + skillResult.refreshed.length + skillResult.skipped.length;
+    if (skillTotal === 0) {
+        console.log("  No bundled skills");
     }
-    if (skillResult.skipped.length > 0) {
-        console.log(`  Preserved ${skillResult.skipped.length} existing skill file(s) — delete to refresh`);
-    }
-    if (skillResult.written.length === 0 && skillResult.skipped.length === 0) {
-        console.log("  No skills bundled");
+    else {
+        if (skillResult.written.length > 0) {
+            console.log(`  Installed ${skillResult.written.length} skill file(s)`);
+        }
+        if (skillResult.refreshed.length > 0) {
+            console.log(`  Refreshed ${skillResult.refreshed.length} skill file(s) to latest`);
+        }
+        if (skillResult.skipped.length > 0) {
+            console.log(`  Preserved ${skillResult.skipped.length} existing skill file(s) — customized or unowned`);
+        }
     }
     // PATH trick: prepend bin dir so agents find emcom/tracker
     const env = { ...process.env, PATH: `${binDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH}` };

package/dist/commands/uninstall.js

@@ -86,11 +86,17 @@ export function uninstall(opts) {
     // Remove skills we installed (only the ones that match the shipped bytes —
     // user-customized files are preserved).
     const skillResult = uninstallSkills();
-    if (skillResult.removed.length > 0) {
-        console.log(`  Removed ${skillResult.removed.length} skill file(s)`);
+    const skillTotal = skillResult.removed.length + skillResult.preserved.length;
+    if (skillTotal === 0) {
+        console.log("  No fellow-agents-tracked skill files found");
     }
-    if (skillResult.preserved.length > 0) {
-        console.log(`  Preserved ${skillResult.preserved.length} customized skill file(s)`);
+    else {
+        if (skillResult.removed.length > 0) {
+            console.log(`  Removed ${skillResult.removed.length} skill file(s)`);
+        }
+        if (skillResult.preserved.length > 0) {
+            console.log(`  Preserved ${skillResult.preserved.length} customized/unowned skill file(s)`);
+        }
     }
     for (const t of targets) {
         try {

package/dist/lib/services.js

@@ -89,6 +89,52 @@ function killTree(pid) {
         process.kill(pid);
     }
 }
+// Scan a port for any listening PID and kill it. Used as a fallback when our
+// PID files are missing (e.g., user ran clean) but a previous service is still
+// holding the port — produces orphans that block re-start and re-uninstall.
+function killOnPort(port) {
+    const killed = [];
+    try {
+        if (process.platform === "win32") {
+            const output = execSync(`netstat -ano -p tcp`, { stdio: ["ignore", "pipe", "ignore"] }).toString();
+            const pids = new Set();
+            for (const line of output.split("\n")) {
+                const trimmed = line.trim();
+                // Match "127.0.0.1:8800   ...   LISTENING   <pid>"
+                if (trimmed.includes(`:${port}`) && trimmed.includes("LISTENING")) {
+                    const parts = trimmed.split(/\s+/);
+                    const pid = parseInt(parts[parts.length - 1], 10);
+                    if (!isNaN(pid) && pid > 4)
+                        pids.add(pid); // skip system PIDs 0/4
+                }
+            }
+            for (const pid of pids) {
+                try {
+                    execSync(`taskkill /F /T /PID ${pid}`, { stdio: "ignore" });
+                    killed.push(pid);
+                }
+                catch { }
+            }
+        }
+        else {
+            const output = execSync(`lsof -ti:${port}`, { stdio: ["ignore", "pipe", "ignore"] }).toString();
+            for (const line of output.split("\n")) {
+                const pid = parseInt(line.trim(), 10);
+                if (!isNaN(pid)) {
+                    try {
+                        process.kill(pid, "SIGKILL");
+                        killed.push(pid);
+                    }
+                    catch { }
+                }
+            }
+        }
+    }
+    catch {
+        // No output (no process listening) or command failed — return empty
+    }
+    return killed;
+}
 export function stopAll() {
     for (const name of ["emcom-server", "pty-win"]) {
         const pid = readPid(name);
@@ -106,6 +152,14 @@ export function stopAll() {
         }
         removePid(name);
     }
+    // Fallback: scan default ports for orphans whose PID files have been lost.
+    // Common after `fellow-agents clean` or manual `Remove-Item` of pid/ dir.
+    for (const port of [3700, 8800]) {
+        const orphans = killOnPort(port);
+        if (orphans.length > 0) {
+            console.log(`  Killed orphan(s) on :${port} (pid ${orphans.join(", ")})`);
+        }
+    }
 }
 export function waitForHealth(url, timeoutMs = 30000) {
     const mod = url.startsWith("https") ? https : http;

package/dist/lib/skills.js

@@ -1,6 +1,7 @@
-import { existsSync, readdirSync, mkdirSync, copyFileSync, readFileSync, statSync, rmSync, rmdirSync } from "fs";
+import { existsSync, readdirSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, statSync, rmSync, rmdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { createHash } from "crypto";
 import { skillsDir } from "./paths.js";
 // Three target paths per agentskills.io convention — installed CLIs vary; we write to all three
 // so the skill works regardless of which AI CLI the user is using.
@@ -9,15 +10,24 @@ const targetRoots = [
     join(homedir(), ".copilot", "skills"), // GitHub Copilot CLI
     join(homedir(), ".agents", "skills"), // pi + cross-tool universal location
 ];
+// Sidecar suffix — written next to each shipped file, contains the SHA-256 of
+// the content we shipped. Used to detect "we wrote this, user hasn't touched"
+// vs "user customized" on later installs and uninstall.
+const SIDECAR_SUFFIX = ".fellow-agents-shipped";
 /**
  * Copy bundled skills to all known target paths.
  *
- * Strategy: write if absent. Never overwrite existing files (treated as
- * user-customized). To force a refresh, the user can delete the target file
- * and re-run fellow-agents.
+ * Update semantics (v0.0.18+):
+ * - Target absent: write file + sidecar.
+ * - Target has sidecar AND target SHA matches sidecar: we own it, user hasn't
+ *   modified — safe to refresh with new content. Write file + update sidecar.
+ * - Target has sidecar AND target SHA differs from sidecar: user edited our
+ *   shipped file. Preserve, don't touch sidecar.
+ * - Target exists with NO sidecar: pre-existing file (pre-v0.0.18 install, or
+ *   user-placed). Preserve — we can't prove we own it.
  */
 export function installSkills() {
-    const result = { written: [], skipped: [] };
+    const result = { written: [], refreshed: [], skipped: [] };
     if (!existsSync(skillsDir))
         return result;
     const skillNames = readdirSync(skillsDir).filter((name) => {
@@ -33,16 +43,42 @@ export function installSkills() {
         const skillFiles = walkSkillFiles(sourceSkillDir);
         for (const relPath of skillFiles) {
             const sourceFile = join(sourceSkillDir, relPath);
+            const sourceSha = sha256File(sourceFile);
             for (const root of targetRoots) {
                 const targetFile = join(root, skillName, relPath);
-                if (existsSync(targetFile)) {
-                    // User-customized or already-installed — never overwrite
+                const sidecarFile = targetFile + SIDECAR_SUFFIX;
+                if (!existsSync(targetFile)) {
+                    // First-time install
+                    mkdirSync(join(root, skillName, ...relPath.split(/[\\/]/).slice(0, -1)), { recursive: true });
+                    copyFileSync(sourceFile, targetFile);
+                    writeFileSync(sidecarFile, sourceSha, "utf-8");
+                    result.written.push(targetFile);
+                    continue;
+                }
+                // Target exists — decide based on sidecar
+                if (!existsSync(sidecarFile)) {
+                    // No sidecar → we can't prove we own this file, preserve
                     result.skipped.push(targetFile);
                     continue;
                 }
-                mkdirSync(join(root, skillName, ...relPath.split(/[\\/]/).slice(0, -1)), { recursive: true });
-                copyFileSync(sourceFile, targetFile);
-                result.written.push(targetFile);
+                const recordedSha = readFileSync(sidecarFile, "utf-8").trim();
+                const currentSha = sha256File(targetFile);
+                if (currentSha === recordedSha) {
+                    // Target matches what we previously shipped → user hasn't touched → safe refresh
+                    if (currentSha === sourceSha) {
+                        // Same shipped version, nothing to do
+                        result.skipped.push(targetFile);
+                    }
+                    else {
+                        copyFileSync(sourceFile, targetFile);
+                        writeFileSync(sidecarFile, sourceSha, "utf-8");
+                        result.refreshed.push(targetFile);
+                    }
+                }
+                else {
+                    // User edited the file after we shipped it — preserve
+                    result.skipped.push(targetFile);
+                }
             }
         }
     }
@@ -51,13 +87,15 @@ export function installSkills() {
 /**
  * Remove skill files we installed, if the user hasn't modified them.
  *
- * Compares each target file byte-for-byte against the bundled version.
- * Matching → safe to delete (we wrote it, nothing changed). Differing →
- * preserve (user customized or it was already there before we showed up).
+ * Sidecar-based ownership detection (v0.0.18+):
+ * - Target has sidecar AND target SHA matches sidecar → we own it, user
+ *   hasn't touched → delete file + sidecar.
+ * - Target has sidecar AND target SHA differs → user customized → preserve
+ *   (file and sidecar).
+ * - Target has no sidecar → we can't prove we own it → preserve.
  *
  * After file removal, attempts to clean up empty skill directories and
- * empty target root directories (e.g., ~/.copilot/skills/ if user doesn't
- * have Copilot installed).
+ * empty target root directories.
  */
 export function uninstallSkills() {
     const result = { removed: [], preserved: [] };
@@ -79,15 +117,21 @@ export function uninstallSkills() {
             if (!existsSync(targetSkillDir))
                 continue;
             for (const relPath of skillFiles) {
-                const sourceFile = join(sourceSkillDir, relPath);
                 const targetFile = join(targetSkillDir, relPath);
+                const sidecarFile = targetFile + SIDECAR_SUFFIX;
                 if (!existsSync(targetFile))
                     continue;
+                if (!existsSync(sidecarFile)) {
+                    // No sidecar — can't prove ownership, preserve
+                    result.preserved.push(targetFile);
+                    continue;
+                }
                 try {
-                    const sourceBytes = readFileSync(sourceFile);
-                    const targetBytes = readFileSync(targetFile);
-                    if (Buffer.compare(sourceBytes, targetBytes) === 0) {
+                    const recordedSha = readFileSync(sidecarFile, "utf-8").trim();
+                    const currentSha = sha256File(targetFile);
+                    if (currentSha === recordedSha) {
                         rmSync(targetFile);
+                        rmSync(sidecarFile);
                         result.removed.push(targetFile);
                     }
                     else {
@@ -95,18 +139,18 @@ export function uninstallSkills() {
                     }
                 }
                 catch {
-                    // Can't read either file — skip, don't risk data loss
                     result.preserved.push(targetFile);
                 }
             }
-            // Try to remove empty skill dir (best effort — won't remove if user has
-            // their own files in there or any preserved files remain)
             tryRemoveIfEmpty(targetSkillDir);
             tryRemoveIfEmpty(root);
         }
     }
     return result;
 }
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
 function tryRemoveIfEmpty(dir) {
     try {
         if (existsSync(dir) && readdirSync(dir).length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fellow-agents",
-  "version": "0.0.16",
+  "version": "0.0.19",
   "description": "Multi-agent system — multiple Claude Code instances collaborating via messaging",
   "type": "module",
   "bin": {

package/skills/emcom/SKILL.md

@@ -111,11 +111,9 @@ Don't reply blind to in-flight work. A short delay to read the thread first prev
 emcom <subcommand> [args]
 ```
 
-If `emcom` is not in PATH, the binary lives at one of:
-- `~/.claude/skills/emcom/bin/emcom` (Claude Code skill install)
-- `~/.copilot/skills/emcom/bin/emcom` (GitHub Copilot skill install)
-- `~/.agents/skills/emcom/bin/emcom` (pi / universal skill install)
-- Or whatever PATH was set up by `npm install -g fellow-agents`
+`emcom` is on PATH when fellow-agents has been installed (`npm install -g fellow-agents`) — the npm-created shim wraps `~/.fellow-agents/bin/<platform>/emcom`. **Use the bare command. Do not prepend any skills-directory path.**
+
+If a CLI environment can't find `emcom` on PATH, that means fellow-agents isn't installed (or its bin shim hasn't been picked up by the shell). Tell the user to run `npm install -g fellow-agents` rather than guessing at a skill-bundled path — fellow-agents does not ship binaries inside `~/.claude/skills/`, `~/.copilot/skills/`, or `~/.agents/skills/`.
 
 **Permission-friendly invocation** (matters in some CLIs that gate command execution):