@sjawhar/pi-envoy 10.21.0 → 10.23.0

package/dist/dispatch.js

@@ -13576,6 +13576,7 @@ var DispatchServerStartedPayloadSchema = exports_external.strictObject({
   commit: exports_external.string().min(1),
   started_at: exports_external.iso.datetime()
 });
+var DEFAULT_ISSUE_READ_EVENTS = 10;
 var DispatchEventSchema = exports_external.object({
   issue_key: exports_external.string().nullable(),
   artifact_id: exports_external.string().nullish(),
@@ -14353,13 +14354,15 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_read",
     example: { issue: "DSP-1" },
-    description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
+    description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
       artifact: z2.string().describe("Document artifact id, slug, or filename: one of the issue's, or a project document.").optional(),
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
-      message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional()
+      message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional(),
+      events: z2.number({ int: true, min: 1 }).describe(`How many of the issue's newest events an issue read or its dispatch://KEY/log lists, oldest first; default ${DEFAULT_ISSUE_READ_EVENTS}. Name no --all-events with it.`).optional(),
+      all_events: z2.boolean().describe(`List every one of the issue's events, oldest first, on an issue read or its dispatch://KEY/log, in place of the last ${DEFAULT_ISSUE_READ_EVENTS}. Name no --events with it.`).optional()
     }),
     validation: readValidation
   },
@@ -15161,6 +15164,7 @@ function asErrorShape(value) {
 function isJson(response) {
   return response.headers.get("content-type")?.includes("application/json") ?? false;
 }
+var ISSUE_EVENTS_PAGE_MAX = 200;
 var DISPATCH_TOOL_DEADLINE_MS = 60000;
 function requestSignal(signal) {
   const deadline = AbortSignal.timeout(DISPATCH_TOOL_DEADLINE_MS);
@@ -15302,13 +15306,28 @@ class DispatchClient {
   async releaseIssueClaim(issue2, input = {}) {
     return this.#json("DELETE", ["api", "v1", "issues", await this.#resolveIssue(issue2), "claim"], input);
   }
-  async getIssueEvents(issue2, after = 0, limit = 200) {
+  async getIssueEvents(issue2, after = 0, limit = ISSUE_EVENTS_PAGE_MAX) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue2), "events"], undefined, { after, limit });
   }
