relay-companion 0.1.548 → 0.1.550

package/bootstrap/application-release.cjs

@@ -10,6 +10,10 @@ function applicationReleaseBase(channel = "stable") {
   return `${CHANNEL_ORIGINS[channel]}/v1/application-releases${channel === "stable" ? "" : `/${channel}`}`;
 }
 
+function applicationManifestUrl(channel = "stable") {
+  return `${applicationReleaseBase(channel)}/${channel === "stable" ? "stable-v3/" : ""}manifest.json`;
+}
+
 function validateApplicationRelease(payload, { version, sourceSha, channel } = {}) {
   if (![1, 2].includes(payload?.schema) || payload.product !== "Relay Application" || payload.version !== version
     || payload.sourceSha !== sourceSha || !/^\d+\.\d+\.\d+$/.test(version || "") || !/^[a-f0-9]{40}$/.test(sourceSha || "")
@@ -59,4 +63,4 @@ async function verifyApplicationArtifact(file, artifact) {
   return true;
 }
 
-module.exports = { PLATFORMS, CHANNEL_ORIGINS, applicationReleaseBase, validateApplicationRelease, verifyApplicationRelease, verifyApplicationArtifact };
+module.exports = { PLATFORMS, CHANNEL_ORIGINS, applicationReleaseBase, applicationManifestUrl, validateApplicationRelease, verifyApplicationRelease, verifyApplicationArtifact };

package/bootstrap/application-rollout.cjs

@@ -2,4 +2,4 @@
 // Capability only. Every background handoff additionally requires a fresh,
 // signed channel-specific policy. An empty device list migrates nobody.
 module.exports = Object.freeze({ enabled: true,
-  manifestUrl: "https://api.sendrelays.com/v1/application-releases/stable/manifest.json" });
+  manifestUrl: require("./application-release.cjs").applicationManifestUrl("stable") });

package/bootstrap/application-update.cjs

@@ -11,7 +11,7 @@ const rollout = require("./application-rollout.cjs");
 const CHECK_MS = 6 * 60 * 60_000;
 
 async function readOffer({ fetchImpl = globalThis.fetch, trustStore = trust, channel = "stable" } = {}) {
-  const response = await fetchImpl(`${release.applicationReleaseBase(channel)}/${channel === "stable" ? "stable/" : ""}manifest.json`, { redirect: "error", signal: AbortSignal.timeout(15_000), headers: { "Cache-Control": "no-cache" } });
+  const response = await fetchImpl(release.applicationManifestUrl(channel), { redirect: "error", signal: AbortSignal.timeout(15_000), headers: { "Cache-Control": "no-cache" } });
   if (response.status === 404) return null;
   if (!response.ok) throw new Error(`Native application offer unavailable (${response.status})`);
   let bytes = 0; const chunks = [];

package/bootstrap/recovery-launcher.cjs

@@ -505,7 +505,10 @@ async function launch({ root = __dirname, run = runChild, now = Date.now, env =
       // to an older bundle here would hand the problem to a runner that only
       // knows how to download.
       const networkFailure = /fetch failed|offline|ENOTFOUND|ECONN|ETIMEDOUT|manifest-http-|channel-discovery-http-|download.*(timed out|stalled|ended early|failed after)|configuration-unavailable/i.test(report?.lastError || "");
-      const retryableReport = ["disabled", "backoff", "emergency-backoff", "restart-failed", "reactivate-failed", "service-repair-failed", "service-repair-unhealthy"].includes(report?.status) || (report?.status === "failed" && networkFailure);
+      // A worker that lost the canonical lock to a live installer judged nothing
+      // about this bundle either; the runner normally reports that as a deferral.
+      const lostTransaction = /recovery-worker-exit-75|transaction-in-progress/i.test(report?.lastError || "");
+      const retryableReport = ["disabled", "backoff", "emergency-backoff", "restart-failed", "reactivate-failed", "service-repair-failed", "service-repair-unhealthy"].includes(report?.status) || (report?.status === "failed" && (networkFailure || lostTransaction));
       if (reported && retryableReport && result.reason !== "deadline") {
         write(path.join(root, "launcher-status.json"), { schema: 1, at: now(), status: "runner-error", version: candidate.version });
         log("done status=runner-error");

package/bootstrap/recovery-runner.cjs

@@ -9,11 +9,16 @@ const crypto = require("node:crypto");
 const { spawn, spawnSync } = require("node:child_process");
 const { stageVerifiedRuntime, releasePlatform } = require("./relay-setup.cjs");
 const { verifyReleaseEnvelope } = require("./release-signature.cjs");
+const { inFlightTransaction, workerLostLock } = require("./recovery-transaction.cjs");
 const trust = require("./trust.json");
 const CHECK_MS = 5 * 60_000;
 const DEADLINE_MS = 25 * 60_000;
 const HEARTBEAT_MS = 60_000;
 const BUSY_GRACE_MS = 15 * 60_000;
+// A runtime committed moments ago is still starting its services. Judging it
+// dead inside this window restarts or replaces a release that was about to
+// answer, and on 2026-09-21 that judgement rolled back a healthy update.
+const STARTUP_GRACE_MS = 3 * 60_000;
 
 function read(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } }
 function write(file, value) {
@@ -157,6 +162,7 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
   verifyReady = require("./recovery-readiness.cjs").waitForRecoveryReady,
   policyFactory = require("./recovery-policy.cjs").recoveryPolicy,
   validateLocal = require("./recovery-local.cjs").validateLocalRuntime,
+  transactions = inFlightTransaction,
   repairServices = require("./mac-service-recovery.cjs").repairMacServiceRegistrations } = {}) {
   const root = path.join(homeDir, ".relay");
   // Local availability is independent of update eligibility, network, memory,
@@ -206,6 +212,18 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     log(`status=${value.status}${value.desiredVersion ? ` desired=${value.desiredVersion}` : ""}${value.lastError ? ` error=${value.lastError}` : ""}`);
     return value;
   };
+  // Another live process owns the canonical transaction: the daemon's own
+  // updater, a manual `relay update`, or a previous runner still activating.
+  // Whatever it installs is judged by readiness later, never by this runner
+  // losing a race to it. The staged download, if any, is swept by the caller.
+  const deferToTransaction = (extra = {}) => {
+    let transaction = null;
+    try { transaction = transactions({ homeDir, now: now() }); } catch (error) { log(`transaction check failed: ${error.message}`); }
+    if (!transaction) return null;
+    log(`canonical transaction in flight: owner pid=${transaction.pid} request=${transaction.requestId || "-"} version=${transaction.version || "-"}`);
+    return status({ ok: true, status: "deferred-update-in-flight", runtimeHealthy: false, ...extra,
+      transaction: { pid: transaction.pid, requestId: transaction.requestId, version: transaction.version } });
+  };
   if (services.status === "deferred-update-owner") return status({ ...services, runtimeHealthy: false });
   if (services.changed || !services.ok) {
     const observed = await ready();
@@ -271,10 +289,18 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
         memoryFreeMB: memoryNow.freeMB };
       log(`installed ${version} not healthy: heartbeatFresh=${heartbeatFresh} daemonAlive=${daemonAlive} health=${JSON.stringify({ daemon: live?.daemon, pill: live?.pill, oldDaemon: live?.oldDaemon, oldPill: live?.oldPill })} readiness=${readiness ? `${readiness.reason || "ok"}${readiness.detail ? ` (${readiness.detail})` : ""}` : "not-attempted"} memoryPressured=${memoryNow.pressured}`);
       if (daemonAlive && now() - staleSince < STALE_CONFIRM_MS) return status({ ok: true, status: "stale-observed", ...base });
+      const deferred = deferToTransaction(base);
+      if (deferred) return deferred;
+      const repeatedCrash = require("./daemon-progress.cjs").repeatedStartupCrash(current, { homeDir, now: now() });
+      // A commit seconds ago means services are still coming up. Two matching
+      // startup crashes are proof of a broken release and end the grace early.
+      const committedAt = Number(current.committedAt);
+      if (!repeatedCrash && Number.isFinite(committedAt) && committedAt <= now() && now() - committedAt < STARTUP_GRACE_MS) {
+        return status({ ok: true, status: "starting", ...base, startupGraceRemainingMs: STARTUP_GRACE_MS - (now() - committedAt) });
+      }
       const busy = busyDecision(heartbeat, { homeDir, now: now() });
       if (busy) return status({ ok: true, status: busy, ...base });
       const restartKey = `restart:${current.packageRoot || current.version}`;
-      const repeatedCrash = require("./daemon-progress.cjs").repeatedStartupCrash(current, { homeDir, now: now() });
       if (repeatedCrash) {
         log(`repeated startup crash; skipping restart/reactivation for ${version}`);
         policy.failure(channel, version, { id: `startup:${current.packageRoot}:${repeatedCrash.fingerprint}`, reason: "repeated-startup-crash" });
@@ -318,7 +344,13 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     }
     // Try a distinct, previously committed local release before requiring a
     // network download. Validation reads the tree without executing its imports.
+    // An inactive journal is an incomplete update only once its owner is gone.
+    // While the owner lives, the journal is an update in progress.
     const failedCandidate = current?.active !== true ? current?.candidate : null;
+    if (failedCandidate?.version || current?.active !== true) {
+      const deferred = deferToTransaction({ desiredVersion, version: current?.version });
+      if (deferred) return deferred;
+    }
     if (failedCandidate?.version) policy.failure(channel, failedCandidate.version, { id: `journal:${failedCandidate.packageRoot || failedCandidate.version}`, reason: "incomplete-update" });
     const good = read(path.join(root, "recovery", "runtime-good.json"));
     const olderGood = read(path.join(root, "recovery", "runtime-previous-good.json"));
@@ -333,7 +365,17 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
         const observed = await ready({ version: target.version }, activationAt);
         if (!observed.ok) throw Error("local-runtime-not-healthy");
         return proven({ ok: true, status: "current", desiredVersion, version: target.version, repair: "local", lastSuccessAt: now(), failures: 0 }, observed);
-      } catch (error) { progress.fail(error.message); log('local recovery failed: ' + error.message); }
+      } catch (error) {
+        // A worker that lost the lock did not fail to restore anything: someone
+        // else is installing. Give the attempt back and let them finish.
+        const lostLock = workerLostLock(error);
+        const deferred = deferToTransaction({ desiredVersion, version: current?.version });
+        if (deferred || lostLock) {
+          progress.refund('local:' + target.packageRoot);
+          return deferred || status({ ok: true, status: "deferred-update-in-flight", desiredVersion, version: current?.version, runtimeHealthy: false });
+        }
+        progress.fail(error.message); log('local recovery failed: ' + error.message);
+      }
     }
     if (discoveryError) throw discoveryError;
     let quarantine = policy.decision(channel, desiredVersion);
