@opticell/workflow-companion 1.5.1 → 1.6.1

package/LICENSE

@@ -1,10 +1,21 @@
-WorkFlow Companion
-Copyright (c) 2026 Opticell Limited. All rights reserved.
+MIT License
 
-You may install and run this software free of charge to use WorkFlow for Mac,
-which you must own, from other computers. You may not sell it, or distribute
-modified copies of it.
+Copyright (c) 2026 Opticell Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED. IN NO EVENT SHALL OPTICELL LIMITED BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -31,19 +31,32 @@ many devices are on.
 1. In WorkFlow on an iPhone or iPad: **Settings → Windows Companion → Answer
    the Companion**. On a Mac: **Settings → Agent Bridge**, then the Agent
    Bridge and **Cloud Bridge** switches.
-2. On this computer, with Node 18 or later:
+2. Install **Node.js 18 or later** (LTS) if `node -v` doesn't show it:
+   Windows `winget install OpenJS.NodeJS.LTS -e`, Mac `brew install node`,
+   Linux your package manager, or the installer from <https://nodejs.org>.
+   Then close and reopen the terminal (and restart Claude Code) so `node` and
+   `npx` are found; otherwise you'll see "node is not recognized".
+3. In a normal terminal window:
 
    ```sh
-   npx -y @opticell/workflow-companion setup
+   npx -y @opticell/workflow-companion@latest setup
    ```
 
    It opens <https://companion.opticell-limited.com> to sign in with the
    Apple Account WorkFlow uses on your iPhone or Mac, then asks you to paste the token that
-   page shows.
-3. Add it to Claude:
+   page shows. It asks questions, so it can't run from Claude Code's `!`
+   prompt or another non-interactive shell; there, pass `--web-token <token>`
+   and `--name <name>`.
+4. Add it to Claude:
 
    ```sh
-   claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion
+   claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion@latest
+   ```
+
+   On **Windows**, `npx` is a script, so Claude Code needs `cmd /c` in front:
+
+   ```sh
+   claude mcp add --scope user workflow -- cmd /c npx -y @opticell/workflow-companion@latest
    ```
 
    `--scope user` makes it available in every project on this computer.
@@ -113,6 +126,22 @@ npx -y @opticell/workflow-companion wake-on
   found. `--skip-existing` treats what's already queued as handled.
 - The log is `~/.workflow-companion/wake.log`. `wake-off` stops it all.
 
+## Staying up to date
+
+- **Claude Code** runs whatever its registration names. Register it with
+  `@latest` (setup prints the exact line) and every new session uses the
+  newest release.
+- **The scheduled jobs** (keep-alive, waking) run a saved copy that npm never
+  touches, so they update themselves. At most every 6 hours they read npm's
+  entry for the package (`registry.npmjs.org/@opticell/workflow-companion/latest`).
+  When it's newer, they download the release, check it against npm's sha512
+  checksum and that Node can parse it, then swap it in. Turn this off with
+  `auto-update off`, and update by hand with `update`.
+- **Its version is reported.** Every ten minutes or so while it runs, each
+  companion writes its version, computer and check-in time to your iCloud.
+  WorkFlow 5.3.2 shows them in Settings → Agent Bridge → Who's Bridged, and
+  `status` lists every companion's version.
+
 ## Commands
 
 | | |
@@ -121,6 +150,8 @@ npx -y @opticell/workflow-companion wake-on
 | `workflow-companion setup` | Signs this computer in. Takes `--web-token` to skip the prompt. |
 | `workflow-companion status` | Which device answers, how fresh the snapshot is, any receipts that arrived late. |
 | `workflow-companion keepalive` | Renews the sign-in. The scheduled job runs this. |
+| `workflow-companion update` | Updates the scheduled jobs' copy to the latest release now, and shows how to keep Claude Code on `@latest`. |
+| `workflow-companion auto-update on\|off` | Whether the scheduled jobs update themselves (on by default). |
 | `workflow-companion wake-on` | Starts a Claude Code session on its own when work for its name arrives. See above. |
 | `workflow-companion wake-off` | Stops that. Work waits until you ask Claude here. |
 | `workflow-companion wake` | One check of the queue. The scheduled job runs this. |
@@ -133,8 +164,11 @@ npx -y @opticell/workflow-companion wake-on
   shows later in `workflow_state`.
 - **Reads come from a snapshot.** WorkFlow publishes it a few seconds after each
   change, so a read straight after a write can lag slightly.
