@sjawhar/pi-legion-envoy 1.27.0 → 1.27.2

package/dist/envoy.js

@@ -29883,7 +29883,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
-      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
+      ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
@@ -32015,6 +32015,19 @@ function askKind(args) {
     return value;
   throw new Error("kind must be action");
 }
+function askQuestionWithRef(args) {
+  const question = stringArg(args, "question");
+  const ref = optionalString(args, "ref");
+  if (ref === undefined || question.includes(ref))
+    return question;
+  const withRef = `${question}
+
+Ref: ${ref}`;
+  if (withRef.length > 800) {
+    throw new Error("question plus ref must be at most 800 characters");
+  }
+  return withRef;
+}
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
   if (projectDocument) {
@@ -32097,6 +32110,9 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
   if (issueFreeTools[tool] === true)
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
+  if (tool === "dispatch_ask" && typeof refArgument === "string" && !refArgument.startsWith("dispatch://")) {
+    throw new Error("ref must be a dispatch:// reference");
+  }
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
     throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename)");
   })() : null;
@@ -32386,12 +32402,23 @@ async function executeDispatchTool(input) {
   if (!input.config.enabled || !configUrl || !configToken) {
     throw new Error("Dispatch is disabled; resolve both DISPATCH_URL and DISPATCH_TOKEN");
   }
+  const baseFetch = input.fetchImpl ?? fetch;
+  const fetchImpl = Object.assign(async (...args) => {
+    try {
+      return await baseFetch(...args);
+    } catch (error) {
+      if (error instanceof TypeError) {
+        throw new Error(`Dispatch at ${configUrl} is unreachable: ${error.message}. If the Dispatch URL changed, restart this agent process so it picks up the new configuration.`);
+      }
+      throw error;
+    }
+  }, { preconnect: baseFetch.preconnect });
   if (input.tool === "dispatch_open_asks") {
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_open_asks");
     toolSchema(input.tool).parse(input.args);
-    const client = new DispatchClient(configUrl, configToken, input.fetchImpl, input.signal);
+    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
@@ -32400,7 +32427,7 @@ async function executeDispatchTool(input) {
   const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec);
   const args = toolSchema(input.tool).parse(ownerArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
-  const client = new DispatchClient(configUrl, configToken, input.fetchImpl, input.signal);
+  const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
@@ -32506,7 +32533,7 @@ async function executeDispatchTool(input) {
       const kind = askKind(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
       const askInput = {
-        question: stringArg(args, "question"),
+        question: askQuestionWithRef(args),
         ...kind === undefined ? {} : { kind },
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },
@@ -33239,59 +33266,7 @@ async function copySessionID(copyToClipboard, sessionID) {
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
-var ASK_AWARENESS_ENTRY = "dispatch-ask-awareness";
-var LEGION_MANAGED_ENTRY = "legion-managed-session";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
-var OPEN_ASKS_REMINDER = "You have no unanswered asks in Dispatch. If you are waiting for human input, open an ask. Otherwise ignore this reminder and continue with any remaining work. Do not reply just to acknowledge this reminder.";
-function isAskAwarenessEntry(entry) {
-  if (typeof entry !== "object" || entry === null)
-    return false;
-  if (!("type" in entry) || entry.type !== "custom")
-    return false;
-  if (!("customType" in entry) || entry.customType !== ASK_AWARENESS_ENTRY)
-    return false;
-  if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
-    return false;
-  const data = entry.data;
-  return "session_id" in data && typeof data.session_id === "string" && "period" in data && typeof data.period === "number" && "baseline_as_of" in data && (typeof data.baseline_as_of === "string" || data.baseline_as_of === null) && "checked" in data && typeof data.checked === "boolean" && "fired" in data && typeof data.fired === "boolean" && "saw_ask" in data && typeof data.saw_ask === "boolean";
-}
-function isLegionManagedEntry(entry) {
-  if (typeof entry !== "object" || entry === null)
-    return false;
-  if (!("type" in entry) || entry.type !== "custom")
-    return false;
-  if (!("customType" in entry) || entry.customType !== LEGION_MANAGED_ENTRY)
-    return false;
-  if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
-    return false;
-  return "session_id" in entry.data && typeof entry.data.session_id === "string";
-}
-function emptyAskAwareness(sessionID) {
-  return {
-    session_id: sessionID,
-    period: 0,
-    baseline_as_of: null,
-    checked: false,
-    fired: false,
-    saw_ask: false
-  };
-}
-function transcriptAskAwareness(branch, sessionID) {
-  let state;
-  for (const entry of branch) {
-    if (isAskAwarenessEntry(entry) && entry.data.session_id === sessionID)
-      state = entry.data;
-  }
-  return state;
-}
-function transcriptMarksLegionSession(branch, sessionID) {
-  return branch.some((entry) => isLegionManagedEntry(entry) && entry.data.session_id === sessionID);
-}
-function isHumanTurnInitiator(message) {
-  if (message.attribution !== "user")
-    return false;
-  return message.role === "user" || message.role === "custom" && (message.customType === "skill-prompt" || message.customType === "collab-prompt");
-}
 function isRoleClaimEntry(entry) {
   if (typeof entry !== "object" || entry === null)
     return false;
@@ -33311,15 +33286,13 @@ function legionRoleClaimBridge() {
   let bridge = store[LEGION_ROLE_CLAIM_BRIDGE];
   if (bridge === undefined) {
     const ready = Promise.withResolvers();
-    bridge = { ready, managedSessions: new Set };
+    bridge = { ready };
     store[LEGION_ROLE_CLAIM_BRIDGE] = bridge;
   }
   return bridge;
 }
 async function claimEnvoyRole(sessionID, role, context) {
   const bridge = legionRoleClaimBridge();
-  bridge.managedSessions.add(sessionID);
-  bridge.markManagedSession?.(sessionID, context);
   const claim = bridge.claim ?? await bridge.ready.promise;
   await claim(sessionID, role, context);
 }
@@ -33368,87 +33341,26 @@ function envoyExtension(pi) {
   let claimedRoleTopic;
   let activeSessionContext;
   const inbox = [];
-  let askAwareness = emptyAskAwareness("");
-  let candidateBaseline;
-  let awarenessGeneration = 0;
-  let availabilityWarningPeriod;
-  let agentRunning = false;
-  let agentWillContinue = false;
-  let legionManagedSessionID = "";
-  let terminalInputUnsubscribe;
-  const persistAskAwareness = (state) => {
-    askAwareness = state;
-    pi.appendEntry(ASK_AWARENESS_ENTRY, state);
-  };
+  const availabilityWarningSessionIDs = new Set;
   const warnAskAvailability = (context, error) => {
-    const key = `${askAwareness.session_id}:${askAwareness.period}`;
-    if (availabilityWarningPeriod === key)
+    const sessionID = context.sessionManager.getSessionId();
+    if (availabilityWarningSessionIDs.has(sessionID))
       return;
-    availabilityWarningPeriod = key;
-    context.ui.notify(`envoy: Dispatch open-ask check unavailable (${messageFor(error)}); reminder skipped`, "warning");
+    availabilityWarningSessionIDs.add(sessionID);
+    context.ui.notify(`envoy: Dispatch open-ask check unavailable (${messageFor(error)}); summary unavailable`, "warning");
   };
-  const queryOpenAsks = async (requestedSessionID, since, signal) => {
+  const queryOpenAsks = async (requestedSessionID) => {
     const config = activeDispatchConfig();
     if (config === null)
       return null;
-    const deadline = AbortSignal.timeout(OPEN_ASKS_TIMEOUT_MS);
-    const requestSignal = signal === undefined ? deadline : AbortSignal.any([signal, deadline]);
-    return new DispatchClient(config.url, config.token, fetch, requestSignal).openAsks(requestedSessionID, since);
-  };
-  const setReminderBaseline = (requestedSessionID, period, asOf) => {
-    candidateBaseline = { sessionID: requestedSessionID, asOf };
-    if (askAwareness.session_id !== requestedSessionID || askAwareness.period !== period || askAwareness.checked || askAwareness.fired || askAwareness.baseline_as_of !== null) {
-      return;
-    }
-    persistAskAwareness({ ...askAwareness, baseline_as_of: asOf });
-  };
-  const refreshReminderBaseline = async (requestedSessionID, period, context) => {
-    try {
-      const snapshot = await queryOpenAsks(requestedSessionID);
-      if (snapshot === null)
-        return;
-      setReminderBaseline(requestedSessionID, period, snapshot.as_of);
-    } catch (error) {
-      warnAskAvailability(context, error);
-    }
-  };
-  const armAskReminder = async (context, refreshBaseline = false) => {
-    const id = context.sessionManager.getSessionId();
-    if (id === "" || activeDispatchConfig() === null)
-      return;
-    awarenessGeneration++;
-    availabilityWarningPeriod = undefined;
-    const baseline = !agentRunning && !refreshBaseline && candidateBaseline !== undefined && candidateBaseline.sessionID === id ? candidateBaseline.asOf : null;
-    const previousPeriod = askAwareness.session_id === id ? askAwareness.period : 0;
-    persistAskAwareness({
-      session_id: id,
-      period: previousPeriod + 1,
-      baseline_as_of: baseline,
-      checked: false,
-      fired: false,
-      saw_ask: false
-    });
-    if (agentRunning || refreshBaseline) {
-      await refreshReminderBaseline(id, askAwareness.period, context);
-    }
-  };
-  const cancelPendingAskReminder = () => {
-    awarenessGeneration++;
-  };
-  const installTerminalInputCancellation = (context) => {
-    terminalInputUnsubscribe?.();
-    terminalInputUnsubscribe = context.ui.onTerminalInput(cancelPendingAskReminder);
+    const snapshot = await new DispatchClient(config.url, config.token, fetch, AbortSignal.timeout(OPEN_ASKS_TIMEOUT_MS)).openAsks(requestedSessionID);
+    availabilityWarningSessionIDs.delete(requestedSessionID);
+    return snapshot;
   };
   const restoreLocalSessionState = (context) => {
     sessionDirectory = context.cwd;
     sessionID = context.sessionManager.getSessionId();
     activeSessionContext = context;
-    candidateBaseline = undefined;
-    const branch = context.sessionManager.getBranch?.() ?? [];
-    askAwareness = transcriptAskAwareness(branch, sessionID) ?? emptyAskAwareness(sessionID);
-    const persistedLegionSession = transcriptMarksLegionSession(branch, sessionID);
-    const managed = persistedLegionSession || legionRoleClaimBridge().managedSessions.has(sessionID);
-    legionManagedSessionID = managed ? sessionID : "";
   };
   pi.on("resources_discover", async () => ({ skillPaths: [SKILLS_DIRECTORY] }));
   registerEnvoyMessageRenderer(pi);
@@ -33489,13 +33401,6 @@ function envoyExtension(pi) {
     const dedupeKey = rendered.envelope?.dedupe_key;
     const duplicate = dedupeKey !== undefined && dedupeKeys.has(dedupeKey);
     if (!duplicate && !rendered.skip) {
-      if (rendered.dispatchActor?.kind === "user" && activeSessionContext !== undefined) {
-        try {
-          await armAskReminder(activeSessionContext, true);
-        } catch (error) {
-          warnAskAvailability(activeSessionContext, error);
-        }
-      }
       const envelope = rendered.envelope;
       if (envelope !== undefined) {
         inbox.unshift({
@@ -33815,17 +33720,6 @@ function envoyExtension(pi) {
     return run;
   };
   const bridge = legionRoleClaimBridge();
-  bridge.markManagedSession = (targetSessionID, context) => {
-    bridge.managedSessions.add(targetSessionID);
-    if (targetSessionID !== sessionID)
-      return;
-    if (legionManagedSessionID === targetSessionID)
-      return;
-    legionManagedSessionID = targetSessionID;
-    if (context !== undefined || activeSessionContext !== undefined) {
-      pi.appendEntry(LEGION_MANAGED_ENTRY, { session_id: targetSessionID });
-    }
-  };
   const claim = async (targetSessionID, role, callerContext) => {
     const context = callerContext ?? activeSessionContext;
     if (context === undefined || context.sessionManager.getSessionId() !== targetSessionID) {
@@ -33839,7 +33733,6 @@ function envoyExtension(pi) {
   bridge.claim = claim;
   bridge.ready.resolve(claim);
   pi.on("session_start", async (_event, context) => {
-    installTerminalInputCancellation(context);
     const previousSessionID = sessionID;
     restoreLocalSessionState(context);
     if (dispatchConfig.error !== null) {
@@ -33875,7 +33768,6 @@ function envoyExtension(pi) {
     }
   });
   const rebind = async (reason, context) => {
-    installTerminalInputCancellation(context);
     const previousID = sessionID;
     restoreLocalSessionState(context);
     if (defaults.natsUrls.length === 0)
@@ -33925,8 +33817,6 @@ function envoyExtension(pi) {
       ]);
     } finally {
       clearTimeout(timer);
-      terminalInputUnsubscribe?.();
-      terminalInputUnsubscribe = undefined;
       connection = undefined;
       activeSessionContext = undefined;
       subscriptions.clear();
@@ -33980,7 +33870,6 @@ function envoyExtension(pi) {
       const snapshot = await queryOpenAsks(id);
       if (snapshot === null)
         return;
-      setReminderBaseline(id, askAwareness.session_id === id ? askAwareness.period : 0, snapshot.as_of);
       return {
         message: {
           customType: "dispatch-open-asks",
@@ -34002,60 +33891,7 @@ ${formatOpenAsksSummary(snapshot, currentDispatchConfig().url)}`,
       };
     }
   });
-  pi.on("agent_start", async () => {
-    agentRunning = true;
-    agentWillContinue = false;
-  });
-  pi.on("agent_end", async (event) => {
-    agentRunning = false;
-    agentWillContinue = event.willContinue === true;
-  });
-  pi.on("input", async () => {
-    cancelPendingAskReminder();
-  });
-  pi.on("message_start", async (event, context) => {
-    if (!isHumanTurnInitiator(event.message))
-      return;
-    try {
-      await armAskReminder(context);
-    } catch (error) {
-      warnAskAvailability(context, error);
-    }
-  });
-  pi.on("session_stop", async (event, context) => {
-    if (event.stop_hook_active || event.signal.aborted || shuttingDown || agentWillContinue || event.last_assistant_message?.role !== "assistant" || event.session_id !== sessionID || legionManagedSessionID === event.session_id || askAwareness.session_id !== event.session_id || askAwareness.period === 0 || askAwareness.checked || askAwareness.fired) {
-      return;
-    }
-    const baseline = askAwareness.baseline_as_of;
-    if (baseline === null)
-      return;
-    if (context.ui.getEditorText().trim() !== "")
-      return;
-    const claimed = { ...askAwareness, checked: true };
-    const generation = awarenessGeneration;
-    persistAskAwareness(claimed);
-    let snapshot;
-    try {
-      snapshot = await queryOpenAsks(event.session_id, baseline, event.signal);
-    } catch (error) {
-      if (!event.signal.aborted && generation === awarenessGeneration) {
-        warnAskAvailability(context, error);
-      }
-      return;
-    }
-    if (snapshot === null || event.signal.aborted || generation !== awarenessGeneration || shuttingDown || agentWillContinue || context.sessionManager.getSessionId() !== event.session_id || sessionID !== event.session_id || legionManagedSessionID === event.session_id || context.ui.getEditorText().trim() !== "" || askAwareness.session_id !== claimed.session_id || askAwareness.period !== claimed.period || !askAwareness.checked) {
-      return;
-    }
-    if (snapshot.count > 0 || snapshot.opened_since || askAwareness.saw_ask) {
-      return;
-    }
-    persistAskAwareness({ ...askAwareness, fired: true });
-    return { continue: true, additionalContext: OPEN_ASKS_REMINDER };
-  });
   pi.on("tool_result", async (event) => {
-    if (!event.isError && event.toolName === "dispatch_ask" && typeof event.details === "object" && event.details !== null && "ask" in event.details && typeof event.details.ask === "string" && askAwareness.session_id === sessionID && askAwareness.period > 0 && !askAwareness.saw_ask) {
-      persistAskAwareness({ ...askAwareness, saw_ask: true });
-    }
     if (event.isError)
       return;
     const topic = dispatchSubscriptionTopic(event.details);

package/dist/legion.js

@@ -29883,7 +29883,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
-      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
+      ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
@@ -32446,6 +32446,19 @@ function askKind(args) {
     return value;
   throw new Error("kind must be action");
 }
+function askQuestionWithRef(args) {
+  const question = stringArg(args, "question");
+  const ref = optionalString(args, "ref");
+  if (ref === undefined || question.includes(ref))
+    return question;
+  const withRef = `${question}
+
+Ref: ${ref}`;
+  if (withRef.length > 800) {
+    throw new Error("question plus ref must be at most 800 characters");
+  }
+  return withRef;
+}
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
   if (projectDocument) {
@@ -32528,6 +32541,9 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
   if (issueFreeTools[tool] === true)
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
+  if (tool === "dispatch_ask" && typeof refArgument === "string" && !refArgument.startsWith("dispatch://")) {
+    throw new Error("ref must be a dispatch:// reference");
+  }
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
     throw new Error("ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename)");
   })() : null;
@@ -32817,12 +32833,23 @@ async function executeDispatchTool(input) {
   if (!input.config.enabled || !configUrl || !configToken) {
     throw new Error("Dispatch is disabled; resolve both DISPATCH_URL and DISPATCH_TOKEN");
   }
+  const baseFetch = input.fetchImpl ?? fetch;
+  const fetchImpl = Object.assign(async (...args) => {
+    try {
+      return await baseFetch(...args);
+    } catch (error) {
+      if (error instanceof TypeError) {
+        throw new Error(`Dispatch at ${configUrl} is unreachable: ${error.message}. If the Dispatch URL changed, restart this agent process so it picks up the new configuration.`);
+      }
+      throw error;
+    }
+  }, { preconnect: baseFetch.preconnect });
   if (input.tool === "dispatch_open_asks") {
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch_open_asks");
     toolSchema(input.tool).parse(input.args);
-    const client = new DispatchClient(configUrl, configToken, input.fetchImpl, input.signal);
+    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
@@ -32831,7 +32858,7 @@ async function executeDispatchTool(input) {
   const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec);
   const args = toolSchema(input.tool).parse(ownerArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
-  const client = new DispatchClient(configUrl, configToken, input.fetchImpl, input.signal);
+  const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
   const owner = ownerArguments.owner?.kind === "issue" ? {
     kind: "issue",
     issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
@@ -32937,7 +32964,7 @@ async function executeDispatchTool(input) {
       const kind = askKind(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
       const askInput = {
-        question: stringArg(args, "question"),
+        question: askQuestionWithRef(args),
         ...kind === undefined ? {} : { kind },
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },
@@ -33662,59 +33689,7 @@ async function copySessionID(copyToClipboard, sessionID) {
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
-var ASK_AWARENESS_ENTRY = "dispatch-ask-awareness";
-var LEGION_MANAGED_ENTRY = "legion-managed-session";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
-var OPEN_ASKS_REMINDER = "You have no unanswered asks in Dispatch. If you are waiting for human input, open an ask. Otherwise ignore this reminder and continue with any remaining work. Do not reply just to acknowledge this reminder.";
-function isAskAwarenessEntry(entry) {
-  if (typeof entry !== "object" || entry === null)
-    return false;
-  if (!("type" in entry) || entry.type !== "custom")
-    return false;
-  if (!("customType" in entry) || entry.customType !== ASK_AWARENESS_ENTRY)
-    return false;
-  if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
-    return false;
-  const data = entry.data;
-  return "session_id" in data && typeof data.session_id === "string" && "period" in data && typeof data.period === "number" && "baseline_as_of" in data && (typeof data.baseline_as_of === "string" || data.baseline_as_of === null) && "checked" in data && typeof data.checked === "boolean" && "fired" in data && typeof data.fired === "boolean" && "saw_ask" in data && typeof data.saw_ask === "boolean";
-}
-function isLegionManagedEntry(entry) {
-  if (typeof entry !== "object" || entry === null)
-    return false;
-  if (!("type" in entry) || entry.type !== "custom")
-    return false;
-  if (!("customType" in entry) || entry.customType !== LEGION_MANAGED_ENTRY)
-    return false;
-  if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
-    return false;
-  return "session_id" in entry.data && typeof entry.data.session_id === "string";
-}
-function emptyAskAwareness(sessionID) {
-  return {
-    session_id: sessionID,
-    period: 0,
-    baseline_as_of: null,
-    checked: false,
-    fired: false,
-    saw_ask: false
-  };
-}
-function transcriptAskAwareness(branch, sessionID) {
-  let state;
-  for (const entry of branch) {
-    if (isAskAwarenessEntry(entry) && entry.data.session_id === sessionID)
-      state = entry.data;
-  }
-  return state;
-}
-function transcriptMarksLegionSession(branch, sessionID) {
-  return branch.some((entry) => isLegionManagedEntry(entry) && entry.data.session_id === sessionID);
-}
-function isHumanTurnInitiator(message) {
-  if (message.attribution !== "user")
-    return false;
-  return message.role === "user" || message.role === "custom" && (message.customType === "skill-prompt" || message.customType === "collab-prompt");
-}
 function isRoleClaimEntry(entry) {
   if (typeof entry !== "object" || entry === null)
     return false;
@@ -33734,15 +33709,13 @@ function legionRoleClaimBridge() {
   let bridge = store[LEGION_ROLE_CLAIM_BRIDGE];
   if (bridge === undefined) {
     const ready = Promise.withResolvers();
-    bridge = { ready, managedSessions: new Set };
+    bridge = { ready };
     store[LEGION_ROLE_CLAIM_BRIDGE] = bridge;
   }
   return bridge;
 }
 async function claimEnvoyRole(sessionID, role, context) {
   const bridge = legionRoleClaimBridge();
-  bridge.managedSessions.add(sessionID);
-  bridge.markManagedSession?.(sessionID, context);
   const claim = bridge.claim ?? await bridge.ready.promise;
   await claim(sessionID, role, context);
 }
@@ -33791,87 +33764,26 @@ function envoyExtension(pi) {
   let claimedRoleTopic;
   let activeSessionContext;
   const inbox = [];
-  let askAwareness = emptyAskAwareness("");
-  let candidateBaseline;
-  let awarenessGeneration = 0;
-  let availabilityWarningPeriod;
-  let agentRunning = false;
-  let agentWillContinue = false;
-  let legionManagedSessionID = "";
-  let terminalInputUnsubscribe;
-  const persistAskAwareness = (state) => {
-    askAwareness = state;
-    pi.appendEntry(ASK_AWARENESS_ENTRY, state);
-  };
+  const availabilityWarningSessionIDs = new Set;
   const warnAskAvailability = (context, error) => {
-    const key = `${askAwareness.session_id}:${askAwareness.period}`;
-    if (availabilityWarningPeriod === key)
+    const sessionID = context.sessionManager.getSessionId();
+    if (availabilityWarningSessionIDs.has(sessionID))
       return;
-    availabilityWarningPeriod = key;
-    context.ui.notify(`envoy: Dispatch open-ask check unavailable (${messageFor(error)}); reminder skipped`, "warning");
+    availabilityWarningSessionIDs.add(sessionID);
+    context.ui.notify(`envoy: Dispatch open-ask check unavailable (${messageFor(error)}); summary unavailable`, "warning");
   };
-  const queryOpenAsks = async (requestedSessionID, since, signal) => {
+  const queryOpenAsks = async (requestedSessionID) => {
     const config = activeDispatchConfig();
     if (config === null)
       return null;
-    const deadline = AbortSignal.timeout(OPEN_ASKS_TIMEOUT_MS);
-    const requestSignal = signal === undefined ? deadline : AbortSignal.any([signal, deadline]);
-    return new DispatchClient(config.url, config.token, fetch, requestSignal).openAsks(requestedSessionID, since);
-  };
-  const setReminderBaseline = (requestedSessionID, period, asOf) => {
-    candidateBaseline = { sessionID: requestedSessionID, asOf };
-    if (askAwareness.session_id !== requestedSessionID || askAwareness.period !== period || askAwareness.checked || askAwareness.fired || askAwareness.baseline_as_of !== null) {
-      return;
-    }
-    persistAskAwareness({ ...askAwareness, baseline_as_of: asOf });
-  };
-  const refreshReminderBaseline = async (requestedSessionID, period, context) => {
-    try {
-      const snapshot = await queryOpenAsks(requestedSessionID);
-      if (snapshot === null)
-        return;
-      setReminderBaseline(requestedSessionID, period, snapshot.as_of);
-    } catch (error) {
-      warnAskAvailability(context, error);
-    }
-  };
-  const armAskReminder = async (context, refreshBaseline = false) => {
-    const id = context.sessionManager.getSessionId();
-    if (id === "" || activeDispatchConfig() === null)
-      return;
-    awarenessGeneration++;
-    availabilityWarningPeriod = undefined;
-    const baseline = !agentRunning && !refreshBaseline && candidateBaseline !== undefined && candidateBaseline.sessionID === id ? candidateBaseline.asOf : null;
-    const previousPeriod = askAwareness.session_id === id ? askAwareness.period : 0;
-    persistAskAwareness({
-      session_id: id,
-      period: previousPeriod + 1,
-      baseline_as_of: baseline,
-      checked: false,
-      fired: false,
-      saw_ask: false
-    });
-    if (agentRunning || refreshBaseline) {
-      await refreshReminderBaseline(id, askAwareness.period, context);
-    }
-  };
-  const cancelPendingAskReminder = () => {
-    awarenessGeneration++;
-  };
-  const installTerminalInputCancellation = (context) => {
-    terminalInputUnsubscribe?.();
-    terminalInputUnsubscribe = context.ui.onTerminalInput(cancelPendingAskReminder);
+    const snapshot = await new DispatchClient(config.url, config.token, fetch, AbortSignal.timeout(OPEN_ASKS_TIMEOUT_MS)).openAsks(requestedSessionID);
+    availabilityWarningSessionIDs.delete(requestedSessionID);
+    return snapshot;
   };
   const restoreLocalSessionState = (context) => {
     sessionDirectory = context.cwd;
     sessionID = context.sessionManager.getSessionId();
     activeSessionContext = context;
-    candidateBaseline = undefined;
-    const branch = context.sessionManager.getBranch?.() ?? [];
-    askAwareness = transcriptAskAwareness(branch, sessionID) ?? emptyAskAwareness(sessionID);
-    const persistedLegionSession = transcriptMarksLegionSession(branch, sessionID);
-    const managed = persistedLegionSession || legionRoleClaimBridge().managedSessions.has(sessionID);
-    legionManagedSessionID = managed ? sessionID : "";
   };
   pi.on("resources_discover", async () => ({ skillPaths: [SKILLS_DIRECTORY] }));
   registerEnvoyMessageRenderer(pi);
@@ -33912,13 +33824,6 @@ function envoyExtension(pi) {
     const dedupeKey = rendered.envelope?.dedupe_key;
     const duplicate = dedupeKey !== undefined && dedupeKeys.has(dedupeKey);
     if (!duplicate && !rendered.skip) {
-      if (rendered.dispatchActor?.kind === "user" && activeSessionContext !== undefined) {
-        try {
-          await armAskReminder(activeSessionContext, true);
-        } catch (error) {
-          warnAskAvailability(activeSessionContext, error);
-        }
-      }
       const envelope = rendered.envelope;
       if (envelope !== undefined) {
         inbox.unshift({
@@ -34238,17 +34143,6 @@ function envoyExtension(pi) {
     return run;
   };
   const bridge = legionRoleClaimBridge();
-  bridge.markManagedSession = (targetSessionID, context) => {
-    bridge.managedSessions.add(targetSessionID);
-    if (targetSessionID !== sessionID)
-      return;
-    if (legionManagedSessionID === targetSessionID)
-      return;
-    legionManagedSessionID = targetSessionID;
-    if (context !== undefined || activeSessionContext !== undefined) {
-      pi.appendEntry(LEGION_MANAGED_ENTRY, { session_id: targetSessionID });
-    }
-  };
   const claim = async (targetSessionID, role, callerContext) => {
     const context = callerContext ?? activeSessionContext;
     if (context === undefined || context.sessionManager.getSessionId() !== targetSessionID) {
@@ -34262,7 +34156,6 @@ function envoyExtension(pi) {
   bridge.claim = claim;
   bridge.ready.resolve(claim);
   pi.on("session_start", async (_event, context) => {
-    installTerminalInputCancellation(context);
     const previousSessionID = sessionID;
     restoreLocalSessionState(context);
     if (dispatchConfig.error !== null) {
@@ -34298,7 +34191,6 @@ function envoyExtension(pi) {
     }
   });
   const rebind = async (reason, context) => {
-    installTerminalInputCancellation(context);
     const previousID = sessionID;
     restoreLocalSessionState(context);
     if (defaults.natsUrls.length === 0)
@@ -34348,8 +34240,6 @@ function envoyExtension(pi) {
       ]);
     } finally {
       clearTimeout(timer);
-      terminalInputUnsubscribe?.();
-      terminalInputUnsubscribe = undefined;
       connection = undefined;
       activeSessionContext = undefined;
       subscriptions.clear();
@@ -34403,7 +34293,6 @@ function envoyExtension(pi) {
       const snapshot = await queryOpenAsks(id);
       if (snapshot === null)
         return;
-      setReminderBaseline(id, askAwareness.session_id === id ? askAwareness.period : 0, snapshot.as_of);
       return {
         message: {
           customType: "dispatch-open-asks",
@@ -34425,60 +34314,7 @@ ${formatOpenAsksSummary(snapshot, currentDispatchConfig().url)}`,
       };
     }
   });
-  pi.on("agent_start", async () => {
-    agentRunning = true;
-    agentWillContinue = false;
-  });
-  pi.on("agent_end", async (event) => {
-    agentRunning = false;
-    agentWillContinue = event.willContinue === true;
-  });
-  pi.on("input", async () => {
-    cancelPendingAskReminder();
-  });
-  pi.on("message_start", async (event, context) => {
-    if (!isHumanTurnInitiator(event.message))
-      return;
-    try {
-      await armAskReminder(context);
-    } catch (error) {
-      warnAskAvailability(context, error);
-    }
-  });
-  pi.on("session_stop", async (event, context) => {
-    if (event.stop_hook_active || event.signal.aborted || shuttingDown || agentWillContinue || event.last_assistant_message?.role !== "assistant" || event.session_id !== sessionID || legionManagedSessionID === event.session_id || askAwareness.session_id !== event.session_id || askAwareness.period === 0 || askAwareness.checked || askAwareness.fired) {
-      return;
-    }
-    const baseline = askAwareness.baseline_as_of;
-    if (baseline === null)
-      return;
-    if (context.ui.getEditorText().trim() !== "")
-      return;
-    const claimed = { ...askAwareness, checked: true };
-    const generation = awarenessGeneration;
-    persistAskAwareness(claimed);
-    let snapshot;
-    try {
-      snapshot = await queryOpenAsks(event.session_id, baseline, event.signal);
-    } catch (error) {
-      if (!event.signal.aborted && generation === awarenessGeneration) {
-        warnAskAvailability(context, error);
-      }
-      return;
-    }
-    if (snapshot === null || event.signal.aborted || generation !== awarenessGeneration || shuttingDown || agentWillContinue || context.sessionManager.getSessionId() !== event.session_id || sessionID !== event.session_id || legionManagedSessionID === event.session_id || context.ui.getEditorText().trim() !== "" || askAwareness.session_id !== claimed.session_id || askAwareness.period !== claimed.period || !askAwareness.checked) {
-      return;
-    }
-    if (snapshot.count > 0 || snapshot.opened_since || askAwareness.saw_ask) {
-      return;
-    }
-    persistAskAwareness({ ...askAwareness, fired: true });
-    return { continue: true, additionalContext: OPEN_ASKS_REMINDER };
-  });
   pi.on("tool_result", async (event) => {
-    if (!event.isError && event.toolName === "dispatch_ask" && typeof event.details === "object" && event.details !== null && "ask" in event.details && typeof event.details.ask === "string" && askAwareness.session_id === sessionID && askAwareness.period > 0 && !askAwareness.saw_ask) {
-      persistAskAwareness({ ...askAwareness, saw_ask: true });
-    }
     if (event.isError)
       return;
     const topic = dispatchSubscriptionTopic(event.details);

package/dist/skills/dispatch/SKILL.md

@@ -111,6 +111,7 @@ dispatch_ask({
   issue?,
   project?,
   artifact?,
+  ref?,
   question,
   options?: { label, description? }[],
   multiple?,
@@ -120,6 +121,8 @@ dispatch_ask({
 ```
 It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document, topic, ask }` for a project document.
 
+References belong in the question text; `ref` is sugar that appends its `dispatch://` value to the question as a rendered link.
+
 An ask is read on a phone by someone who has not read the code. Open with one or two plain
 sentences: what needs deciding and why it matters now. Each option is a button with a label and
 one sentence saying what happens if it is chosen; never enumerate choices in prose. Put the
@@ -341,6 +344,24 @@ with your text. Never do that: the spec is edited in place with `dispatch_doc_ed
 artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
 slug also arrives on `artifact.created` events.
 
+## Structure over stream
+
+Dispatch is a structured workspace, never a message stream (Sami, 2026-09-13, verbatim: "strange
+to me that agents keep trying to use dispatch as a giant stream of messages instead of
+high-signal, structured conversation"). The structure IS the product:
+
+- **One issue per piece of work.** A new deliverable — an email to send, a document to review, a
+  decision with its own lifecycle — gets its own issue with the content as the issue's document
+  (spec artifact), not a message pile on an existing issue. If you are about to post a message
+  carrying a draft, a spec, or anything over a couple of paragraphs, stop: that is an issue with a
+  document, or an artifact on the issue it belongs to.
+- **Content lives in documents; decisions live in asks; messages only announce.** A draft the
+  human must read goes in a document artifact the dashboard renders with versions and margins; the
+  ask that needs their word references it (`ref`, or the `dispatch://` link inline) instead of
+  restating it. A message never carries a body a human has to scroll.
+- **Never split one deliverable across a message + an ask that points at it.** Ask the question
+  with the document reference in the question text; the reader lands on the content in one click.
+
 ## Messages
 
 Dispatch is a high-signal record for humans, not a log of what you are doing. A message is a reply to a human's message, or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "1.27.0",
+  "version": "1.27.2",
   "type": "module",
   "omp": {
     "extensions": [