@@ -346,6 +388,10 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     if (quarantine.blocked) return status({ ok: true, status: "deferred-release-cooldown", desiredVersion, runtimeHealthy: runtimeVerified, runtimeAvailable: runtimeResponsive, retryAt: quarantine.retryAt, failures: quarantine.failures });
     const busy = busyDecision(heartbeat, { homeDir, now: now() });
     if (busy) return status({ ok: true, status: busy, desiredVersion, ...repairState });
+    // Never start a five-minute download to race an installer that is already
+    // running; the daemon's updater discovers the same release we just did.
+    const deferredBeforeDownload = deferToTransaction({ desiredVersion, ...repairState });
+    if (deferredBeforeDownload) return deferredBeforeDownload;
     if (previous?.desiredVersion === desiredVersion && previous.retryAt > now()) return status({ ok: false, status: "backoff", desiredVersion, ...repairState,
       failures: previous.failures, retryAt: previous.retryAt, lastError: previous.lastError });
     // Ordinary upgrades wait for pressure to clear. An unavailable installation
@@ -369,6 +415,8 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
     if (read(path.join(root, "recovery", "policy.json"))?.autoUpdate === false) return status({ ok: true, status: "disabled", desiredVersion });
     const stillBusy = busyDecision(read(path.join(root, "recovery", "daemon.json")), { homeDir, now: now() });
     if (stillBusy) return status({ ok: true, status: stillBusy, desiredVersion });
+    const deferredAfterDownload = deferToTransaction({ desiredVersion, ...repairState });
+    if (deferredAfterDownload) return deferredAfterDownload;
     const entry = path.join(candidate.packageRoot, "src", "recovery-entry.js");
     if (!fs.existsSync(entry)) throw new Error("candidate-missing-recovery-engine");
     status({ ok: true, status: "activating", desiredVersion, ...repairState });