-- **Files don't travel yet.** Attaching a file, or adding a new version of a
-  document, has to be done in WorkFlow itself.
+- **Files go through your iCloud (1.6).** Attaching a file, filing a document
+  into a project or adding a new version uploads the file to your own iCloud;
+  WorkFlow 5.3 or later on the answering Mac or iPhone attaches it and then
+  deletes the uploaded copy. Up to 50 MB a file. An older WorkFlow ignores the
+  upload and reports the file as missing.
 - **The token is a password.** `~/.workflow-companion/token.txt` opens your
   WorkFlow data in iCloud. Apple replaces it on every request, and the
   companion saves each replacement at once. Several Claude sessions on one

package/index.js

@@ -27,7 +27,7 @@ const path = require("path");
 const os = require("os");
 
 const PROTOCOL_VERSION = "2024-11-05";
-const SERVER_INFO = { name: "workflow", version: "1.5.1" };
+const SERVER_INFO = { name: "workflow", version: "1.6.1" };
 // Who the agent is in WorkFlow: the assignee its queue follows, the @name
 // that calls it, the signature on what it writes. On the Mac it's Claude.
 // A companion goes by the name chosen at setup (default "Companion"), so a
@@ -438,7 +438,45 @@ const cloud = (() => {
     return { status: "pending", message: `Sent to iCloud, but WorkFlow hasn't answered within ${Math.round(schedule.reduce((a, b) => a + b) / 1000)} s (${macLine()}). The command waits safely in iCloud and runs when WorkFlow next looks; its receipt shows in workflow_state.` };
   }
 
-  return { call, lookup, load, send, macLine, pending, takeLate, collect, field };
+  // Files (1.6). The file goes up as its own record of the snapshot's type,
+  // whose "snapshot" asset field is already in the Production schema, so no
+  // schema change was needed. The device that applies the command fetches it
+  // by name and deletes it afterwards. CloudKit Web Services takes an asset
+  // in three steps: ask for an upload address, send the bytes there, then
+  // save a record that refers to what came back.
+  async function upload(file) {
+    const recordName = `upload-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+    const asked = await call("private/assets/upload", { zoneID, tokens: [{ recordType: "BridgeSnapshot", fieldName: "snapshot", recordName }] });
+    const url = asked.tokens && asked.tokens[0] && asked.tokens[0].url;
+    if (!url) throw new Error("iCloud didn't give an address to upload the file to.");
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/octet-stream" }, body: fs.readFileSync(file) });
+    } catch (e) {
+      throw new Error(`Couldn't upload ${path.basename(file)} to iCloud (${(e.cause && e.cause.code) || e.message}).`);
+    }
+    if (!res.ok) throw new Error(`iCloud refused the upload of ${path.basename(file)} (HTTP ${res.status}).`);
+    const body = await res.json().catch(() => ({}));
+    if (!body.singleFile) throw new Error("iCloud took the file but didn't say where it is.");
+    const out = await call("private/records/modify", { zoneID, operations: [{ operationType: "create", record: {
+      recordType: "BridgeSnapshot", recordName,
+      fields: {
+        snapshot: { value: body.singleFile },
+        sha: { value: path.basename(file), type: "STRING" },
+        generatedAt: { value: Date.now(), type: "TIMESTAMP" },
+      },
+    } }] });
+    const err = recordError((out.records || [])[0]);
+    if (err) throw err;
+    return recordName;
+  }
+
+  async function discardUpload(recordName) {
+    if (!/^upload-/.test(recordName)) return;
+    await call("private/records/modify", { zoneID, operations: [{ operationType: "forceDelete", record: { recordName } }] });
+  }
+
+  return { call, lookup, load, send, macLine, pending, takeLate, collect, field, upload, discardUpload };
 })();
 
 // The companions WorkFlow knows, from the hidden task the applying device
@@ -507,14 +545,43 @@ function documentLine(d) {
   return `${d.number} v${d.version}  ${d.name}${d.type ? `  [${d.type}]` : ""}${d.status ? `  (${d.status})` : ""}  — ${where}${d.folder ? ` / ${d.folder}` : ""}`;
 }
 