-  async read(issueReference) {
+  async read(issueReference, options = {}) {
     const issueKey = await this.#resolveIssue(issueReference);
     const issue2 = await this.getIssue(issueKey);
-    const events = await this.getIssueEvents(issueKey, Math.max(0, issue2.last_seq - 10), 10);
+    const requested = options.events;
+    const count = requested === undefined ? DEFAULT_ISSUE_READ_EVENTS : requested === "all" ? issue2.last_seq : Math.min(requested, issue2.last_seq);
+    const events = [];
+    let after = Math.max(0, issue2.last_seq - count);
+    while (events.length < count) {
+      const limit = Math.min(ISSUE_EVENTS_PAGE_MAX, count - events.length);
+      const page = await this.getIssueEvents(issueKey, after, limit);
+      events.push(...page);
+      const last = page.at(-1);
+      if (page.length < limit || last === undefined || events.length >= count)
+        break;
+      if (last.seq <= after) {
+        throw new Error(`GET /api/v1/issues/${issueKey}/events?after=${after} answered no event after seq ${after}`);
+      }
+      after = last.seq;
+    }
     return { issue: issue2, events };
   }
   async ask(issue2, input) {
@@ -16659,6 +16678,16 @@ function argumentProblems(tool, args) {
       if (message !== undefined && messageIdOf(message) === undefined) {
         problems.push("message must be a full message id (uuid) or a dispatch://KEY/message/<id> reference");
       }
+      const events = optionalNumber(args, "events");
+      const allEvents = optionalBoolean(args, "all_events") === true;
+      if (events !== undefined && allEvents) {
+        problems.push("--events and --all-events both say how many events the read lists: name one, --events N for the last N or --all-events for every one");
+      }
+      const count = events !== undefined ? "--events" : allEvents ? "--all-events" : undefined;
+      const eventless = count === undefined ? undefined : readWithoutEvents(args);
+      if (eventless !== undefined) {
+        problems.push(`${count} lists an issue's events, which dispatch read prints only for an issue or its dispatch://KEY/log, not for ${eventless}: drop ${count}`);
+      }
       break;
     }
     case "dispatch_doc_read": {
@@ -16670,6 +16699,27 @@ function argumentProblems(tool, args) {
   }
   return problems;
 }
+function readWithoutEvents(args) {
+  if (optionalString(args, "message") !== undefined)
+    return "a message's conversation";
+  const ref = optionalString(args, "ref");
+  switch (ref === undefined ? undefined : parseDispatchRef(ref)?.kind) {
+    case "ask":
+      return "an ask";
+    case "comment":
+      return "a comment";
+    case "message":
+      return "a message's conversation";
+    case "children":
+      return "the issue's children";
+    case "log":
+      return;
+  }
+  if (optionalString(args, "artifact") !== undefined || optionalString(args, "project") !== undefined) {
+    return "a document summary";
+  }
+  return;
+}
 function dispatchRefFromUrl(value, serverUrl) {
   let url2;
   let origin;
@@ -18581,8 +18631,11 @@ ${trailer.join(`
         };
       }
       const issueKey = issue2();
+      const readEvents = {
+        events: optionalBoolean(args, "all_events") === true ? "all" : optionalNumber(args, "events")
+      };
       if (ownerArguments.ref?.kind === "log") {
-        const read2 = await client.read(issueKey);
+        const read2 = await client.read(issueKey, readEvents);
         const pictures3 = await picturesOf(read2.events.flatMap(eventTexts));
         return {
           text: [logSummary(read2.issue, read2.events), ...pictures3.lines].join(`
@@ -18592,13 +18645,13 @@ ${trailer.join(`
         };
       }
       if (ownerArguments.ref?.kind === "children") {
-        const read2 = await client.read(issueKey);
+        const parent = await client.getIssue(issueKey);
         return {
-          text: childrenSummary(read2.issue),
-          details: { issue: read2.issue.key }
+          text: childrenSummary(parent),
+          details: { issue: parent.key }
         };
       }
-      const readPromise = client.read(issueKey);
+      const readPromise = client.read(issueKey, readEvents);
       const referencesPromise = issueReferencesOrUnavailable(client, issueKey);
       const read = await readPromise;
       const [references, graph, titles, pictures2] = await Promise.all([
@@ -19342,8 +19395,14 @@ function dispatchSettings(env, config2) {
 
 // ../envoy-client/src/envoy-settings.ts
 var DEFAULT_ENVOY_URL = "http://127.0.0.1:9020";
-var DEFAULT_HEARTBEAT_MS = 120000;
-var MIN_HEARTBEAT_MS = 25;
+var DEFAULT_HEARTBEAT_MS = 90000;
+var MIN_PASS_DEADLINE_MS = 30000;
+var MIN_INTERVAL_MS = 25;
+var MAX_INTERVAL_MS = 2147483647;
+function namedInterval(raw) {
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
 function natsSeedFromEnvironment(env) {
   const { NATS_NKEY_SEED_FILE: file2, NATS_NKEY_SEED: plain } = env;
   if (file2 !== undefined) {
@@ -19430,13 +19489,17 @@ function envoySettings(env, config2, options = {}) {
       inbound = { off: messageFor(error48) };
     }
   }
-  const rawHeartbeatMs = Number(env.ENVOY_HEARTBEAT_MS);
+  const namedHeartbeatMs = namedInterval(env.ENVOY_HEARTBEAT_MS);
+  const heartbeatMs = namedHeartbeatMs === undefined ? DEFAULT_HEARTBEAT_MS : Math.min(Math.max(namedHeartbeatMs, MIN_INTERVAL_MS), MAX_INTERVAL_MS);
+  const namedPassDeadlineMs = namedInterval(env.ENVOY_PASS_DEADLINE_MS);
   return {
     enabled: true,
     url: normalizeEnvoyUrl(url2),
     token,
     inbound,
-    heartbeatMs: Number.isFinite(rawHeartbeatMs) && rawHeartbeatMs > 0 ? Math.max(rawHeartbeatMs, MIN_HEARTBEAT_MS) : DEFAULT_HEARTBEAT_MS
+    heartbeatMs,
+    passDeadlineMs: Math.min(Math.max(namedPassDeadlineMs ?? MIN_PASS_DEADLINE_MS, heartbeatMs), MAX_INTERVAL_MS),
+    passDeadlineRaisedFrom: namedPassDeadlineMs !== undefined && namedPassDeadlineMs < heartbeatMs ? namedPassDeadlineMs : undefined
   };
 }
 function normalizeEnvoyUrl(value) {

package/dist/envoy.js

@@ -29665,6 +29665,7 @@ var DispatchServerStartedPayloadSchema = exports_external.strictObject({
   commit: exports_external.string().min(1),
   started_at: exports_external.iso.datetime()
 });
+var DEFAULT_ISSUE_READ_EVENTS = 10;
 var DispatchEventSchema = exports_external.object({
   issue_key: exports_external.string().nullable(),
   artifact_id: exports_external.string().nullish(),
@@ -30340,13 +30341,15 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_read",
     example: { issue: "DSP-1" },
-    description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
+    description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
       artifact: z2.string().describe("Document artifact id, slug, or filename: one of the issue's, or a project document.").optional(),
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
-      message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional()
+      message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional(),
+      events: z2.number({ int: true, min: 1 }).describe(`How many of the issue's newest events an issue read or its dispatch://KEY/log lists, oldest first; default ${DEFAULT_ISSUE_READ_EVENTS}. Name no --all-events with it.`).optional(),
+      all_events: z2.boolean().describe(`List every one of the issue's events, oldest first, on an issue read or its dispatch://KEY/log, in place of the last ${DEFAULT_ISSUE_READ_EVENTS}. Name no --events with it.`).optional()
     }),
     validation: readValidation
   },
@@ -32705,6 +32708,7 @@ function asErrorShape(value) {
 function isJson(response) {
   return response.headers.get("content-type")?.includes("application/json") ?? false;
 }
+var ISSUE_EVENTS_PAGE_MAX = 200;
 var DISPATCH_TOOL_DEADLINE_MS = 60000;
 function requestSignal(signal) {
   const deadline = AbortSignal.timeout(DISPATCH_TOOL_DEADLINE_MS);
@@ -32846,13 +32850,28 @@ class DispatchClient {
   async releaseIssueClaim(issue2, input = {}) {
     return this.#json("DELETE", ["api", "v1", "issues", await this.#resolveIssue(issue2), "claim"], input);
   }
-  async getIssueEvents(issue2, after = 0, limit = 200) {
+  async getIssueEvents(issue2, after = 0, limit = ISSUE_EVENTS_PAGE_MAX) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue2), "events"], undefined, { after, limit });
   }
-  async read(issueReference) {
+  async read(issueReference, options = {}) {
     const issueKey = await this.#resolveIssue(issueReference);
     const issue2 = await this.getIssue(issueKey);
-    const events = await this.getIssueEvents(issueKey, Math.max(0, issue2.last_seq - 10), 10);
+    const requested = options.events;
+    const count = requested === undefined ? DEFAULT_ISSUE_READ_EVENTS : requested === "all" ? issue2.last_seq : Math.min(requested, issue2.last_seq);
+    const events = [];
+    let after = Math.max(0, issue2.last_seq - count);
+    while (events.length < count) {
+      const limit = Math.min(ISSUE_EVENTS_PAGE_MAX, count - events.length);
+      const page = await this.getIssueEvents(issueKey, after, limit);
+      events.push(...page);
+      const last = page.at(-1);
+      if (page.length < limit || last === undefined || events.length >= count)
+        break;
+      if (last.seq <= after) {
+        throw new Error(`GET /api/v1/issues/${issueKey}/events?after=${after} answered no event after seq ${after}`);
+      }
+      after = last.seq;
+    }
     return { issue: issue2, events };
   }
   async ask(issue2, input) {
@@ -33567,29 +33586,16 @@ function writeSessionTitle(dir, title) {
   writeAtomically(join3(dir, "title"), title);
 }
 
-// ../envoy-client/src/nats-auth.ts
-var import_nats = __toESM(require_mod4(), 1);
-var seedKeys = import_nats.nkeys;
-function natsAuthOptions(seed) {
-  if (seed === undefined)
-    return {};
-  const bytes = new TextEncoder().encode(seed.value);
-  let publicKey;
-  try {
-    publicKey = seedKeys.fromSeed(bytes).getPublicKey();
-  } catch (error48) {
-    throw new Error(`${seed.source} does not hold a valid nkey seed: ${messageFor(error48)}`);
-  }
-  if (!publicKey.startsWith("U")) {
-    throw new Error(`${seed.source} holds an nkey seed that is not a user's (public key ${publicKey})`);
-  }
-  return { authenticator: import_nats.nkeyAuthenticator(bytes) };
-}
-
 // ../envoy-client/src/envoy-settings.ts
 var DEFAULT_ENVOY_URL = "http://127.0.0.1:9020";
-var DEFAULT_HEARTBEAT_MS = 120000;
-var MIN_HEARTBEAT_MS = 25;
+var DEFAULT_HEARTBEAT_MS = 90000;
+var MIN_PASS_DEADLINE_MS = 30000;
+var MIN_INTERVAL_MS = 25;
+var MAX_INTERVAL_MS = 2147483647;
+function namedInterval(raw) {
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
 function natsSeedFromEnvironment(env) {
   const { NATS_NKEY_SEED_FILE: file2, NATS_NKEY_SEED: plain } = env;
   if (file2 !== undefined) {
@@ -33676,19 +33682,42 @@ function envoySettings(env, config2, options = {}) {
       inbound = { off: messageFor(error48) };
     }
   }
-  const rawHeartbeatMs = Number(env.ENVOY_HEARTBEAT_MS);
+  const namedHeartbeatMs = namedInterval(env.ENVOY_HEARTBEAT_MS);
+  const heartbeatMs = namedHeartbeatMs === undefined ? DEFAULT_HEARTBEAT_MS : Math.min(Math.max(namedHeartbeatMs, MIN_INTERVAL_MS), MAX_INTERVAL_MS);
+  const namedPassDeadlineMs = namedInterval(env.ENVOY_PASS_DEADLINE_MS);
   return {
     enabled: true,
     url: normalizeEnvoyUrl(url2),
     token,
     inbound,
-    heartbeatMs: Number.isFinite(rawHeartbeatMs) && rawHeartbeatMs > 0 ? Math.max(rawHeartbeatMs, MIN_HEARTBEAT_MS) : DEFAULT_HEARTBEAT_MS
+    heartbeatMs,
+    passDeadlineMs: Math.min(Math.max(namedPassDeadlineMs ?? MIN_PASS_DEADLINE_MS, heartbeatMs), MAX_INTERVAL_MS),
+    passDeadlineRaisedFrom: namedPassDeadlineMs !== undefined && namedPassDeadlineMs < heartbeatMs ? namedPassDeadlineMs : undefined
   };
 }
 function normalizeEnvoyUrl(value) {
   return value.replace(/\/+$/, "");
 }
 
+// ../envoy-client/src/nats-auth.ts
+var import_nats = __toESM(require_mod4(), 1);
+var seedKeys = import_nats.nkeys;
+function natsAuthOptions(seed) {
+  if (seed === undefined)
+    return {};
+  const bytes = new TextEncoder().encode(seed.value);
+  let publicKey;
+  try {
+    publicKey = seedKeys.fromSeed(bytes).getPublicKey();
+  } catch (error48) {
+    throw new Error(`${seed.source} does not hold a valid nkey seed: ${messageFor(error48)}`);
+  }
+  if (!publicKey.startsWith("U")) {
+    throw new Error(`${seed.source} holds an nkey seed that is not a user's (public key ${publicKey})`);
+  }
+  return { authenticator: import_nats.nkeyAuthenticator(bytes) };
+}
+
 // ../envoy-client/src/session-settings.ts
 function sessionConfigFile(harness, env) {
   try {
@@ -33727,6 +33756,9 @@ function startNotice(config2, dispatch, envoy, nats) {
   if (envoy.enabled && nats && "off" in envoy.inbound) {
     parts.push(`Envoy's inbound messages are off: ${envoy.inbound.off}; the Envoy tools still work`);
   }
+  if (envoy.enabled && envoy.passDeadlineRaisedFrom !== undefined) {
+    parts.push(`Envoy's pass deadline is ${envoy.passDeadlineMs} ms, not the ${envoy.passDeadlineRaisedFrom} ms ENVOY_PASS_DEADLINE_MS names: a deadline inside one ${envoy.heartbeatMs} ms heartbeat interval would abandon every pass before the next tick, so the registration refresh the heartbeat posts for a stalled pass would never run`);
+  }
   return parts.length === 0 ? null : parts.join("; ");
 }
 function sessionSettings(file2, env, options) {
@@ -33737,7 +33769,11 @@ function sessionSettings(file2, env, options) {
   const config2 = readEnvoyConfig(file2.path, env, options);
   const dispatch = dispatchSettings(env, config2);
   const envoy = envoySettings(env, config2, { nats: options.nats });
-  return { dispatch, envoy, notice: startNotice(config2, dispatch, envoy, options.nats !== false) };
+  return {
+    dispatch,
+    envoy,
+    notice: startNotice(config2, dispatch, envoy, options.nats !== false)
+  };
 }
 function sessionDispatchSettings(file2, env, options) {
   if (file2.path === null)
@@ -35301,11 +35337,31 @@ import("@oh-my-pi/pi-coding-agent/extensibility/extensions/send-user-input-handl
 var codec2 = import_nats2.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
 var DELIVERY_PICTURES_TIMEOUT_MS = 20000;
-function serialQueue() {
+var UNFENCED = () => true;
+
+class AbandonedTaskError extends Error {
+}
+function serialQueue(deadlineMs) {
   let tail = Promise.resolve();
   return {
     run(task) {
-      const next = tail.then(task);
+      const next = tail.then(() => new Promise((resolve3, reject) => {
+        let abandoned = false;
+        const taskDeadlineMs = deadlineMs();
+        const timer = setTimeout(() => {
+          abandoned = true;
+          reject(new AbandonedTaskError(`a queued task did not settle within ${taskDeadlineMs}ms and was abandoned; the queue moved on`));
+        }, taskDeadlineMs);
+        (async () => task(() => !abandoned))().then((value) => {
+          clearTimeout(timer);
+          if (!abandoned)
+            resolve3(value);
+        }, (error48) => {
+          clearTimeout(timer);
+          if (!abandoned)
+            reject(error48);
+        });
+      }));
       tail = next.catch(() => {
         return;
       });
@@ -35456,6 +35512,7 @@ function envoyExtension(pi) {
     }
     return active;
   };
+  const passDeadlineMs = () => active?.settings.passDeadlineMs ?? MIN_PASS_DEADLINE_MS;
   const subscriptions = new Map;
   const delivered = createDeliveryDedupe();
   let connection;
@@ -35485,7 +35542,7 @@ function envoyExtension(pi) {
   let roleNoticesFor;
   const roleNoticeSubjects = new Set;
   let roleEnds = 0;
-  const roleMoves = serialQueue();
+  const roleMoves = serialQueue(passDeadlineMs);
   const isRoleBound = (subject2) => roleNoticeSubjects.has(subject2);
   const heldRole = () => claimedRoleTopic?.slice(ROLE_TOPIC_PREFIX.length);
   let activeSessionContext;
@@ -35621,11 +35678,11 @@ function envoyExtension(pi) {
     }
     return inbound2;
   };
-  const ensureConnection = async () => {
+  const ensureConnection = async (live = UNFENCED) => {
     if (connection?.isClosed() === false)
       return connection;
     const { natsUrls, natsSeed } = requireInbound();
-    connection = await import_nats2.connect({
+    const dialled = await import_nats2.connect({
       servers: [...natsUrls],
       name: `omp-${sessionID || "unknown"}`,
       ...natsAuthOptions(natsSeed),
@@ -35633,6 +35690,13 @@ function envoyExtension(pi) {
       maxReconnectAttempts: -1,
       reconnectTimeWait: 2000
     });
+    if (!live() || shuttingDown || connection?.isClosed() === false) {
+      await dialled.close().catch(() => {});
+      if (!shuttingDown && connection?.isClosed() === false)
+        return connection;
+      throw new AbandonedTaskError(shuttingDown ? "the session shut down while its NATS dial was in flight; the connection it opened was closed" : "the pass that dialled NATS was abandoned at its deadline while the dial was in flight; the connection it opened was closed");
+    }
+    connection = dialled;
     return connection;
   };
   const postDispatchReply = async (delivery, result, replySessionID = sessionID) => {
@@ -35868,11 +35932,13 @@ function envoyExtension(pi) {
     };
     retry(RESUBSCRIBE_DELAY_MS);
   };
-  const subscribe = async (topic) => {
+  const subscribe = async (topic, live = UNFENCED) => {
     const subjects = expandSubscriptionTopics([topic]).filter((candidate) => !subscriptions.has(candidate));
     if (subjects.length === 0)
       return false;
-    const activeConnection = await ensureConnection();
+    const activeConnection = await ensureConnection(live);
+    if (!live())
+      return false;
     for (const subject2 of subjects) {
       const subscription = activeConnection.subscribe(subject2);
       intentionallyClosed.delete(subject2);
@@ -35971,7 +36037,7 @@ function envoyExtension(pi) {
       });
     }, RESUBSCRIBE_DELAY_MS);
   };
-  const watchAgentStream = async (session) => {
+  const watchAgentStream = async (session, live = UNFENCED) => {
     if (agentStreamControlSession === session && agentStreamControl !== undefined)
       return;
     agentStreamControl?.unsubscribe();
@@ -35982,8 +36048,10 @@ function envoyExtension(pi) {
       agentStreamCommandsRefreshedOnWatchAt = -Infinity;
     }
     agentStreamControlSession = session;
-    const active2 = await ensureConnection();
-    const subscription = active2.subscribe(agentStreamControlSubject(session));
+    const connected = await ensureConnection(live);
+    if (!live())
+      return;
+    const subscription = connected.subscribe(agentStreamControlSubject(session));
     agentStreamControl = subscription;
     pumpAgentStreamControl(subscription, session);
   };
@@ -36046,12 +36114,15 @@ function envoyExtension(pi) {
       closeIntentionally(subject2);
     return false;
   };
+  let registeredFor = "";
+  let registeredAt = -Infinity;
   const registerSession = () => {
-    for (const [topic, hold] of abandonedHolds) {
+    const registeringFor = sessionID;
+    for (const [key, hold] of abandonedHolds) {
       if (hold.id !== sessionID)
         continue;
-      abandonedHolds.delete(topic);
-      pendingHandBacks.set(`${topic}@${sessionID}`, { topic, id: sessionID });
+      abandonedHolds.delete(key);
+      pendingHandBacks.set(key, { topic: hold.topic, id: sessionID });
     }
     return requireEnvoy().client.subscribe({
       sessionID,
@@ -36067,17 +36138,23 @@ function envoyExtension(pi) {
       capabilities: sideTurn(activeSessionContext) === undefined ? CAPABILITIES_WITHOUT_BTW : DELIVERY_CAPABILITIES,
       driving: false,
       selfSubscribed: true
+    }).then((result) => {
+      registeredFor = registeringFor;
+      registeredAt = Date.now();
+      return result;
     });
   };
-  const reassertRoleNow = async (id, role, afterOutage, context) => {
+  const reassertRoleNow = async (id, role, afterOutage, context, live) => {
     const topic = ROLE_TOPIC_PREFIX + role;
     const { client } = requireEnvoy();
+    const owns = () => live() && sessionOpen(id);
+    const stillHolds = () => claimedRoleTopic === topic;
     const holder = await client.getRole(role).then((info) => info.holder, (error48) => {
       if (error48 instanceof EnvoyApiError && error48.details.status === 404)
         return;
       throw error48;
     });
-    if (claimedRoleTopic !== topic || !sessionOpen(id))
+    if (!owns() || !stillHolds())
       return false;
     let reason;
     if (holder === id) {
@@ -36086,7 +36163,7 @@ function envoyExtension(pi) {
       reason = "reregistered";
     } else {
       const result = await client.setRole({ sessionID: id, role, soft: true });
-      if (claimedRoleTopic !== topic || !sessionOpen(id))
+      if (!owns() || !stillHolds())
         return false;
       if (!result.claimed) {
         endRole();
@@ -36118,23 +36195,48 @@ function envoyExtension(pi) {
     if (heartbeatRegistered)
       return;
     let heartbeatOutageNotified = false;
+    let stallNotified = false;
     let registrationFailed = false;
     let healing = false;
+    const noteStall = (detail) => {
+      if (stallNotified)
+        return;
+      stallNotified = true;
+      logger3.warn("envoy: reconcile pass stalled; registration refreshed on its own", {
+        detail,
+        sessionID: context.sessionManager.getSessionId()
+      });
+      context.ui.notify(`envoy: a reconcile pass has stalled (${detail}); the session registration is being refreshed on its own, and recovers once the pass settles`, "warning");
+    };
     context.setInterval(() => {
       if (context.sessionManager.getSessionId() === "")
         return;
-      if (healing)
+      if (healing) {
+        const refreshMs = requireEnvoy().settings.heartbeatMs;
+        if (registeredFor === sessionID && Date.now() - registeredAt < refreshMs)
+          return;
+        noteStall("a pass has not settled a whole refresh interval after the last accepted registration");
+        registerSession().catch(() => {
+          return;
+        });
         return;
+      }
       healing = true;
       const afterOutage = registrationFailed;
       const settled = (decided) => {
         if (decided)
           registrationFailed = false;
         heartbeatOutageNotified = false;
+        stallNotified = false;
       };
       reconcile(context, { heartbeat: true, afterOutage }).then(settled, (error48) => {
         if (error48 instanceof InboundError)
           return settled(error48.decided);
+        if (error48 instanceof AbandonedTaskError) {
+          registrationFailed = true;
+          noteStall(messageFor(error48));
+          return;
+        }
         if (error48 instanceof RegistrationError)
           registrationFailed = true;
         throw error48 instanceof RegistrationError ? error48.cause : error48;
@@ -36149,12 +36251,12 @@ function envoyExtension(pi) {
     }, requireEnvoy().settings.heartbeatMs);
     heartbeatRegistered = true;
   };
-  const recoverRegisteredInterests = async () => {
+  const recoverRegisteredInterests = async (live) => {
     const { client } = requireEnvoy();
     const registry2 = await client.getInterest(sessionID).catch(() => {
       return;
     });
-    if (registry2 === undefined)
+    if (registry2 === undefined || !live())
       return;
     const retired = publishedInterface?.roleClaim.slackRoleOwned === true ? registry2.topics.filter((topic) => slackTopicChannel(topic) !== undefined) : [];
     if (retired.length > 0) {
@@ -36166,31 +36268,34 @@ function envoyExtension(pi) {
         });
       });
     }
+    if (!live())
+      return;
     for (const topic of registry2.topics) {
       if (topic === agentSubject(sessionID) || topic.startsWith(ROLE_TOPIC_PREFIX))
         continue;
       if (retired.includes(topic))
         continue;
-      await subscribe(topic);
+      await subscribe(topic, live);
     }
   };
-  const observeAbandonedHold = async (topic, role, holder) => {
-    const abandoned = abandonedHolds.get(topic);
-    if (abandoned === undefined || abandoned.id !== holder)
+  const observeAbandonedHold = async (topic, role, holder, live) => {
+    const key = `${topic}@${holder}`;
+    const abandoned = abandonedHolds.get(key);
+    if (abandoned === undefined)
       return false;
     const seen = await requireEnvoy().client.getRole(role).then((info) => info.holder === holder ? info.last_seen : undefined, () => {
       return;
     });
-    if (seen === undefined)
+    if (!live() || seen === undefined)
       return true;
     if (abandoned.lastSeen !== undefined && seen !== abandoned.lastSeen) {
-      abandonedHolds.delete(topic);
+      abandonedHolds.delete(key);
       return false;
     }
-    abandonedHolds.set(topic, { id: abandoned.id, lastSeen: seen });
+    abandonedHolds.set(key, { topic, id: abandoned.id, lastSeen: seen });
     return true;
   };
-  const setEnvoyRole = async (role, forSession, options = {}) => {
+  const setEnvoyRole = async (role, forSession, live, options = {}) => {
     if (!sessionOpen(forSession)) {
       throw new SessionLeftError(`the session moved from ${forSession} to ${hostSessionID()} before its claim of role ${role} ran; nothing was claimed`);
     }
@@ -36205,10 +36310,18 @@ function envoyExtension(pi) {
       soft: options.soft,
       previousSessionID: options.previousSessionID
     });
+    if (!live()) {
+      if (result.claimed)
+        pendingHandBacks.set(`${topic}@${id}`, { topic, id });
+      throw new AbandonedTaskError(`the role move that claimed ${role} for session ${id} was abandoned at its deadline while the claim was in flight; ${result.claimed ? "the hold the listener granted is left for the next pass to hand back" : "nothing was claimed"}`);
+    }
     if (result.claimed) {
       refusedRoles.delete(id);
       holdUnconfirmed = false;
-      abandonedHolds.delete(topic);
+      for (const [key, hold] of abandonedHolds) {
+        if (hold.topic === topic)
+          abandonedHolds.delete(key);
+      }
       for (const [key, hold] of pendingHandBacks) {
         if (hold.topic === topic)
           pendingHandBacks.delete(key);
@@ -36228,10 +36341,11 @@ function envoyExtension(pi) {
     }
     if (!result.claimed) {
       endRole();
-      const waitingOnReap = await observeAbandonedHold(topic, role, result.holder);
-      if (!waitingOnReap)
+      const waitingOnReap = await observeAbandonedHold(topic, role, result.holder, live);
+      const notRecorded = !live() ? "the move was abandoned at its deadline before the refusal was recorded" : sessionOpen(id) ? undefined : `the session moved to ${hostSessionID()} before the refusal was recorded`;
+      if (notRecorded === undefined && !waitingOnReap)
         refusedRoles.set(id, role);
-      logger3.warn(waitingOnReap ? "envoy: role still held by a session this process left; claiming again once the listener reaps it" : "envoy: role held by another live session; not reclaimed", { role, sessionID: id, holder: result.holder });
+      logger3.warn(notRecorded !== undefined ? `envoy: role held by another live session; ${notRecorded}` : waitingOnReap ? "envoy: role still held by a session this process left; claiming again once the listener reaps it" : "envoy: role held by another live session; not reclaimed", { role, sessionID: id, holder: result.holder });
       return false;
     }
     if (previousTopic !== undefined && previousTopic !== topic)
@@ -36340,12 +36454,13 @@ function envoyExtension(pi) {
     knownSessions.add(host3);
   };
   const knownSessions = new Set;
-  const passes = serialQueue();
-  const reconcile = (context, cause = {}) => passes.run(() => reconcileNow(context, cause));
+  const passes = serialQueue(passDeadlineMs);
+  const reconcile = (context, cause = {}) => passes.run((live) => reconcileNow(context, cause, live));
   const agentSessions = new Set;
   let inboundOpenFor = "";
-  const reconcileNow = async (context, cause) => {
+  const reconcileNow = async (context, cause, live) => {
     const host3 = context.sessionManager.getSessionId();
+    const owns = () => live() && sessionOpen(host3);
     noteMove(host3);
     if (sessionID !== host3)
       restoreLocalSessionState(context);
@@ -36375,27 +36490,39 @@ function envoyExtension(pi) {
     if (inbound && inboundOpenFor !== host3) {
       try {
         agentSessions.add(host3);
-        await ensureConnection();
-        await subscribe(agentSubject(host3));
-        await watchAgentStream(host3);
+        await ensureConnection(live);
+        if (!owns())
+          return false;
+        await subscribe(agentSubject(host3), live);
+        if (!owns())
+          return false;
+        await watchAgentStream(host3, live);
+        if (!owns())
+          return false;
         if ((context.sessionManager.getBranch?.() ?? []).length > 0) {
-          await recoverRegisteredInterests();
+          await recoverRegisteredInterests(live);
+          if (!owns())
+            return false;
         }
         inboundOpenFor = host3;
       } catch (error48) {
         inboundFailure = error48;
       }
     }
-    if (hostSessionID() !== host3)
+    if (!owns())
       return false;
     const registration = await registerSession().then(() => {
       return;
     }, (error48) => ({ error: error48 }));
+    if (!owns())
+      return false;
     if (registration === undefined) {
       establishedSession = host3;
       ensureHeartbeat(context);
     }
-    const decided = await roleMoves.run(() => settleRole(context, host3, cause, registration === undefined));
+    const decided = await roleMoves.run((moveLive) => settleRole(context, host3, cause, registration === undefined, moveLive));
+    if (!owns())
+      return false;
     if (registration !== undefined) {
       throw new RegistrationError(messageFor(registration.error), { cause: registration.error });
     }
@@ -36406,12 +36533,14 @@ function envoyExtension(pi) {
   };
   let roleSettledFor = "";
   let lastHeard = "";
-  const settleEndedHolds = async (host3, wanted) => {
+  const settleEndedHolds = async (wanted, live) => {
     let restored = false;
     const failed = [];
     for (const [key, hold] of pendingHandBacks) {
+      if (!live())
+        break;
       pendingHandBacks.delete(key);
-      if (wanted !== undefined && hold.topic === ROLE_TOPIC_PREFIX + wanted) {
+      if (wanted !== undefined && hold.topic === ROLE_TOPIC_PREFIX + wanted && sessionOpen(hold.id)) {
         claimedRoleTopic = hold.topic;
         claimedRoleSessionID = hold.id;
         holdUnconfirmed = true;
@@ -36427,21 +36556,20 @@ function envoyExtension(pi) {
         });
       });
     }
-    for (const { key, topic, id } of failed) {
-      if (id === host3)
-        pendingHandBacks.set(key, { topic, id });
-      else
-        abandonedHolds.set(topic, { id });
-    }
+    for (const { key, topic, id } of failed)
+      abandonedHolds.set(key, { topic, id });
+    if (!live())
+      return false;
     return restored;
   };
-  const settleRole = async (context, host3, cause, registered) => {
-    if (!sessionOpen(host3))
+  const settleRole = async (context, host3, cause, registered, live) => {
+    const owns = () => live() && sessionOpen(host3);
+    if (!owns())
       return false;
     const branch = context.sessionManager.getBranch?.() ?? [];
     const readRows = roleSettledFor !== host3 && (branch.length > 0 || roleSettledFor !== "");
     const desired = await desiredRole(host3, branch, readRows);
-    if (!sessionOpen(host3))
+    if (!owns())
       return false;
     const unheard = lastHeard !== host3;
     const held = heldRole();
@@ -36449,13 +36577,13 @@ function envoyExtension(pi) {
       const ended = await handBackRole();
       if (ended !== undefined && unheard)
         warnRoleEnded(context, host3, ended);
-      if (!sessionOpen(host3))
+      if (!owns())
         return false;
     }
-    if (await settleEndedHolds(host3, desired) && unheard && desired !== undefined) {
+    if (await settleEndedHolds(desired, live) && unheard && desired !== undefined) {
       warnNoticesClosed(context, desired);
     }
-    if (!sessionOpen(host3))
+    if (!owns())
       return false;
     if (!registered)
       return false;
@@ -36465,7 +36593,7 @@ function envoyExtension(pi) {
     }
     if (!holdUnconfirmed && heldRole() === desired && claimedRoleSessionID === host3) {
       roleSettledFor = host3;
-      return cause.heartbeat === true ? reassertRoleNow(host3, desired, cause.afterOutage === true, context) : true;
+      return cause.heartbeat === true ? reassertRoleNow(host3, desired, cause.afterOutage === true, context, live) : true;
     }
     if (!inbound) {
       roleSettledFor = host3;
@@ -36479,18 +36607,18 @@ function envoyExtension(pi) {
       });
       if (holder !== undefined && holder !== host3 && lineage.includes(holder))
         supersedes = holder;
-      if (!sessionOpen(host3))
+      if (!owns())
         return false;
     }
     try {
-      const claimed = await setEnvoyRole(desired, host3, {
+      const claimed = await setEnvoyRole(desired, host3, live, {
         soft: true,
         previousSessionID: supersedes
       });
       if (claimed && unheard)
         warnNoticesClosed(context, desired);
     } catch (error48) {
-      if (error48 instanceof SessionLeftError)
+      if (error48 instanceof SessionLeftError || error48 instanceof AbandonedTaskError)
         return false;
       logger3.warn("envoy: role reclaim failed", {
         role: desired,
@@ -36498,6 +36626,8 @@ function envoyExtension(pi) {
         error: messageFor(error48)
       });
     }
+    if (!owns())
+      return false;
     roleSettledFor = host3;
     return true;
   };
@@ -36530,7 +36660,7 @@ function envoyExtension(pi) {
     if (establishedSession !== targetSessionID)
       await establishForBridge(context);
     await registerSession();
-    await roleMoves.run(() => setEnvoyRole(role, targetSessionID));
+    await roleMoves.run((live) => setEnvoyRole(role, targetSessionID, live));
   };
   const subscribeNotice = async (targetSessionID, topic, callerContext, whileHolding) => {
     const context = callerContext ?? activeSessionContext;
@@ -36963,13 +37093,13 @@ Not delivered: that holder is the session this subagent sends as, and the listen
         }
         case EnvoyToolOperation.setRole: {
           const role = stringFor(parameters, "role");
-          const released = await roleMoves.run(async () => {
+          const released = await roleMoves.run(async (live) => {
             const held = heldRole();
             const moving = held !== undefined && held !== role;
             if (moving && roleNoticeSubjects.size > 0) {
               throw new Error(`This session holds role ${held}, and ${[...roleNoticeSubjects].join(", ")} lasts only while it does; envoy_role_set does not move it to ${role}`);
             }
-            await setEnvoyRole(role, sessionID);
+            await setEnvoyRole(role, sessionID, live);
             return moving ? held : undefined;
           });
           return toolSuccess(released === undefined ? `Now holding role: ${role}` : `Now holding role: ${role} (released role ${released})`, { role, ...released === undefined ? {} : { released } });

package/dist/skills/dispatch/references/reading.md

@@ -4,7 +4,8 @@ Read this to catch up after a restart, read a node, trace what cites it, or writ
 
 ## What comes back
 
-- After a restart, catch up with `dispatch read --issue <KEY>` (or `--artifact` with `--issue` or `--project`, or `--ref`). It prints the issue's summary, open asks, references and recent events, a document's summary (its issue, reference, versions and approval), or an ask's, comment's or message's thread. Reads do not subscribe. Use `dispatch doc-read` for document text.
+- After a restart, catch up with `dispatch read --issue <KEY>` (or `--artifact` with `--issue` or `--project`, or `--ref`). It prints the issue's summary, open asks, references and last 10 events, a document's summary (its issue, reference, versions and approval), or an ask's, comment's or message's thread. Reads do not subscribe. Use `dispatch doc-read` for document text.
+- To audit an issue's history (who asked what, which ask was answered), add `--events N` for the last N events or `--all-events` for every one. Both work on `--ref dispatch://KEY/log` too.
 - An anchored comment or ask prints `Position:`, where its quote's block stands. `unavailable (DOC_SERVICE_UNAVAILABLE)` means try again shortly. `unavailable (DOC_SCHEMA)` means the document needs repair.
 - The API gives the same facts as `anchor_block` (or `anchor_block_error`) on `GET /api/v1/comments/{id}` and `GET /api/v1/asks/{id}`. `GET /api/v1/artifacts/{id}/blocks/{block_id}` gives them for any block.
 - Each read ends with `Referenced by:` (what cites the node) and `Links:` (what it cites), across projects. "What led to this decision" is one read on the ask.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "10.21.0",
+  "version": "10.23.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {