@sjawhar/claude-envoy 1.14.1 → 1.16.0

package/dist/envoy-channel.js

@@ -37088,7 +37088,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_message",
     example: { issue: "DSP-1", body: "Implementation started." },
-    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A BTW, Aside or Steer " + "frame carries a reply_with command: answer with it, on that issue. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
+    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A frame reading expects_reply: optional or " + "required carries a reply_with command: answer with it, on that issue. One reading false carries none and asks for no answer; where " + "you answer one anyway, its card names what to answer. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
       body: z.string().describe(`Update text. ${BODY_BLOCK_RULE}`),
@@ -38415,6 +38415,7 @@ var DISPATCH_TEXT_REFERENCES = [
 ];
 // ../contracts/src/envelope.ts
 var isSubject = (value) => typeof value === "string" && value.length > 0;
+var EXPECTS_REPLY_VALUES = [false, "optional", "required"];
 var EnvelopeSchema = object({
   event_id: string2().min(1),
   source: _enum2([
@@ -38448,7 +38449,7 @@ var EnvelopeSchema = object({
   in_reply_to: string2().min(1).optional(),
   supersedes: string2().min(1).optional(),
   urgency: _enum2(["low", "med", "high", "blocking"]).optional(),
-  expects_reply: _enum2(["none", "optional", "required"]).optional()
+  expects_reply: literal(EXPECTS_REPLY_VALUES).optional()
 });
 var MINTED_DEDUPE_KEY_PATTERN = "^(?:envoy\\.role\\.forward\\.)?(?:publish|agent\\.[^.]+)\\.(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$";
 var mintedDedupeKey = new RegExp(MINTED_DEDUPE_KEY_PATTERN);
@@ -38469,6 +38470,7 @@ function dedupeKeyNamesItsEvent(envelope) {
 }
 // ../contracts/src/envoy-session.ts
 var SESSION_HEARTBEAT_MS = 90000;
+var SESSION_LIVE_WINDOW_MS = 300000;
 var LISTENER_CALL_TIMEOUT_MS = 5000;
 var LISTENER_CALL_RETRY_DELAY_MS = 250;
 var LISTENER_CALL_ATTEMPTS = 2;
@@ -38586,6 +38588,12 @@ var SLACK_POST_TEXT_MAX = 4000;
 function overCapMessage(length, max) {
   return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
 }
+function literalOfSet(api, values) {
+  const node = api.literal?.(values);
+  if (node === undefined || typeof node.safeParse !== "function")
+    return;
+  return values.every((value) => node.safeParse(value).success) ? node : undefined;
+}
 function zodSchemaApi(zod) {
   const api = zod;
   return {
@@ -38614,6 +38622,7 @@ function zodSchemaApi(zod) {
     },
     boolean: () => api.boolean(),
     enum: (values) => api.enum(values),
+    literal: (values) => literalOfSet(api, values) ?? api.unknown(),
     unknown: () => api.unknown(),
     array: (item, opts = {}) => {
       let schema = api.array(item);
@@ -43288,6 +43297,7 @@ var InboundSenderSchema = object({
   title: string2().optional(),
   roles: array(string2()).optional()
 });
+var InboundExpectsReplySchema = literal([...EXPECTS_REPLY_VALUES, "none"]).transform((value) => value === "none" ? false : value);
 var InboundEnvelopeSchema = object({
   event_id: string2().optional(),
   source: string2(),
@@ -43304,7 +43314,7 @@ var InboundEnvelopeSchema = object({
   in_reply_to: string2().optional(),
   supersedes: string2().optional(),
   urgency: string2().optional(),
-  expects_reply: string2().optional()
+  expects_reply: InboundExpectsReplySchema.optional()
 }).passthrough();
 function tolerantShape(shape) {
   return Object.fromEntries(Object.entries(shape).map(([key, schema]) => [key, _catch2(schema, undefined)]));
@@ -44011,7 +44021,8 @@ function renderInbound(raw, sessionID, subject, wholeBody) {
       break;
   }
   const role = envelope.sender?.roles?.[0];
-  const reply = dispatchReply ?? replyWith(envelope);
+  const wantsNoReply = envelope.expects_reply === false;
+  const reply = wantsNoReply ? undefined : dispatchReply ?? replyWith(envelope);
   const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
   const unrecognised = [
     ...parseIssues,
@@ -44030,7 +44041,7 @@ function renderInbound(raw, sessionID, subject, wholeBody) {
     ...inReplyTo === undefined ? {} : { re: inReplyTo },
     ...envelope.supersedes === undefined ? {} : { supersedes: envelope.supersedes },
     ...reply === undefined ? {} : { reply_with: reply },
-    ...role === undefined ? {} : {
+    ...role === undefined || wantsNoReply ? {} : {
       reply_role: {
         tool: "envoy_publish",
         args: { topic: `notifications.role.${role}`, message: "..." }
@@ -44804,7 +44815,9 @@ var RoleWireSchema = object({
   host: string2().optional(),
   last_seen: number2().int(),
   state: WireStateSchema,
-  holder_state: SessionStateSchema.optional()
+  holder_state: SessionStateSchema.optional(),
+  client_instance_id: string2().optional(),
+  handed_back: boolean2().optional()
 });
 var RoleHeldWireSchema = object({
   error: string2(),
@@ -44883,6 +44896,21 @@ function mergeInterestSources(registryTopics, liveTopics) {
 function holderStateOf(role) {
   return role.holder_state ?? role.state;
 }
+function namedProcess(id) {
+  return id === "" ? undefined : id;
+}
+function roleHeldBy(info, sessionID, clientInstanceID) {
+  if (info === undefined || info.holder !== sessionID || info.handed_back === true)
+    return false;
+  const holding = namedProcess(info.client_instance_id);
+  return holding === undefined || holding === namedProcess(clientInstanceID);
+}
+function mayActOnRoleRecord(writer, clientInstanceID, holdsRole) {
+  const wrote = namedProcess(writer);
+  if (wrote === undefined || wrote === namedProcess(clientInstanceID))
+    return true;
+  return !holdsRole;
+}
 function newClientInstanceID() {
   return Array.from(crypto.getRandomValues(new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
 }
@@ -45078,7 +45106,8 @@ function createEnvoyClient(config) {
     unsubscribe: async (input) => {
       await post("/v1/interests/unsubscribe", {
         session_id: input.sessionID,
-        topics: expandSubscriptionTopics(input.topics)
+        topics: expandSubscriptionTopics(input.topics),
+        ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
       }, { actingSession: input.sessionID });
     },
     getInterest: async (sessionID) => InterestWireSchema.parse(JSON.parse(await request(`/v1/interests/${sessionID}`, {}))),
@@ -45148,7 +45177,8 @@ function createEnvoyClient(config) {
         session_id: input.sessionID,
         role: input.role,
         ...soft ? { soft: true } : {},
-        ...previous === "" ? {} : { previous_session_id: previous }
+        ...previous === "" ? {} : { previous_session_id: previous },
+        ...input.clientInstanceID === undefined ? {} : { client_instance_id: input.clientInstanceID }
       };
       let raw;
       try {
@@ -45957,6 +45987,9 @@ function replayLedgerIdentity(frame) {
     ...frame.dedupe_key === undefined || !dedupeKeyNamesItsEvent(frame) ? {} : { dedupe_key: frame.dedupe_key }
   };
 }
+var StoredEnvelopeSchema = EnvelopeSchema.extend({
+  expects_reply: InboundExpectsReplySchema.optional()
+});
 function parseEnvelope(data) {
   let parsed;
   try {
@@ -45964,7 +45997,7 @@ function parseEnvelope(data) {
   } catch {
     return;
   }
-  const result = EnvelopeSchema.safeParse(parsed);
+  const result = StoredEnvelopeSchema.safeParse(parsed);
   return result.success ? result.data : undefined;
 }
 function createLedger(now) {
@@ -51811,13 +51844,12 @@ var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across
 var STORED_DELIVERY = "Stored topics (agent, dispatch, github, slack, legion, ghostwispr, whatsapp; a role message " + "reaches its holder as a stored copy on the holder's agent topic) reach each subscribed session " + "once from the durable consumer its listener relays to it, also one that was away or restarted. " + "Team and other ad-hoc topics are live only.";
 var TOPIC_GUIDE = "Topic guide (all are under notifications.): agent.<session_id> (subscribe: own inbox); role.<role> " + "(publish-to; holders claim via envoy_role_set). > matches one or more trailing tokens and does not " + "match the base subject. Envoy registers the concrete base when you subscribe to <subject>.>, so " + "the recommended default remains github.<owner>.<repo>.pr.<n>.>. <owner> and <repo> are one token " + "each, with every dot in the name written _ (sjawhar/.github is github.sjawhar._github; " + "acme/site.io is github.acme.site_io), and a topic spelled with the dot receives nothing. " + "Default PR subscription: " + "github.<owner>.<repo>.pr.<n>.> (it receives the quiet PR family): pr.<n> (lifecycle: " + "opened/synchronize/closed; closed carries merged, merge_commit_sha, merged_by, head_sha), " + "pr.<n>.comment, pr.<n>.review, pr.<n>.mention, pr.<n>.checks (one settlement event per commit whose checks settle, the head or not, naming its sha: " + 'passed/failed/cancelled/skipped with failing names and URLs; re-fires with superseded_settlement: "true" ' + "when new runs appear for the same commit). Other GitHub: issue.<n>, issue.<n>.comment, " + "issue.<n>.mention, mention, push.branch.<name>, push.tag.<name>, workflow.<file>.<action> (only " + "runs without an associated PR); slack.<team>.<channel>.message|mention and " + "slack.<team>.<channel>.thread.<ts>.message|mention; ghostwispr.<session>.<kind>; " + "whatsapp.<phone>.<jid>.<kind>; envoy.exceptions.<original-topic>.";
 var URGENCY_VALUES = EnvelopeSchema.shape.urgency.unwrap().options;
-var EXPECTS_REPLY_VALUES = EnvelopeSchema.shape.expects_reply.unwrap().options;
 function messageMetadataShape(schema) {
   return {
     in_reply_to: schema.string().optional(),
     supersedes: schema.string().optional(),
     urgency: schema.enum(URGENCY_VALUES).describe("low | med | high | blocking: how soon the recipient should act, shown on its card. It does not deliver the message sooner or ahead of others.").optional(),
-    expects_reply: schema.enum(EXPECTS_REPLY_VALUES).describe("none | optional | required").optional(),
+    expects_reply: schema.literal(EXPECTS_REPLY_VALUES).describe("false | optional | required").optional(),
     expires_at: schema.number({ int: true }).optional()
   };
 }
@@ -55179,7 +55211,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
 
 // package.json
 var name = "@sjawhar/claude-envoy";
-var version2 = "1.14.1";
+var version2 = "1.16.0";
 var legion = {
   daemonApiVersion: 56
 };
@@ -55868,7 +55900,11 @@ async function pruneStaleSessionTitles(stateDirectory) {
 }
 
 // src/session-identity.ts
-var PersistedRole = object({ session_id: string2().min(1), role: string2().min(1) });
+var PersistedRole = object({
+  session_id: string2().min(1),
+  role: string2().min(1),
+  client_instance_id: string2().min(1).optional()
+});
 
 class SessionIdentity {
   directory;
@@ -56111,9 +56147,13 @@ async function waitForSavedTranscript(transcript, signal, pollMs = 100) {
 function isFile(file) {
   return stat2(file).then((info) => info.isFile(), () => false);
 }
+var ROLE_CLAIM_RETRY_MS = 1e4;
+var ROLE_CLAIM_WAIT_MS = SESSION_LIVE_WINDOW_MS + ROLE_CLAIM_RETRY_MS;
 function startLegionClaim(deps) {
   let capability;
   const { sessionID } = deps;
+  const roleWaitMs = deps.roleWaitMs ?? ROLE_CLAIM_WAIT_MS;
+  const roleRetryMs = deps.roleRetryMs ?? ROLE_CLAIM_RETRY_MS;
   const boot = async () => {
     const transcript = await waitForTranscript(deps.pane.configDir, sessionID, deps.signal, deps.pollMs);
     if (deps.pane.launcherSaves) {
@@ -56132,16 +56172,39 @@ function startLegionClaim(deps) {
         capability = registered;
       },
       claimRole: async (role) => {
-        const claimed = await deps.client.setRole({ sessionID, role, soft: true });
-        if (!claimed.claimed) {
-          throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`);
+        const deadline = Date.now() + roleWaitMs;
+        let waited = false;
+        for (;; ) {
+          const claimed = await deps.client.setRole({
+            sessionID,
+            role,
+            soft: true,
+            clientInstanceID: deps.clientInstanceID
+          });
+          if (claimed.claimed)
+            break;
+          if (claimed.holder !== sessionID) {
+            throw new Error(`Envoy role ${role} is held by live session ${claimed.holder}`);
+          }
+          const left = deadline - Date.now();
+          if (left <= 0) {
+            throw new Error(`Envoy role ${role} is still claimed under this session by another process after ${roleWaitMs} ms of asking`);
+          }
+          if (!waited) {
+            waited = true;
+            deps.log(`Envoy role ${role} is claimed under this session by the process this pane replaced; asking again every ${roleRetryMs} ms for up to ${roleWaitMs} ms, until nobody has answered for that claim inside the listener's live window`);
+          }
+          await delay(Math.min(roleRetryMs, left), undefined, { signal: deps.signal });
         }
         await deps.session.rememberRole(role);
       },
       onRoleRegained: (listener) => deps.session.onRoleRegained(listener),
       log: deps.log,
       stopping: "stopping the pane so the daemon launches it again",
-      stop: deps.stop
+      stop: () => {
+        if (!deps.signal.aborted)
+          deps.stop();
+      }
     });
   };
   const booted = boot().catch((error) => {
@@ -57511,7 +57574,7 @@ function createChannelDelivery(input) {
           dedupe_key: envelope?.dedupe_key,
           urgency: envelope?.urgency,
           from_session: envelope?.source_session,
-          expects_reply: envelope?.expects_reply,
+          expects_reply: envelope?.expects_reply?.toString(),
           in_reply_to: envelope?.in_reply_to
         })
       }
@@ -57849,7 +57912,11 @@ async function startChannelSession(options) {
       relay.delivery.setFollowed(registeredTopics());
     return {
       dropping,
-      unsubscribing: serialized(() => options.client.unsubscribe({ sessionID: identity.id, topics }))
+      unsubscribing: serialized(() => options.client.unsubscribe({
+        sessionID: identity.id,
+        topics,
+        clientInstanceID: options.clientInstanceID
+      }))
     };
   }
   function registeredTopics() {
@@ -57902,27 +57969,40 @@ async function startChannelSession(options) {
     const result = await registering;
     takeDeliveryAnswer(sessionID, topics, asking, result);
   };
-  const restoreRole = async (previousSessionID = identity.id) => {
+  const writeRoleRecord = (file, role) => writePersistedRole(file, {
+    session_id: identity.id,
+    role,
+    client_instance_id: options.clientInstanceID
+  });
+  let roleTransferFrom;
+  const restoreRole = async (previousSessionID) => {
     const previousFile = roleStateFile(options.stateDirectory, previousSessionID);
     const persisted = await readPersistedRole(previousFile);
     if (persisted === undefined)
-      return;
+      return "settled";
+    if (!mayActOnRoleRecord(persisted.client_instance_id, options.clientInstanceID, heldRole !== undefined)) {
+      return "settled";
+    }
     const claim = await options.client.setRole({
       sessionID: identity.id,
       role: persisted.role,
       soft: true,
-      previousSessionID: persisted.session_id
+      previousSessionID: persisted.session_id,
+      clientInstanceID: options.clientInstanceID
     });
     if (!claim.claimed) {
+      if (claim.holder === identity.id)
+        return "pending";
       if (claim.holder !== persisted.session_id)
         await rm2(previousFile, { force: true });
-      return;
+      return "settled";
     }
     heldRole = persisted.role;
     const currentFile = roleStateFile(options.stateDirectory, identity.id);
     if (previousFile !== currentFile)
       await rm2(previousFile, { force: true });
-    await writePersistedRole(currentFile, { session_id: identity.id, role: persisted.role });
+    await writeRoleRecord(currentFile, persisted.role);
+    return "settled";
   };
   let regained;
   const fireRegained = (role, reason) => {
@@ -57952,8 +58032,8 @@ async function startChannelSession(options) {
     if (heldRole === undefined)
       return;
     const role = heldRole;
-    const holder = await options.client.getRole(role).then((info) => info.holder, undefinedOnNotFound);
-    if (holder === identity.id) {
+    const holding = await options.client.getRole(role).catch(undefinedOnNotFound);
+    if (roleHeldBy(holding, identity.id, options.clientInstanceID)) {
       await refreshRoleRecord();
       if (afterOutage)
         fireRegained(role, "reregistered");
@@ -57962,24 +58042,27 @@ async function startChannelSession(options) {
     const result = await options.client.setRole({
       sessionID: identity.id,
       role,
-      soft: true
+      soft: true,
+      clientInstanceID: options.clientInstanceID
     });
     if (!result.claimed) {
-      heldRole = undefined;
-      await rm2(roleStateFile(options.stateDirectory, identity.id), { force: true });
+      if (result.holder !== identity.id) {
+        heldRole = undefined;
+        await rm2(roleStateFile(options.stateDirectory, identity.id), { force: true });
+        return;
+      }
+      await refreshRoleRecord();
       return;
     }
     fireRegained(role, "reclaimed");
   };
-  let roleTransferFrom;
   let roleTransferFailureReported = false;
   const transferRole = async () => {
     const from = roleTransferFrom;
     if (from === undefined)
       return;
     try {
-      await restoreRole(from);
-      roleTransferFrom = undefined;
+      roleTransferFrom = await restoreRole(from) === "pending" ? from : undefined;
       roleTransferFailureReported = false;
     } catch (error) {
       if (!roleTransferFailureReported) {
@@ -58044,7 +58127,11 @@ async function startChannelSession(options) {
     const drifted = registry.topics.filter((topic) => topic !== directSubject && !topic.startsWith(ROLE_TOPIC_PREFIX) && !followed.has(topic));
     if (drifted.length === 0)
       return;
-    await options.client.unsubscribe({ sessionID: identity.id, topics: drifted });
+    await options.client.unsubscribe({
+      sessionID: identity.id,
+      topics: drifted,
+      clientInstanceID: options.clientInstanceID
+    });
   };
   let heartbeatInFlight = false;
   let heartbeatRequested = false;
@@ -58133,17 +58220,19 @@ async function startChannelSession(options) {
   await options.connection.flush();
   await serialized(async () => {
     await register();
-    await restoreRole().catch((error) => {
+    try {
+      roleTransferFrom = await restoreRole(identity.id) === "pending" ? identity.id : undefined;
+    } catch (error) {
       if (error instanceof UnparseableRoleRecordError) {
         process.stderr.write(`envoy-channel: ${messageFor(error)}; the session starts without a role
 `);
-        return;
-      }
-      roleTransferFrom = identity.id;
-      roleTransferFailureReported = true;
-      process.stderr.write(`envoy-channel: could not restore the role (${messageFor(error)}); the next heartbeat retries
+      } else {
+        roleTransferFrom = identity.id;
+        roleTransferFailureReported = true;
+        process.stderr.write(`envoy-channel: could not restore the role (${messageFor(error)}); the next heartbeat retries
 `);
-    });
+      }
+    }
   });
   triggerReplay();
   for (const prune of [
@@ -58218,10 +58307,7 @@ async function startChannelSession(options) {
     },
     async rememberRole(role) {
       heldRole = role;
-      await writePersistedRole(roleStateFile(options.stateDirectory, identity.id), {
-        session_id: identity.id,
-        role
-      });
+      await writeRoleRecord(roleStateFile(options.stateDirectory, identity.id), role);
     },
     async shutdown() {
       if (shuttingDown)
@@ -58320,7 +58406,11 @@ async function executeEnvoyTool(runtime, name, input) {
     }
     case EnvoyToolOperation.setRole: {
       const args = parseArguments(spec, input);
-      const result = await runtime.client.setRole({ sessionID: identity.id, role: args.role });
+      const result = await runtime.client.setRole({
+        sessionID: identity.id,
+        role: args.role,
+        clientInstanceID: runtime.clientInstanceID
+      });
       if (!result.claimed)
         throw new Error(`role ${args.role} is held by ${result.holder}`);
       await runtime.session.rememberRole(args.role);
@@ -58534,13 +58624,14 @@ async function runEnvoyChannelServer() {
         ...configuredValue(overrideSessionId) === undefined ? { handoffPid: process.ppid } : {}
       });
     }
-    runtime = { identity, client, session };
+    runtime = { identity, client, session, clientInstanceID };
     if (pane !== undefined && daemon !== undefined && !stopping) {
       claim = startLegionClaim({
         pane,
         sessionID: identity.id,
         daemon,
         client,
+        clientInstanceID,
         session,
         signal: booting.signal,
         log: logLegion,

package/dist/session-hook.js

@@ -14438,7 +14438,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_message",
     example: { issue: "DSP-1", body: "Implementation started." },
-    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A BTW, Aside or Steer " + "frame carries a reply_with command: answer with it, on that issue. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
+    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch read --message <id> reads " + "that conversation back. " + "Every other message names its issue; keep --issue whenever the frame you answer gave one. A frame reading expects_reply: optional or " + "required carries a reply_with command: answer with it, on that issue. One reading false carries none and asks for no answer; where " + "you answer one anyway, its card names what to answer. On Oh My Pi an Agents-page Send or Aside " + "arrives as a user message: answer in the conversation, with no dispatch message. " + `${BODY_BLOCK_RULE} The lines images appends count toward it. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
       body: z.string().describe(`Update text. ${BODY_BLOCK_RULE}`),
@@ -15765,6 +15765,7 @@ var DISPATCH_TEXT_REFERENCES = [
 ];
 // ../contracts/src/envelope.ts
 var isSubject = (value) => typeof value === "string" && value.length > 0;
+var EXPECTS_REPLY_VALUES = [false, "optional", "required"];
 var EnvelopeSchema = object({
   event_id: string2().min(1),
   source: _enum2([
@@ -15798,7 +15799,7 @@ var EnvelopeSchema = object({
   in_reply_to: string2().min(1).optional(),
   supersedes: string2().min(1).optional(),
   urgency: _enum2(["low", "med", "high", "blocking"]).optional(),
-  expects_reply: _enum2(["none", "optional", "required"]).optional()
+  expects_reply: literal(EXPECTS_REPLY_VALUES).optional()
 });
 var MINTED_DEDUPE_KEY_PATTERN = "^(?:envoy\\.role\\.forward\\.)?(?:publish|agent\\.[^.]+)\\.(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$";
 var mintedDedupeKey = new RegExp(MINTED_DEDUPE_KEY_PATTERN);
@@ -15819,6 +15820,7 @@ function dedupeKeyNamesItsEvent(envelope) {
 }
 // ../contracts/src/envoy-session.ts
 var SESSION_HEARTBEAT_MS = 90000;
+var SESSION_LIVE_WINDOW_MS = 300000;
 var LISTENER_CALL_TIMEOUT_MS = 5000;
 var LISTENER_CALL_RETRY_DELAY_MS = 250;
 var LISTENER_CALL_ATTEMPTS = 2;
@@ -15936,6 +15938,12 @@ var SLACK_POST_TEXT_MAX = 4000;
 function overCapMessage(length, max) {
   return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
 }
+function literalOfSet(api, values) {
+  const node = api.literal?.(values);
+  if (node === undefined || typeof node.safeParse !== "function")
+    return;
+  return values.every((value) => node.safeParse(value).success) ? node : undefined;
+}
 function zodSchemaApi(zod) {
   const api = zod;
   return {
@@ -15964,6 +15972,7 @@ function zodSchemaApi(zod) {
     },
     boolean: () => api.boolean(),
     enum: (values) => api.enum(values),
+    literal: (values) => literalOfSet(api, values) ?? api.unknown(),
     unknown: () => api.unknown(),
     array: (item, opts = {}) => {
       let schema = api.array(item);
@@ -18333,6 +18342,7 @@ var InboundSenderSchema = object({
   title: string2().optional(),
   roles: array(string2()).optional()
 });
+var InboundExpectsReplySchema = literal([...EXPECTS_REPLY_VALUES, "none"]).transform((value) => value === "none" ? false : value);
 var InboundEnvelopeSchema = object({
   event_id: string2().optional(),
   source: string2(),
@@ -18349,7 +18359,7 @@ var InboundEnvelopeSchema = object({
   in_reply_to: string2().optional(),
   supersedes: string2().optional(),
   urgency: string2().optional(),
-  expects_reply: string2().optional()
+  expects_reply: InboundExpectsReplySchema.optional()
 }).passthrough();
 function tolerantShape(shape) {
   return Object.fromEntries(Object.entries(shape).map(([key, schema]) => [key, _catch2(schema, undefined)]));
@@ -19056,7 +19066,8 @@ function renderInbound(raw, sessionID, subject, wholeBody) {
       break;
   }
   const role = envelope.sender?.roles?.[0];
-  const reply = dispatchReply ?? replyWith(envelope);
+  const wantsNoReply = envelope.expects_reply === false;
+  const reply = wantsNoReply ? undefined : dispatchReply ?? replyWith(envelope);
   const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
   const unrecognised = [
     ...parseIssues,
@@ -19075,7 +19086,7 @@ function renderInbound(raw, sessionID, subject, wholeBody) {
     ...inReplyTo === undefined ? {} : { re: inReplyTo },
     ...envelope.supersedes === undefined ? {} : { supersedes: envelope.supersedes },
     ...reply === undefined ? {} : { reply_with: reply },
-    ...role === undefined ? {} : {
+    ...role === undefined || wantsNoReply ? {} : {
       reply_role: {
         tool: "envoy_publish",
         args: { topic: `notifications.role.${role}`, message: "..." }
@@ -26862,7 +26873,11 @@ async function pruneStaleSessionTitles(stateDirectory) {
 }
 
 // src/session-identity.ts
-var PersistedRole = object({ session_id: string2().min(1), role: string2().min(1) });
+var PersistedRole = object({
+  session_id: string2().min(1),
+  role: string2().min(1),
+  client_instance_id: string2().min(1).optional()
+});
 
 class SessionIdentity {
   directory;

package/legion/agents/design-outsider.md

@@ -0,0 +1,44 @@
+---
+name: design-outsider
+description: |
+  Outside reader of a design problem. Reads no file of the repository. Use before you write a
+  design: it says where the proposal is stupid, whether the thing should exist at all, what the
+  smallest thing that gives the person what they asked for is, and what to delete.
+tools: WebSearch
+color: magenta
+---
+
+You are an outsider to this codebase. The caller gives you a problem statement and the
+repository's design principles, and nothing else. You answer the problem, not the caller.
+
+## What you answer
+
+Four questions, in this order, each in your own words:
+
+1. Where is the proposal stupid?
+2. Should the thing in question exist at all?
+3. What is the smallest thing that gives the person what they asked for?
+4. What should be deleted?
+
+## How you answer
+
+- Answer from the problem statement and the principles the caller gave you. Say plainly what
+  you cannot judge from them, and name what you would need to judge it.
+- Where a standard solution to this problem exists, name it. A web search for how two or three
+  well-regarded projects solve the same problem is the one source you can read.
+- Do not agree. A reply that gives the caller's own design back to it is worth nothing, and a
+  verdict with no reasoning behind it is worth less.
+- You are a challenge, never a gate and never an approval. The caller answers you in writing,
+  and it may decide against you and give its reason. You decide nothing and you block nothing.
+
+## What your tool list does not prevent
+
+You hold no tool that reads a file, by design: your value is that you read the problem instead
+of the code that already exists. Two things still reach you, so do not claim otherwise:
+
+- A plugin device of the pod stays available, so an indexed workspace can still be read through
+  one.
+- A subagent inherits the caller's repository guide, which in this repository imports the whole
+  of `AGENTS.md`. So you may already hold that guide and the design principles in it.
+
+Where you used either, say so in your answer.

package/legion/skills/legion-architect/SKILL.md

@@ -16,7 +16,7 @@ You own one issue tree from its first decision to the merge that closes it. The
 - Before you end a turn that waits on a human, open what they must answer: a decision block, a `dispatch ask` or `dispatch request-approval`. A turn that ends with nothing open asks nobody, and the tree stops. Open an ordinary ask on the root issue itself, never a child: only a question a session of this tree opens on the root starts a wait on a person, so an ask on a child starts no wait and leaves the tree standing still. Once you have handed a root question to the human, end your turn: when nothing else of the tree is at work — no other issue of the tree in a phase, the `legion` label still on, and no person or outside session holding the root's Dispatch claim — the root returns its admission slot (`awaiting_person`) while this session stays live. Read the human's comments and replies as they arrive. Their answer gives this live claim a task naming what answered and what is still with them. The same holds once you request approval and `register_gate` that version: the registration hands the spec to the human, so end your turn there too, and the human's review, or a newer version once Dispatch shows the request back on your turn, gives you that task.
 - Deliver every criterion of the root spec in this tree. Work leaves it only when a root splits, as a `dispatch ask` for the rest: work outside has no owner.
 - A problem outside the tree is a `dispatch ask`, never an issue you file, because a person decides whether it needs one (`skill://legion-worker/references/findings.md`). A clear defect is the exception. Fix one in code this tree touches or depends on in this tree's pull request. Send any other to the controller, which gives it to the tree that owns that code.
-- Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one, then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in that file goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
+- Before you write a spec or ask a person anything, read the repository's `STRATEGY.md` when it has one and the design principles where it states them (`AGENTS.md`, in this repository), then use a standard best-practice solution; ask only what neither settles, with one recommendation. A design that crosses a Boundary in `STRATEGY.md` goes to its owner before it is built. Find the standard with a web search and with how two or three well-regarded projects solve the problem. Cite them in a few lines of the spec's `Design`. A design far from the standard is a sign to fix the underlying problem, not to add a workaround.
 - Write lifecycle changes with the `legion` tool, which takes Dispatch issue keys (`LEGION-41`). Never apply a label: Legion has none.
 - Message a phase worker with `envoy_publish` to `notifications.role.<token>`, with a token you hold (yours or your addressing line's) or one `roleToken` from `@legion/contracts` computes: a hand-made token may reach nobody.
 - Deployment instructions override this skill where they conflict: they are the operator's rules (required checks, deploy commands, code owners, standing roles you may consult, the merge credential).
@@ -31,6 +31,7 @@ You own one issue tree from its first decision to the merge that closes it. The
 - A child that duplicates another issue and is not yet released is never released: fold it by the duplicate rule of `skill://dispatch-first`. The daemon records a child at its release and re-asserts a status only on an issue it has recorded, so that close stands. A released duplicate goes out with `park_child` instead.
 - Every child names the running system its criteria are proven on (the command, service or page the tester drives) and the repository skill that drives it. If the repository cannot exercise a criterion end to end, building that path is work of this tree.
 - The issue's primary document is the root spec: extend it in place, because a second "spec" artifact replaces the human's document. Mark each requirement of it as a `requirement` block, and write the issue's Verification document (`verification.md`) beside it: one `check` block per thing that must be proved, each with `serves` naming the requirements it serves, its `surface` (`browser`, `cli` or `api`), its `run`, its `when` (`before_merge`, `after_merge` or `default_branch`) and its `negative_control`. The checks are the gate every later role reads: the implementer and the tester record a result against each, and the reviewer approves only once every `before_merge` check of the issue has a passing result current at the head. The decomposition's order and the plan's tasks go in the children and the planner's `plan` handoff, not the root spec.
+- Before you write a design, state the problem to `task(agent="design-outsider")` and read its answer with `wait`. The brief holds the problem statement and the design principles, and no design of your own. The four questions are where the proposal is stupid, whether the thing in question should exist at all, what the smallest thing that gives the person what they asked for is, and what to delete. Record the answer in a comment on the issue, or in the issue's `plan.md` where one exists, before any action that states or favours a design, and give your reason where you do not follow it. Run the step once per design: at the first design of an issue, and again when a push-back or a review changes what the design is for. It is a challenge, never a gate.
 - Read `skill://legion-architect/references/design-gate.md` before you write the root spec and before any edit to it after approval, because any new version closes the gate. It also names the design gate steps your `Legion addressing` line declares, the document each step records, and says that a sub-architect runs none.
 - File every child of your decomposition before `dispatch request-approval`, and before `register_gate` where your line gates no step: the gate's opening starts your root's own first phase unless Dispatch shows an open child under it, so a child filed after it opens leaves the root working beside its children.
 - A root architect then ends its turn and releases no child until every gated step is open: a delivered wake shows `design-approved` on the root, and under more than one step `gatedSteps` in your record (the `legion` tool's `read_record`) shows each step `approved`. The daemon starts no phase in the tree before that. A root that waited on a person's answer gets no `design-approved` notice: a resume task saying "this resume is your design-approved wake" is that wake. A sub-architect waits for none and releases its children with `release_children`.

package/legion/skills/legion-architect/references/wake-routing.md

@@ -36,7 +36,7 @@ and 7 (a conflict, the hand-over, the close) is in
 | `merge-stalled` | GitHub shows the pull request closed, or at another head, while the record still awaits READY's head, and that change's webhook never reached the daemon: read the pull request on GitHub and act on what it shows (`skill://legion-architect/references/merge-notices.md#merge-stalled`). |
 | `merge-removed` | A person, or GitHub on its own, took the pull request out of the merge queue or turned its auto-merge off at READY's head after the daemon submitted the merge: read the pull request on GitHub and act on the removal's reason (`skill://legion-architect/references/merge-notices.md#merge-removed`). |
 | `merge-waiting` | GitHub has not completed the merge the daemon submitted within an hour of READY's acceptance, and nothing has been withdrawn: read the pull request on GitHub for what GitHub waits on and ask a person for what no worker can do (`skill://legion-architect/references/merge-notices.md#merge-waiting`). |
-| A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
+| A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused) where the reply carries a question, a disagreement, a correction or a fact you do not have, and whenever you are unsure; an approval, or an answer that settles the question with nothing left to say, draws no comment and no message back to the person who answered. Then adjust the plan or relay the reply via `envoy_publish` to the responsible worker's role token, which an answer needing nothing from you still needs; scope and product decisions remain with you. |
 | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. |
 | `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the `worker-died` that comes with it is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, and you start nothing for it. |
 | `ready-refused` | Its `version` and `reason`, and the `reason` names the gated step the READY waits on. The merger's READY was refused, and its packet is kept with the completion so no second READY is ever needed. With `version` greater than 0, `reason` reads `READY refused: approve design version <N> of the tree's <step> document before requesting READY.`: that step's document is already registered at that version, so get it approved (`skill://legion-architect/references/design-gate.md`), and the daemon advances the merge and posts the kept packet the moment every gated step is open. With `version` 0, `reason` reads `READY refused: no design version of the tree's <step> document is approved; register and approve it before requesting READY.`: that step is not registered yet, so register it and get it approved (`skill://legion-architect/references/design-gate.md`) exactly as above; the daemon releases the kept packet the same way — at registration itself when that opens the step (a deployment that gates no step, or Dispatch already shows the version approved), otherwise the moment a human approves the version you registered. The refusal names the first closed step, in the order the deployment gates them, and no second READY is asked for however many steps were closed: read `gatedSteps` in your own record (the `legion` tool's `read_record`) for every step still closed, and open each one. Nothing else is needed once every gated step is open. On a root whose catch-up said `carried`, the gate is a copy on the old root's spec document: run nothing of `skill://legion-architect/references/design-gate.md` for that step; tell the controller the READY waits on a human's approval of that document, and `carried-gate-opened` follows the approval. A `reason` starting `READY_PACKET_MISSING` names a READY refused before the daemon kept packets: that READY is void and the issue stays in merging, so start it over (`park_child` then `rerun_child`, for a child) or end it. |