-function stageFile(file) {
-  if (CLOUD) throw new Error("Files can't be sent through iCloud yet — attach it in WorkFlow itself, or put its text in a comment or note.");
-  const src = path.resolve(file.replace(/^~/, os.homedir()));
-  if (!fs.existsSync(src)) throw new Error(`no such file: ${src}`);
+// WorkFlow's own limit on one attachment (PMAttachment.maxAttachmentBytes).
+const MAX_FILE_BYTES = 50 * 1024 * 1024;
+
+// Gets a file to WorkFlow. On the Mac it is copied into the bridge folder;
+// from a companion (1.6) it is uploaded to the user's iCloud first and the
+// command names the upload. Returns the fields the command needs.
+async function stageFile(file) {
+  const src = path.resolve(String(file).replace(/^~/, os.homedir()));
+  if (!fs.existsSync(src) || !fs.statSync(src).isFile()) throw new Error(`no such file: ${src}`);
+  const fileName = path.basename(src);
+  if (CLOUD) {
+    const size = fs.statSync(src).size;
+    if (size > MAX_FILE_BYTES) throw new Error(`${fileName} is ${(size / 1048576).toFixed(1)} MB; WorkFlow takes files up to 50 MB.`);
+    return { fileName, upload: await cloud.upload(src) };
+  }
   fs.mkdirSync(P.attachments, { recursive: true });
-  const staged = path.join(P.attachments, path.basename(src));
+  const staged = path.join(P.attachments, fileName);
   if (path.resolve(staged) !== src) fs.copyFileSync(src, staged);
-  return path.basename(src);
+  return { fileName };
+}
+
+// Sends a file command. If the command never reaches iCloud, the upload it
+// named is removed again rather than left behind.
+async function sendWithFile(op, fields, staged, waitMs) {
+  try {
+    const receipt = await send(op, Object.assign({}, fields, { fileName: staged.fileName, upload: staged.upload }), waitMs);
+    // WorkFlow 5.3+ deletes the upload itself. One that refused the command
+    // (or an older WorkFlow, which doesn't know uploads) leaves it, so it
+    // goes here. Still pending: leave it, the command will need it.
+    if (staged.upload && receipt && (receipt.status === "failed" || receipt.status === "rejected")) {
+      await cloud.discardUpload(staged.upload).catch(() => {});
+    }
+    return receipt;
+  } catch (e) {
+    if (staged.upload) await cloud.discardUpload(staged.upload).catch(() => {});
+    throw e;
+  }
 }
 
 function findNote(needle) {
@@ -577,7 +644,35 @@ function mentionsMe(text) {
 // the owner asking (the same rule as the Mac's wake trigger).
 function addressedToMe(t, sharedProjects) {
   if (t.project && sharedProjects.has(t.project)) return false;
-  return (t.comments || []).slice(-3).some(c => !String(c.authorID || "").startsWith("agent.") && mentionsMe(c.text));
+  return !!addressingComment(t);
+}
+
+// Assistant hand-offs allowed in a row before a person must write again
+// (1.6, matching WorkFlow 5.3.1). Enough for "Claude, check this" -> "Jarvis,
+// done" -> a reply; never enough for two assistants to wake each other forever.
+const MAX_AGENT_HOPS = 3;
+const isAgentID = id => String(id || "").startsWith("agent.");
+
+// The comment asking this agent for something, if any. A person's @Name
+// counts in any of the last three comments. Another assistant's counts only
+// as the newest comment, and only while the run of assistant comments with an
+// @mention since a person last wrote is within MAX_AGENT_HOPS. Before 1.6 an
+// assistant's comment never counted, so Claude's "@Jarvis, brief above" woke
+// nothing.
+function addressingComment(t) {
+  const comments = t.comments || [];
+  // The newest request wins: a fresh assistant hand-off must count even when
+  // an older @mention from a person is still among the last three.
+  const last = comments[comments.length - 1];
+  if (last && isAgentID(last.authorID) && last.authorID !== AGENT.authorID && mentionsMe(last.text)) {
+    let hops = 0;
+    for (const c of [...comments].reverse()) {
+      if (!isAgentID(c.authorID)) break;
+      if (/(^|[^A-Za-z0-9_])@[A-Za-z]/.test(c.text || "")) hops++;
+    }
+    if (hops <= MAX_AGENT_HOPS) return last;
+  }
+  return comments.slice(-3).reverse().find(c => !isAgentID(c.authorID) && mentionsMe(c.text)) || null;
 }
 
 function showNote(n) {
@@ -814,10 +909,11 @@ const TOOLS = [
   {
     name: "workflow_attach_file",
     description: "Attach a local file to a task (a report, a document, an image). The file is copied into the bridge folder and consumed by the app.",
-    inputSchema: { type: "object", properties: { task: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" }, name: { type: "string", description: "Display name; defaults to the filename" } }, required: ["task", "file"] },
+    inputSchema: { type: "object", properties: { task: { type: "string" }, file: { type: "string", description: "Path to the file on this computer" }, name: { type: "string", description: "Display name; defaults to the filename" } }, required: ["task", "file"] },
     handler: async a => {
-      const name = stageFile(a.file);
-      return receiptText(await send("attach_file", { taskID: findTask(a.task).id, fileName: name, displayName: a.name }, 15000));
+      const taskID = findTask(a.task).id;
+      const staged = await stageFile(a.file);
+      return receiptText(await sendWithFile("attach_file", { taskID, displayName: a.name }, staged, 15000));
     },
   },
   {
@@ -871,25 +967,25 @@ const TOOLS = [
     name: "workflow_file_document",
     description: "File a local file straight into a project's workspace (not onto a task), with an optional profile and folder.",
     inputSchema: { type: "object", properties: {
-      project: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" },
+      project: { type: "string" }, file: { type: "string", description: "Path to the file on this computer" },
       name: { type: "string" }, type: { type: "string" }, status: { type: "string" }, author: { type: "string" },
       description: { type: "string" }, folder: { type: "string" } }, required: ["project", "file"] },
     handler: async a => {
-      const name = stageFile(a.file);
-      return receiptText(await send("attach_file", { project: a.project, fileName: name, displayName: a.name, docType: a.type,
-        docStatus: a.status, docAuthor: a.author, docSummary: a.description, docFolder: a.folder }, 15000));
+      const staged = await stageFile(a.file);
+      return receiptText(await sendWithFile("attach_file", { project: a.project, displayName: a.name, docType: a.type,
+        docStatus: a.status, docAuthor: a.author, docSummary: a.description, docFolder: a.folder }, staged, 15000));
     },
   },
   {
     name: "workflow_add_document_version",
     description: "Upload a new version of a document. The current file is kept in its history; the profile and folder carry over.",
     inputSchema: { type: "object", properties: {
-      document: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" },
+      document: { type: "string" }, file: { type: "string", description: "Path to the file on this computer" },
       comment: { type: "string", description: "What changed" } }, required: ["document", "file"] },
     handler: async a => {
       const id = findDocument(a.document).id;
-      const name = stageFile(a.file);
-      return receiptText(await send("add_document_version", { documentID: id, fileName: name, versionComment: a.comment }, 15000));
+      const staged = await stageFile(a.file);
+      return receiptText(await sendWithFile("add_document_version", { documentID: id, versionComment: a.comment }, staged, 15000));
     },
   },
   {
@@ -922,7 +1018,10 @@ async function handle(request) {
     try {
       // In iCloud mode every tool reads the Mac's latest snapshot first
       // (task lookups need it too); workflow_state reports on its own.
-      if (CLOUD && tool.name !== "workflow_state" && tool.name !== "workflow_ping") await cloud.load();
+      if (CLOUD && tool.name !== "workflow_state" && tool.name !== "workflow_ping") {
+        await cloud.load();
+        reportPresence().catch(() => {});
+      }
       return ok({ content: [{ type: "text", text: String(await tool.handler(args)) }], isError: false });
     } catch (e) {
       return ok({ content: [{ type: "text", text: `${e.message || e}` }], isError: true });
@@ -972,11 +1071,18 @@ async function cloudStateText() {
   try { lastKeepAlive = fs.readFileSync(KEEPALIVE_LOG, "utf8").trim().split("\n").pop(); } catch (_) {}
   if (lastKeepAlive) lines.push(`keep-alive  last run ${lastKeepAlive}`);
   lines.push(`waking      ${cfg.wakeEnabled ? `on — Claude Code starts by itself when @${AGENT.name} work arrives (log ${WAKE.log})` : "off — work waits until Claude here is asked (turn on: workflow-companion wake-on)"}`);
+  lines.push(`version     ${await versionLine()}`);
   lines.push(`name        ${AGENT.name} — assign tasks to "${AGENT.name}", or write @${AGENT.name} in a comment or note`);
   try {
     await cloud.load(true);
     lines.push(`answering   ${cloud.macLine()}`);
     lines.push(`snapshot    ${cloudSnap ? `${cloudSnap.tasks.length} tasks, ${(cloudSnap.notes || []).length} notes, generated ${local(cloudSnap.generatedAt)}` : "none yet — is the companion switched on in WorkFlow's Settings (Windows Companion on iPhone and iPad, Cloud Bridge on a Mac)?"}`);
+    try {
+      const ago = t => { const m = Math.round((Date.now() - t) / 60000); return m < 1 ? "just now" : m < 90 ? `${m} min ago` : m < 2880 ? `${Math.round(m / 60)} h ago` : `${Math.round(m / 1440)} days ago`; };
+      for (const c of await companionPresence()) {
+        lines.push(`companion   ${c.name}: ${c.version ? `${c.version} on ${c.host || "?"}, checked in ${ago(c.aliveAt)}${c.waking ? ", waking on" : ""}` : "hasn't reported a version (older than 1.6.1)"}`);
+      }
+    } catch (_) { /* presence is a nicety */ }
     const clash = cloudSnap ? nameClash(AGENT.name) : null;
     if (clash) lines.push(`WARNING     ${clash.host} also answers to "${AGENT.name}": both would act on @${AGENT.name}. Run setup with another --name.`);
   } catch (e) {
@@ -1073,7 +1179,8 @@ async function setup() {
   } else {
     console.log(`\nKeep-alive: ${installSchedule()}. It keeps the sign-in from lapsing while Claude isn't running.`);
   }
-  console.log(`\nNow add it to Claude Code:\n  claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion`);
+  await reportPresence(true);
+  console.log(`\nNow add it to Claude Code (@latest, so each new session picks up the newest release):\n  ${claudeCodeCommand()}`);
   if (argv.includes("--wake") && !argv.includes("--no-schedule") && !process.env.WF_NO_SCHEDULE) {
     console.log("");
     await wakeSetup(true);
@@ -1103,7 +1210,9 @@ async function keepAlive() {
   const at = new Date().toISOString();
   try {
     await cloud.call("public/users/caller");
-    logKeepAlive(`${at} ok`);
+    await reportPresence();
+    const update = await selfUpdate();
+    logKeepAlive(`${at} ok${/^updated|failed/.test(update) ? `; ${update}` : ""}`);
     return 0;
   } catch (e) {
     logKeepAlive(`${at} ${e instanceof SignInNeeded ? "SIGN-IN ENDED" : "failed"}: ${String(e.message).split("\n")[0]}`);
@@ -1199,7 +1308,7 @@ function wakeItems(snap) {
   const personal = c => !String(c.authorID || "").startsWith("agent.");
   const items = rows.map(t => {
     const byPeople = (t.comments || []).filter(personal);
-    const trigger = mine(t) ? byPeople.slice(-1)[0] : byPeople.slice(-3).reverse().find(c => mentionsMe(c.text));
+    const trigger = mine(t) ? byPeople.slice(-1)[0] : addressingComment(t);
     const why = mine(t) ? `assigned to ${AGENT.name}` : `@${AGENT.name} in a comment`;
     return { key: `task:${t.id}`, sig: trigger ? `${trigger.id || ""}@${trigger.timestamp || ""}` : "assigned",
       kind: "task", id: t.id, title: t.title, project: t.project || "", why };
@@ -1246,6 +1355,8 @@ Do the work, then report back in the task's own thread so it reaches the user's
   workflow_complete_task     only when the task is plainly finished
 For a [note], answer with workflow_reply_note, or workflow_convert_note if it describes work worth tracking.
 
+Only @mention another assistant (such as @Claude) when you need it to act: an @mention wakes it. A thank-you or an FYI must not include one.
+
 How to write into a thread (it is read on a phone): one reply per request, about six short lines at most, leading with what changed or what you need. Anything longer goes in a note (workflow_create_note) or an attached file (workflow_attach_file), linked from the reply. Never paste logs or code into a comment. If you need something from the user, ask in the comment and leave it open.
 
 You may only have some tools available. If a request needs a tool you don't have (for example running commands on this computer), say so plainly in the thread rather than working around it.
@@ -1298,6 +1409,7 @@ async function wake() {
   try {
     try { await cloud.load(true); }
     catch (e) { logWake(`${e instanceof SignInNeeded ? "SIGN-IN ENDED" : "iCloud failed"}: ${String(e.message).split("\n")[0]}`); return 1; }
+    await reportPresence();
     if (!cloudSnap) return 0;
     if (blockingClash()) { logWake(`not waking: "${AGENT.name}" is also Claude on another computer`); return 0; }
     const st = readJSON(WAKE.state, null) || {};
@@ -1352,6 +1464,7 @@ async function wake() {
     return 1;
   } finally {
     try { fs.unlinkSync(WAKE.lock); } catch (_) {}
+    try { const update = await selfUpdate(); if (/^updated|failed/.test(update)) logWake(update); } catch (_) {}
   }
 }
 
@@ -1433,13 +1546,200 @@ async function wakeSetup(on) {
     }
   }
   saveAtomic(CP.config, JSON.stringify(cfg, null, 2));
-  console.log(`Waking: ${installWakeSchedule()}.\n  Claude Code: ${claudeBin}\n  Allowed without asking: ${cfg.wakeAllowedTools || "mcp__workflow"} (change with --allow-tools)\n  Log: ${WAKE.log}`);
+  // The same switch as the keep-alive: tests (and anyone running by hand)
+  // must never land in the real crontab or Task Scheduler.
+  const scheduled = argv.includes("--no-schedule") || process.env.WF_NO_SCHEDULE
+    ? `not scheduled (--no-schedule); run "workflow-companion wake" yourself` : installWakeSchedule();
+  console.log(`Waking: ${scheduled}.\n  Claude Code: ${claudeBin}\n  Allowed without asking: ${cfg.wakeAllowedTools || "mcp__workflow"} (change with --allow-tools)\n  Log: ${WAKE.log}`);
+  return 0;
+}
+
+// ------------------------------------------------------------------ versions (1.6.1)
+
+// Each companion says which version it runs, and keeps itself current.
+//
+// Presence: a "companion-<name>" record of the Mac's own status type
+// (BridgeStatus: aliveAt, appVersion, device, pollSeconds, all already in the
+// Production schema), so WorkFlow's Who's Bridged and other companions can
+// show "Jarvis · 1.6.1 · checked in 4 min ago".
+//
+// Latest release: npm's registry entry for the package, which is JSON and is
+// by definition what was last published. Checked at most every 6 hours.
+//
+// Self-update: the scheduled jobs run a saved copy that npm never touches.
+// When a newer release is out, that copy is replaced by the published file,
+// after checking it against npm's own sha512 and that Node can parse it.
+// Claude Code stays current by being registered with @latest.
+const RELEASE_URL = "https://registry.npmjs.org/@opticell/workflow-companion/latest";
+const RELEASE_CHECK_MS = 6 * 3600 * 1000;
+const PRESENCE_EVERY_MS = 10 * 60 * 1000;
+const SAVED_SCRIPT = path.join(COMPANION.home, "workflow-companion.js");
+
+// true when version a is newer than b ("1.10.0" > "1.9.3").
+function newerVersion(a, b) {
+  const pa = String(a || "").split(".").map(n => parseInt(n, 10) || 0);
+  const pb = String(b || "").split(".").map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) > (pb[i] || 0);
+  return false;
+}
+
+function updateConfig(change) {
+  if (!fs.existsSync(CP.config)) return;
+  const cfg = readJSON(CP.config, {}) || {};
+  change(cfg);
+  saveAtomic(CP.config, JSON.stringify(cfg, null, 2));
+}
+
+// The newest published release, from npm (cached for 6 hours in config.json).
+async function latestRelease(force = false) {
+  const cached = (readJSON(CP.config, {}) || {}).latestRelease || null;
+  if (!force && cached && Date.now() - cached.checkedAt < RELEASE_CHECK_MS) return cached;
+  try {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), 8000);
+    const res = await fetch(RELEASE_URL, { signal: ctl.signal });
+    clearTimeout(timer);
+    if (!res.ok) return cached;
+    const j = await res.json();
+    if (!j || !j.version) return cached;
+    const info = { version: j.version, tarball: j.dist && j.dist.tarball, integrity: j.dist && j.dist.integrity, checkedAt: Date.now() };
+    updateConfig(cfg => { cfg.latestRelease = info; });
+    return info;
+  } catch (_) {
+    return cached;
+  }
+}
+
+// The version a saved copy of this file declares.
+function versionOfScript(file) {
+  try {
+    const m = fs.readFileSync(file, "utf8").match(/const SERVER_INFO = \{ name: "workflow", version: "([0-9.]+)" \};/);
+    return m ? m[1] : null;
+  } catch (_) { return null; }
+}
+
+// package/index.js out of an npm tarball (gzip'd ustar). No dependencies.
+function indexFromTarball(gz) {
+  const tar = require("zlib").gunzipSync(gz);
+  const text = (from, len) => tar.toString("utf8", from, from + len).replace(/\0[\s\S]*$/, "");
+  for (let off = 0; off + 512 <= tar.length;) {
+    if (tar.subarray(off, off + 512).every(b => b === 0)) break;
+    const name = text(off, 100), prefix = text(off + 345, 155);
+    const size = parseInt(text(off + 124, 12).trim(), 8) || 0;
+    const start = off + 512;
+    if ((prefix ? `${prefix}/${name}` : name) === "package/index.js") return tar.subarray(start, start + size);
+    off = start + Math.ceil(size / 512) * 512;
+  }
+  return null;
+}
+
+// Replaces the saved copy the scheduled jobs run, if a newer release is out.
+// Returns "updated from X to Y", "current", "off", or a reason it didn't.
+async function selfUpdate({ force = false } = {}) {
+  const cfg = readJSON(CP.config, null);
+  if (!cfg) return "not signed in";
+  if (cfg.autoUpdate === false && !force) return "off";
+  if (!fs.existsSync(SAVED_SCRIPT)) return "nothing scheduled";
+  const saved = versionOfScript(SAVED_SCRIPT);
+  const rel = await latestRelease(force);
+  if (!rel || !rel.version) return "couldn't reach npm";
+  if (!newerVersion(rel.version, saved)) return "current";
+  try {
+    if (!rel.tarball || !/^sha512-/.test(rel.integrity || "")) throw new Error("npm gave no tarball or checksum");
+    const res = await fetch(rel.tarball);
+    if (!res.ok) throw new Error(`download failed (HTTP ${res.status})`);
+    const gz = Buffer.from(await res.arrayBuffer());
+    const sum = "sha512-" + require("crypto").createHash("sha512").update(gz).digest("base64");
+    if (sum !== rel.integrity) throw new Error("checksum didn't match npm's");
+    const code = indexFromTarball(gz);
+    if (!code) throw new Error("no index.js in the package");
+    // A .js name: Node won't --check a file with any other extension.
+    const tmp = path.join(COMPANION.home, `workflow-companion.${process.pid}.new.js`);
+    fs.writeFileSync(tmp, code);
+    const check = require("child_process").spawnSync(process.execPath, ["--check", tmp], { encoding: "utf8" });
+    if (check.status !== 0) { try { fs.unlinkSync(tmp); } catch (_) {} throw new Error("the new file didn't parse"); }
+    fs.renameSync(tmp, SAVED_SCRIPT);
+    return `updated from ${saved || "?"} to ${rel.version}`;
+  } catch (e) {
+    return `update to ${rel.version} failed: ${e.message}`;
+  }
+}
+
+// "I'm here, this version": at most every 10 minutes unless forced.
+async function reportPresence(force = false) {
+  if (!CLOUD) return;
+  const cfg = readJSON(CP.config, null);
+  if (!cfg || !fs.existsSync(CP.token)) return;
+  if (!force && cfg.presenceAt && Date.now() - cfg.presenceAt < PRESENCE_EVERY_MS) return;
+  const slug = AGENT.authorID.slice("agent.".length);
+  try {
+    await cloud.call("private/records/modify", { zoneID: { zoneName: COMPANION.zone }, operations: [{ operationType: "forceReplace", record: {
+      recordType: "BridgeStatus", recordName: `companion-${slug}`,
+      fields: {
+        aliveAt: { value: Date.now(), type: "TIMESTAMP" },
+        appVersion: { value: SERVER_INFO.version, type: "STRING" },
+        device: { value: os.hostname(), type: "STRING" },
+        // Seconds between wake checks; 0 when waking is off.
+        pollSeconds: { value: cfg.wakeEnabled ? WAKE.everyMinutes * 60 : 0, type: "INT64" },
+      },
+    } }] });
+    updateConfig(c => { c.presenceAt = Date.now(); });
+  } catch (_) { /* reported next time */ }
+}
+
+// Every companion's last check-in, from their presence records.
+async function companionPresence() {
+  const names = companionRoster().map(e => e.name);
+  if (!names.includes(AGENT.name)) names.push(AGENT.name);
+  const slugs = names.map(n => agentFor(n).authorID.slice("agent.".length));
+  const got = await cloud.lookup(slugs.map(s => `companion-${s}`));
+  return names.map((name, i) => {
+    const r = got[`companion-${slugs[i]}`];
+    return r ? { name, version: cloud.field(r, "appVersion"), host: cloud.field(r, "device"),
+                 aliveAt: cloud.field(r, "aliveAt"), waking: (cloud.field(r, "pollSeconds") || 0) > 0 } : { name };
+  });
+}
+
+// One line for status and workflow_state: this version, and whether it's the latest.
+async function versionLine() {
+  const rel = await latestRelease();
+  const auto = (readJSON(CP.config, {}) || {}).autoUpdate === false ? "auto-update off" : "auto-update on";
+  if (!rel) return `${SERVER_INFO.version} (couldn't check npm for a newer one; ${auto})`;
+  return newerVersion(rel.version, SERVER_INFO.version)
+    ? `${SERVER_INFO.version}, UPDATE AVAILABLE: ${rel.version}. Run "npx -y @opticell/workflow-companion@latest update" (${auto})`
+    : `${SERVER_INFO.version}, the latest (${auto})`;
+}
+
+// How Claude Code should run the companion: @latest, so every new session
+// picks up the newest release. Windows needs cmd /c in front of npx.
+function claudeCodeCommand() {
+  return `claude mcp add --scope user workflow -- ${process.platform === "win32" ? "cmd /c " : ""}npx -y @opticell/workflow-companion@latest`;
+}
+
+// `workflow-companion update`: refresh the saved copy now, say the version,
+// and how to keep Claude Code current.
+async function updateNow() {
+  const result = await selfUpdate({ force: true });
+  const rel = await latestRelease();
+  console.log(`Latest release: ${rel ? rel.version : "unknown (couldn't reach npm)"}`);
+  console.log(`Scheduled jobs' copy: ${result === "nothing scheduled" ? "none (waking and keep-alive aren't scheduled here)" : result}`);
+  await reportPresence(true);
+  console.log(`\nClaude Code runs whatever its registration says. To always get the latest:\n  claude mcp remove workflow -s user\n  ${claudeCodeCommand()}`);
+  return 0;
+}
+
+// `workflow-companion auto-update on|off`.
+function setAutoUpdate(on) {
+  if (!fs.existsSync(CP.config)) { console.error(signInHelp("Not signed in yet.")); return 2; }
+  updateConfig(cfg => { cfg.autoUpdate = on; });
+  console.log(on ? "Auto-update is on: the scheduled jobs update themselves when a new release is out."
+                 : "Auto-update is off. Update by hand with: npx -y @opticell/workflow-companion@latest update");
   return 0;
 }
 
 function printConfig() {
   if (CLOUD) {
-    process.stdout.write(`Claude Code:\n  claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion\n\nClaude Desktop → Settings → Developer → Edit Config, add:\n${JSON.stringify({ mcpServers: { workflow: { command: "npx", args: ["-y", "@opticell/workflow-companion"] } } }, null, 2)}\n`);
+    process.stdout.write(`Claude Code:\n  ${claudeCodeCommand()}\n\nClaude Desktop → Settings → Developer → Edit Config, add:\n${JSON.stringify({ mcpServers: { workflow: { command: "npx", args: ["-y", "@opticell/workflow-companion@latest"] } } }, null, 2)}\n`);
     return;
   }
   const cfg = { mcpServers: { workflow: { command: "node", args: [__filename], env: { WF_BRIDGE: ROOT } } } };
@@ -1453,6 +1753,8 @@ const HELP = `WorkFlow companion ${SERVER_INFO.version}
   workflow-companion setup      sign this computer in to iCloud for WorkFlow (--name, --takeover, --no-browser)
   workflow-companion status     which device answers, how fresh is the snapshot
   workflow-companion keepalive  renew the sign-in (what the scheduled job runs)
+  workflow-companion update     update the scheduled jobs' copy now, and say how to keep Claude Code current
+  workflow-companion auto-update on|off   whether the scheduled jobs update themselves (on by default)
   workflow-companion wake-on    start a Claude Code session on its own when @name work arrives
                                 (--allow-tools, --model, --workdir, --max-minutes, --claude, --skip-existing)
   workflow-companion wake-off   stop doing that; work waits until you ask
@@ -1468,6 +1770,8 @@ else if (argv.includes("--help") || verb === "help") process.stdout.write(HELP);
 else if (verb === "setup") setup().then(c => { process.exitCode = c; }, e => { console.error(e.message || e); process.exitCode = 1; });
 else if (verb === "status") cloudStateText().then(t => console.log(t), e => { console.error(e.message || e); process.exitCode = 1; });
 else if (verb === "keepalive") keepAlive().then(c => { process.exitCode = c; });
+else if (verb === "update") updateNow().then(c => { process.exitCode = c; }, e => { console.error(e.message || e); process.exitCode = 1; });
+else if (verb === "auto-update") process.exitCode = setAutoUpdate(argv[argv.indexOf("auto-update") + 1] !== "off");
 else if (verb === "wake") wake().then(c => { process.exitCode = c; }, e => { logWake(`failed: ${e.message || e}`); process.exitCode = 1; });
 else if (verb === "wake-on" || verb === "wake-off") wakeSetup(verb === "wake-on").then(c => { process.exitCode = c; }, e => { console.error(e.message || e); process.exitCode = 1; });
 else if (verb === "signout") {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@opticell/workflow-companion",
-  "version": "1.5.1",
+  "version": "1.6.1",
+  "mcpName": "io.github.TeamDzX/workflow-companion",
   "description": "Lets Claude on Windows or Linux work in your WorkFlow tasks, notes and projects, through WorkFlow for Mac and your own iCloud. An MCP server.",
   "keywords": [
     "mcp",
@@ -12,7 +13,7 @@
   ],
   "homepage": "https://www.opticell-limited.com/companion",
   "author": "Opticell Limited",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "MIT",
   "bin": {
     "workflow-companion": "index.js"
   },
@@ -26,5 +27,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TeamDzX/workflow-companion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TeamDzX/workflow-companion/issues"
   }
 }