@@ -380,6 +428,11 @@ async function recoverLocked({ homeDir = os.homedir(), env = process.env, now =
       if (!observed.ok) throw new Error("replacement-not-healthy");
       return proven({ ok: true, status: "current", desiredVersion, version: desiredVersion, repair: "download", restarts: 0, lastSuccessAt: now(), failures: 0 }, observed);
     } catch (error) {
+      // Only a worker that owned the transaction can have judged the release.
+      // One that lost the lock, or found another owner mid-flight, judged nothing.
+      const deferred = deferToTransaction({ desiredVersion, ...repairState });
+      if (deferred) return deferred;
+      if (workerLostLock(error)) return status({ ok: true, status: "deferred-update-in-flight", desiredVersion, ...repairState, runtimeHealthy: false });
       policy.failure(channel, desiredVersion, { id: attemptId, reason: error.message });
       policy.interrupt();
       throw error;

package/bootstrap/recovery-transaction.cjs

@@ -0,0 +1,66 @@
+"use strict";
+
+// The daemon's own updater and the scheduled recovery runner both install
+// releases through the same canonical transaction. When both discover a release
+// in the same minute, one of them owns the lock and the other loses it. Losing
+// the lock says nothing about the release: the other owner is installing it
+// right now. On 2026-09-21 the runner read that loss as a broken release,
+// quarantined a version that was booting healthily, and rolled the person back.
+//
+// This module answers one question without importing the application tree:
+// is a canonical runtime transaction currently owned by a live process?
+const fs = require("node:fs");
+const path = require("node:path");
+const { processAlive, nativeProcessIdentity } = require("./recovery-launcher.cjs");
+
+// An admitted update request older than this is debris from a worker that died
+// without writing its terminal state; the lock engine reclaims after owner death.
+const REQUEST_IN_FLIGHT_MAX_MS = 45 * 60_000;
+// The exit code a recovery worker uses when the lock belongs to a live owner.
+// EX_TEMPFAIL: try again later; nothing about the release was judged.
+const WORKER_EXIT_TRANSACTION_IN_PROGRESS = 75;
+
+function read(file) { try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; } }
+
+function liveOwner(owner, { alive = processAlive, identity = nativeProcessIdentity } = {}) {
+  const pid = Number(owner?.pid);
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (!alive(pid)) return false;
+  const expected = typeof owner.processIdentity === "string" ? owner.processIdentity : "";
+  if (!expected) return true;
+  const actual = identity(pid);
+  return !actual || actual === expected;
+}
+
+// Returns the live transaction, or null when no live process owns one.
+// The lock owner is authoritative; an admitted update request adds the version
+// being installed, which the lock file does not carry.
+function inFlightTransaction({ homeDir, now = Date.now(), alive = processAlive, identity = nativeProcessIdentity } = {}) {
+  const root = path.join(homeDir, ".relay", "runtime");
+  const owner = read(path.join(root, "transaction.lock", "owner.json"));
+  let request = null;
+  let names = [];
+  try { names = fs.readdirSync(path.join(root, "update-requests")); } catch {}
+  for (const name of names) {
+    if (!/^[0-9a-f-]{36}\.json$/i.test(name)) continue;
+    const value = read(path.join(root, "update-requests", name));
+    if (value?.state !== "admitted") continue;
+    const admittedAt = Number(value.admittedAt);
+    if (!Number.isFinite(admittedAt) || admittedAt > now || now - admittedAt > REQUEST_IN_FLIGHT_MAX_MS) continue;
+    const pid = Number(value.workerPid) || Number(value.lockOwner?.pid);
+    if (!liveOwner({ pid, processIdentity: value.lockOwner?.processIdentity }, { alive, identity })) continue;
+    request = { source: "request", pid, requestId: value.requestId || null, version: value.version || null, admittedAt };
+    break;
+  }
+  if (request) return request;
+  if (owner && liveOwner(owner, { alive, identity })) {
+    return { source: "lock", pid: Number(owner.pid), requestId: owner.requestId || null, version: null, admittedAt: Number(owner.createdAt) || null };
+  }
+  return null;
+}
+
+function workerLostLock(error) {
+  return /recovery-worker-exit-75$/.test(String(error?.message || error || ""));
+}
+
+module.exports = { inFlightTransaction, liveOwner, workerLostLock, REQUEST_IN_FLIGHT_MAX_MS, WORKER_EXIT_TRANSACTION_IN_PROGRESS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.548",
+  "version": "0.1.550",
   "description": "Install Relay for Claude Code, Cowork, and Codex, then sign in from the Relay pill.",
   "homepage": "https://sendrelays.com/get-started",
   "repository": {

package/skill/manifest.json

@@ -1,17 +1,17 @@
 {
   "schemaVersion": 1,
   "name": "relay",
-  "version": "1.1.66",
+  "version": "1.1.68",
   "consentVersion": 2,
-  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.66",
+  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.68",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "133e7fce3c7d0adf4e76c6e93ad50897ce1a92924e354d58a07bc8506857b783",
+      "sha256": "0f11648dc5a5d27001b214efc474cdebcfb164eec748574cc9b3192e7a9cce68",
       "variants": {
         "dev": {
           "source": "SKILL.dev.md",
-          "sha256": "1a1a300cdaee4ceb48bfeb1ee6f3dfb92cc15e304e357b30cc280fcd09fd0653"
+          "sha256": "91daeb3d53ccf4eabaacdac701639bd2b0470af05bec94761a20153a7b2bae46"
         }
       }
     },
@@ -21,7 +21,7 @@
     },
     {
       "path": "scripts/relay-protocol.mjs",
-      "sha256": "2fcf0a459c079cdce025efd4bd8e495f5c3b8ce320f617ec04b540adf6f2f51e"
+      "sha256": "bfbc56ecaf202f77002da7eec4a33c5bfc7f3c6574df3dd385766684eb5458a3"
     },
     {
       "path": "scripts/relay-local.mjs",

package/skill/relay/SKILL.md

@@ -381,10 +381,8 @@ asking for thoughts, opinions or answers, which come back as ordinary replies.
 A technical note with dense agent context is still a message; a small or quick
 piece of work is still a Task. Respect the account's available capabilities.
 
-A Task is closed only by `relay_task_complete`. For an inbound Task, call
-`relay_task_start` before the authorized work. Opening or reading a Task does
-not authorize starting it. Once the requested work is genuinely complete, call relay_task_complete with this taskRelayId, a concise forHuman result and the complete useful evidence in forAgent, before telling the human the Task is finished. This sends the completion Relay to the requester and marks the Task Done. Returning that result is part of the human's authorization to carry out the Task: do not wait for another send instruction or request separate approval, unless the human explicitly asked to review or withhold the result. Stay within the authorized task and disclosure scope. Do not use relay_send or relay_share_link as a substitute. If work remains blocked or incomplete, report that to the human without claiming completion. Confirm the tool succeeded; after an uncertain result, retry the same payload and idempotency key, never send a separate completion.
-
+A Task is closed only by `relay_task_complete`. Started means beginning authorized work that advances the Task's requested outcome. First check the human's limits: an explicit 'without action' or 'leave status unchanged' means report only, with no start, completion or other status write, even when diagnosis is requested. 'Do not change code' alone is different: authorized investigation still counts as work. Call relay_task_start before authorized investigation, analysis, testing or implementation; read-only work counts. Opening a Task or summarizing its request alone does not count. Do not wait for code changes, experiments or acceptance of the full implementation when the human has authorized investigation. Retain the exact Task ID when a follow-up authorizes work. If the start call fails, report that the status was not updated; never claim Started without confirmation.
+Once the requested work is genuinely complete, call relay_task_complete with this taskRelayId, a concise forHuman result and the complete useful evidence in forAgent, before telling the human the Task is finished. This sends the completion Relay to the requester and marks the Task Done. Returning that result is part of the human's authorization to carry out the Task: do not wait for another send instruction or request separate approval, unless the human explicitly asked to review or withhold the result. Stay within the authorized task and disclosure scope. Do not use relay_send or relay_share_link as a substitute. If work remains blocked or incomplete, report that to the human without claiming completion. Confirm the tool succeeded; after an uncertain result, retry the same payload and idempotency key, never send a separate completion.
 A reply into the Task's chat never
 completes it: when the approval or decision itself is the deliverable,
 `relay_task_complete` carries it as forHuman. Never send a Relay merely to

package/skill/relay/scripts/relay-protocol.mjs

@@ -22,6 +22,7 @@ let transport = "auto";
 let lastTransport = "";
 const DIRECT_RECOVERY = "To renew browser approval, use connect-start <approved-api-origin> <invite-token> codex|claude_code, approve the returned URL in your browser, then connect-finish. Your own invitation from the Relay website can be used; no Companion or device enrollment is needed.";
 const SAFE_GET = [
+  /^\/v1\/share-links\/[A-Za-z0-9_-]+\/stats(?:\?.*)?$/,
   /^\/v1\/contact-groups$/,
   /^\/v1\/chats(?:\?.*)?$/,
   /^\/v1\/chats\/[A-Za-z0-9_-]+(?:\?.*)?$/,
@@ -35,6 +36,7 @@ const SAFE_GET = [
   /^\/v1\/share-links\/[A-Za-z0-9_-]+$/,
 ];
 const SAFE_POST = [
+  /^\/v1\/share-links\/[A-Za-z0-9_-]+\/placements$/,
   /^\/v1\/relays$/,
   /^\/v1\/relays\/[A-Za-z0-9_-]+\/forward$/,
   /^\/v1\/relays\/[A-Za-z0-9_-]+\/read$/,
@@ -45,6 +47,7 @@ const SAFE_POST = [
 // A person may correct a message they sent, or take back a link they minted
 // or a message they sent, from the same conversation. Both are sender-only on
 // the server and converge on an exact retry.
+const SAFE_PUT = [/^\/v1\/share-links\/[A-Za-z0-9_-]+\/placements\/[A-Za-z0-9_-]+\/snapshot$/];
 const SAFE_PATCH = [
   /^\/v1\/messages\/[A-Za-z0-9_-]+$/,
 ];
@@ -217,7 +220,7 @@ async function readStdin() {
 }
 
 function allowed(method, requestPath) {
-  const list = method === "GET" ? SAFE_GET : method === "POST" ? SAFE_POST : method === "PATCH" ? SAFE_PATCH : method === "DELETE" ? SAFE_DELETE : [];
+  const list = method === "PUT" ? SAFE_PUT : method === "GET" ? SAFE_GET : method === "POST" ? SAFE_POST : method === "PATCH" ? SAFE_PATCH : method === "DELETE" ? SAFE_DELETE : [];
   return list.some((pattern) => pattern.test(requestPath));
 }
 
@@ -691,6 +694,9 @@ const DIRECT_TOOLS = {
   relay_chat_fetch: directTool("Read a page of one chat without receipts. Defaults to the newest 25, oldest first. HTTPS requires chatId. Continue with nextBeforeCursor or nextAfterCursor; a page is not the full history.", { chatId: idField, limit: { type: "integer", minimum: 1, maximum: 200 }, beforeCursor: { type: "string" }, afterCursor: { type: "string" } }, ["chatId"], { full: true }),
   relay_thread_fetch: directTool("Read related Relays by their internal threadId without receipts.", { threadId: idField }, ["threadId"]),
   relay_inbox_list: directTool("Read recent inbox metadata, or up to 20 exact Relay packet envelopes in items [{relayId, ...response}]. Does not send receipts. Todo queries require Companion.", { relayIds: { type: "array", items: idField, minItems: 1, maxItems: 20 } }),
+  relay_share_stats: directTool("Read owner-only share statistics. Separates legacy opens, estimated external browsers, button attempts, successful copies, agent fetches and account outcomes. Does not mark read. Browser estimates are not people; owner/test events are excluded. Optional from/to are ISO timestamps.", {"relayId": {"type": "string", "minLength": 1}, "from": {"type": "string"}, "to": {"type": "string"}}, ["relayId"], { full: true, readOnly: true }),
+  relay_share_placement: directTool("Create an attributed URL for an existing share link. This sends nothing. Use separate placements for X replies and internal previews; test=true excludes that placement from acquisition. Reuse the same idempotency key on retries.", {"relayId": {"type": "string", "minLength": 1}, "idempotencyKey": {"type": "string", "minLength": 8}, "label": {"type": "string", "maxLength": 120}, "source": {"type": "string", "enum": ["x", "relay", "internal", "other"]}, "postId": {"type": "string", "pattern": "^[0-9]{1,30}$"}, "test": {"type": "boolean"}}, ["relayId", "idempotencyKey", "label", "source"], { full: true, readOnly: false }),
+  relay_share_snapshot: directTool("Save a manually observed X analytics snapshot for an X placement. Keep X aggregate impressions and link clicks separate from Relay visits; never infer unique people or subtract guessed self clicks.", {"relayId": {"type": "string", "minLength": 1}, "placementId": {"type": "string"}, "observedAt": {"type": "string"}, "impressions": {"type": "integer", "minimum": 0}, "linkClicks": {"type": "integer", "minimum": 0}}, ["relayId", "placementId", "observedAt", "impressions", "linkClicks"], { full: true, readOnly: false }),
   relay_sent_list: directTool("Read sent history. Optional recipient matches a name or address.", { recipient: stringField, limit: { type: "integer", minimum: 1, maximum: 100 } }),
   relay_mark_read: directTool("Send a read receipt only when the person requested reading this exact Relay and you present it.", { relayId: idField, idempotencyKey: stringField }, ["relayId", "idempotencyKey"], { readOnly: false }),
   relay_send: directTool("Send authorized correspondence or a Task using a resolved recipient, a title and both documents. Preserve the exact body and idempotency key on retry. HTTPS cannot send to unresolved names or email addresses; resolve an existing contact first or mint a link.", {
@@ -772,6 +778,15 @@ async function directToolCommand(command, body, config) {
       for (const relayId of new Set(args.relayIds)) items.push({ relayId, ...await request("GET", `/v1/relays/${relayId}`) });
       value = { items, readStateChanged: false, readReceiptsSent: false };
     } else value = await request("GET", "/v1/inbox?view=summary");
+  } else if (name === "relay_share_stats") {
+    const query = new URLSearchParams(Object.entries({ from: args.from, to: args.to }).filter(([, v]) => v !== undefined));
+    value = await request("GET", `/v1/share-links/${encodeURIComponent(args.relayId)}/stats?${query}`);
+  } else if (name === "relay_share_placement") {
+    const { relayId, ...body } = args;
+    value = await request("POST", `/v1/share-links/${encodeURIComponent(relayId)}/placements`, body);
+  } else if (name === "relay_share_snapshot") {
+    const { relayId, placementId, ...body } = args;
+    value = await request("PUT", `/v1/share-links/${encodeURIComponent(relayId)}/placements/${encodeURIComponent(placementId)}/snapshot`, body);
   } else if (name === "relay_sent_list") {
     const result = await request("GET", "/v1/sent?limit=100");
     const needle = String(args.recipient || "").toLowerCase();

package/skill/variants/SKILL.dev.md

@@ -381,10 +381,8 @@ asking for thoughts, opinions or answers, which come back as ordinary replies.
 A technical note with dense agent context is still a message; a small or quick
 piece of work is still a Task. Respect the account's available capabilities.
 
-A Task is closed only by `relay_task_complete`. For an inbound Task, call
-`relay_task_start` before the authorized work. Opening or reading a Task does
-not authorize starting it. Once the requested work is genuinely complete, call relay_task_complete with this taskRelayId, a concise forHuman result and the complete useful evidence in forAgent, before telling the human the Task is finished. This sends the completion Relay to the requester and marks the Task Done. Returning that result is part of the human's authorization to carry out the Task: do not wait for another send instruction or request separate approval, unless the human explicitly asked to review or withhold the result. Stay within the authorized task and disclosure scope. Do not use relay_send or relay_share_link as a substitute. If work remains blocked or incomplete, report that to the human without claiming completion. Confirm the tool succeeded; after an uncertain result, retry the same payload and idempotency key, never send a separate completion.
-
+A Task is closed only by `relay_task_complete`. Started means beginning authorized work that advances the Task's requested outcome. First check the human's limits: an explicit 'without action' or 'leave status unchanged' means report only, with no start, completion or other status write, even when diagnosis is requested. 'Do not change code' alone is different: authorized investigation still counts as work. Call relay_task_start before authorized investigation, analysis, testing or implementation; read-only work counts. Opening a Task or summarizing its request alone does not count. Do not wait for code changes, experiments or acceptance of the full implementation when the human has authorized investigation. Retain the exact Task ID when a follow-up authorizes work. If the start call fails, report that the status was not updated; never claim Started without confirmation.
+Once the requested work is genuinely complete, call relay_task_complete with this taskRelayId, a concise forHuman result and the complete useful evidence in forAgent, before telling the human the Task is finished. This sends the completion Relay to the requester and marks the Task Done. Returning that result is part of the human's authorization to carry out the Task: do not wait for another send instruction or request separate approval, unless the human explicitly asked to review or withhold the result. Stay within the authorized task and disclosure scope. Do not use relay_send or relay_share_link as a substitute. If work remains blocked or incomplete, report that to the human without claiming completion. Confirm the tool succeeded; after an uncertain result, retry the same payload and idempotency key, never send a separate completion.
 A reply into the Task's chat never
 completes it: when the approval or decision itself is the deliverable,
 `relay_task_complete` carries it as forHuman. Never send a Relay merely to