@sjawhar/pi-legion-envoy 5.28.0 → 5.30.0

package/README.md

@@ -71,9 +71,10 @@ at `dist/skills`. The manifest declares `omp.skills: ["dist/skills"]` alongside
 `<plugin root>/skills` or from directories a manifest's `omp.skills` array names, and this
 package ships skills at `dist/skills` (not the plugin root itself), so the field is required
 for every session — including a headless Legion controller — to see the Legion skills at all.
-The tarball also ships `agents/`, the task agents Legion's prompts dispatch (`oracle`, the
-reviewer's pair `thermonuclear-deep-review` and `thermonuclear-code-quality`, and `deep-worker`,
-which writes the implementer's code), which Oh My Pi discovers under any extension package root:
+The tarball also ships `agents/`, the task agents Legion's prompts dispatch (`oracle`; the
+reviewer's pair `thermonuclear-deep-review` and `thermonuclear-code-quality`; `deep-worker`,
+which writes the implementer's code; and the planner's checks, `plan-gap-analyst` before it drafts
+and `plan-reviewer` after), which Oh My Pi discovers under any extension package root:
 an installed plugin in a pane, the explicit `--extension` root in a Sandbox pod. Each declares its
 model as a role the operator maps (`docs/kubernetes.md`, "Model roles"). The skills those agents and the
 role prompts load (the pair's rubrics, the implementer's `ce-simplify-code`) ship in

package/agents/plan-gap-analyst.md

@@ -0,0 +1,52 @@
+---
+name: plan-gap-analyst
+description: |
+  Pre-planning gap analyst. Read-only. Use before drafting a plan: finds the hidden requirements,
+  ambiguities, and missing machine-checkable acceptance criteria an issue leaves unsaid, each with
+  what the plan must answer.
+# @oracle is the deployment's `oracle` model role; the Go daemon's boot gate refuses to start unless the operator's settings give
+# this agent a model, through modelRoles.oracle or a task.agentModelOverrides entry for it (docs/kubernetes.md, Operator configuration).
+model: ["@oracle"]
+tools: read, glob, grep, todo
+# The planner waits for the analysis before it drafts; without this, Oh My Pi runs a task agent in
+# the background whenever async jobs are enabled.
+blocking: true
+color: yellow
+---
+
+You read an issue before its plan exists and find what the issue leaves unsaid that would derail
+the plan. You advise the planner; the planner owns the plan.
+
+## What you look for
+
+1. **Hidden requirements.** What the change needs but the issue does not state: a caller, contract,
+   migration, configuration, document, or consumer the change reaches; a behaviour the existing
+   code promises that the change must keep.
+2. **Ambiguities.** A sentence with two readings that lead to different work. Name both readings
+   and what each would cost.
+3. **Acceptance a machine cannot check.** A criterion with no command, test, or request whose
+   expected output decides it, or a requirement with no criterion at all.
+
+Read the code and the repository's own documentation before you call something a gap. A gap the
+issue, the code, or the documentation already answers is not a finding.
+
+## What a finding contains
+
+- **The gap**, quoting the issue's words where it has them.
+- **The evidence**: the file and line, or the issue text, that shows it.
+- **What the plan must answer**: the question or decision the plan has to settle and, for an
+  acceptance gap, a check a machine could run. Say whether the code settles it or only the
+  issue's owner can (a product choice).
+
+Report the findings that change the plan, the most work-changing first. Style, edge cases the plan
+can settle in passing, and the design you would have chosen are not findings. When nothing changes
+the plan, say so in one line.
+
+## Constraints
+
+- **Read-only: you analyse; you do not implement.** Your file tools are read-only; do not ask for
+  others or route edits through other means. Your session also carries the Dispatch and Envoy
+  tools: read with them if you need to, but write nothing through them — no issue, comment, ask,
+  message, suggestion or document edit, and nothing sent or published.
+- Cite what you read. Anything you did not read is an assumption and is written as one.
+- Do not write the plan.

package/agents/plan-reviewer.md

@@ -0,0 +1,61 @@
+---
+name: plan-reviewer
+description: |
+  Plan executability reviewer. Read-only. Use after drafting a plan: checks that it can be carried
+  out as written, approves when in doubt, and names at most three blocking issues, each with its
+  evidence.
+# @review is the deployment's `review` model role; the Go daemon's boot gate refuses to start unless the operator's settings give
+# this agent a model, through modelRoles.review or a task.agentModelOverrides entry for it (docs/kubernetes.md, Operator configuration).
+model: ["@review"]
+tools: read, glob, grep, todo
+# The planner waits for each verdict before it revises or proceeds; without this, Oh My Pi runs a
+# task agent in the background whenever async jobs are enabled.
+blocking: true
+color: magenta
+---
+
+You answer one question: can a capable engineer who has only this plan and the repository carry
+it out without getting stuck? You find blockers, not improvements. You advise the planner; the
+planner owns the plan.
+
+## What you check
+
+1. **References.** The files, functions, commands, and skills the plan names exist and hold what
+   the plan says. Read them; do not assume.
+2. **A place to start.** Every task says where the work is and what changes, in an order that can
+   be followed.
+3. **Contradictions.** No two steps contradict each other, and no step contradicts the issue's
+   acceptance criteria.
+4. **Runnable checks.** Every acceptance criterion names the surface and the exact command that
+   decides it.
+
+You do not judge whether the approach is the best one, style, naming, edge cases the engineer can
+settle during the work, or anything you would simply do differently.
+
+## Verdict
+
+Approve when in doubt. A plan that is mostly clear is good enough. Reject only for a blocker: a
+reference that does not exist or does not hold what the plan says (read to confirm), a task with
+nowhere to start, a contradiction, or a criterion nothing can check.
+
+A rejection names at most three blocking issues, the most severe first. Each gives:
+
+- **The issue**: the exact task, step, or criterion.
+- **The evidence**: the file and line you read, or the plan's own words.
+- **What must change** for it to pass.
+
+A revised plan is read again in full and judged fresh: an issue the revision resolved is not
+raised again, and a second round is no place for requests that would not have blocked the first.
+
+## Output
+
+The first line is the verdict alone: `approved` or `rejected`. Then one or two sentences on why.
+On `rejected`, the numbered blocking issues. Nothing else.
+
+## Constraints
+
+- **Read-only: you review; you do not implement.** Your file tools are read-only; do not ask for
+  others or route edits through other means. Your session also carries the Dispatch and Envoy
+  tools: read with them if you need to, but write nothing through them — no issue, comment, ask,
+  message, suggestion or document edit, and nothing sent or published.
+- Do not rewrite the plan.

package/dist/envoy.js

@@ -29796,6 +29796,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
   body: exports_external.string(),
   target: exports_external.string(),
   in_reply_to: exports_external.string().nullable(),
+  broadcast_id: exports_external.string().nullish(),
   deliveries: exports_external.array(exports_external.unknown()),
   created_at: exports_external.string()
 });
@@ -30477,6 +30478,8 @@ var EnvelopeSchema = exports_external.object({
 // ../contracts/src/handoff-schema.ts
 var HANDOFF_SCHEMA_VERSION = 1;
 var HANDOFF_PHASES = ["architect", "plan", "implement", "test", "review"];
+var PLAN_REVIEW_MAX_ROUNDS = 3;
+var PLAN_REVIEW_VERDICTS = ["approved", "rejected", "failed"];
 var isoTimestamp = exports_external.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
 var handoffPhase = exports_external.enum(HANDOFF_PHASES);
 var nonEmpty = exports_external.string().trim().min(1);
@@ -30513,6 +30516,16 @@ var requiredSkillsSchema = exports_external.object({
   test: exports_external.array(exports_external.string()).optional(),
   review: exports_external.array(exports_external.string()).optional()
 }).passthrough().optional();
+var gapAnalysisSchema = exports_external.object({
+  findings: exports_external.array(exports_external.object({ finding: exports_external.string(), answer: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
+var planReviewSchema = exports_external.object({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number(),
+  remainingIssues: exports_external.array(exports_external.object({ issue: exports_external.string(), evidence: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
 var planSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("plan"),
   taskCount: exports_external.number().optional(),
@@ -30520,7 +30533,9 @@ var planSchema = baseHandoffSchema.extend({
   routingHints: routingHintsSchema,
   concerns: exports_external.array(exports_external.string()).optional(),
   workflowRecommendation: exports_external.string().optional(),
-  requiredSkills: requiredSkillsSchema
+  requiredSkills: requiredSkillsSchema,
+  gapAnalysis: gapAnalysisSchema,
+  planReview: planReviewSchema
 });
 var implementSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("implement"),
@@ -30560,13 +30575,60 @@ var reviewSchema = baseHandoffSchema.extend({
   verdict: exports_external.enum(["approved", "changes_requested"]).optional(),
   keyFindings: exports_external.array(exports_external.object({ severity: exports_external.string(), file: exports_external.string(), description: exports_external.string() }).passthrough()).optional()
 });
-var nonEmptySkillList = exports_external.array(exports_external.string().trim().min(1)).min(1);
+var nonEmptySkillList = exports_external.array(nonEmpty).min(1);
+var recorded = (shape, whatToRecord) => exports_external.object(shape, {
+  error: (issue2) => issue2.input === undefined ? `missing \u2014 record ${whatToRecord}` : undefined
+}).passthrough();
+var gapAnalysisWriteSchema = recorded({
+  findings: exports_external.array(exports_external.object({ finding: nonEmpty, answer: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the gap analyst's `findings`, each with how the plan answers it (`[]` when it found none), or its failed call's `error`").refine((analysis) => analysis.findings === undefined !== (analysis.error === undefined), {
+  message: "record exactly one of `findings` or the failed call's `error`"
+});
+var planReviewWriteSchema = recorded({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number().int().min(1).max(PLAN_REVIEW_MAX_ROUNDS),
+  remainingIssues: exports_external.array(exports_external.object({ issue: nonEmpty, evidence: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the plan review's `verdict` and `rounds`, with `remainingIssues` when it was rejected or `error` when a review's call failed").superRefine((review, ctx) => {
+  const remaining = review.remainingIssues?.length ?? 0;
+  if (review.verdict === "rejected" && remaining === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "a rejected review records the blocking issues its last round named"
+    });
+  }
+  if (review.verdict === "rejected" && review.rounds < PLAN_REVIEW_MAX_ROUNDS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["rounds"],
+      message: `a review still rejecting after ${review.rounds} of ${PLAN_REVIEW_MAX_ROUNDS} rounds is revised and reviewed again, not recorded`
+    });
+  }
+  if (review.verdict === "approved" && remaining > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "an approved review leaves no blocking issue standing"
+    });
+  }
+  if (review.verdict === "failed" !== (review.error !== undefined)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["error"],
+      message: "a failed review records its call's error, and only a failed review does"
+    });
+  }
+});
 var planWriteSchema = planSchema.extend({
   requiredSkills: exports_external.object({
     implement: nonEmptySkillList,
     test: nonEmptySkillList,
     review: nonEmptySkillList
-  }).passthrough()
+  }).passthrough(),
+  gapAnalysis: gapAnalysisWriteSchema,
+  planReview: planReviewWriteSchema
 });
 var phaseHandoffSchema = exports_external.discriminatedUnion("phase", [
   architectSchema,
@@ -31969,7 +32031,8 @@ function renderInbound(raw, sessionID, subject2) {
               replyPath: dispatchReplyPath("message", message2.data.id),
               replyFields: {},
               issueKey: frame.event.issue_key,
-              body: message2.data.body
+              body: message2.data.body,
+              ...typeof message2.data.broadcast_id === "string" ? { broadcastId: message2.data.broadcast_id } : {}
             };
             dispatchReply = {
               tool: "dispatch_message",
@@ -32517,6 +32580,9 @@ class DispatchClient {
   async getMessageThread(id, session) {
     return this.#json("GET", ["api", "v1", "messages", id], undefined, { session });
   }
+  async acceptMessageDelivery(id, attempt, input) {
+    return this.#json("POST", ["api", "v1", "messages", id, "deliveries", String(attempt), "accept"], input);
+  }
   async artifact(issue2, input) {
     const artifactPath = ["api", "v1", "issues", await this.#resolveIssue(issue2), "artifacts"];
     if ("content" in input)
@@ -35236,7 +35302,7 @@ function conversationParts(content) {
   return parts;
 }
 function frameFor(entry) {
-  const { message } = entry;
+  const { dispatchMessageId, message } = entry;
   if (message.role === "toolResult" && message.toolCallId !== undefined) {
     return {
       kind: "tool-result",
@@ -35258,7 +35324,8 @@ function frameFor(entry) {
       id: entry.key.slice(2),
       parts: conversationParts(message.host.content),
       role: message.role === "assistant" ? "assistant" : "user",
-      streaming: entry.streaming
+      streaming: entry.streaming,
+      ...dispatchMessageId === undefined ? {} : { dispatchMessageId }
     },
     seq: entry.seq,
     v: AGENT_STREAM_PROTOCOL
@@ -35287,7 +35354,7 @@ class AgentStreamPublisher {
     this.#publishedAt.clear();
     this.#watchedUntil = 0;
   }
-  record(subject2, raw, streaming) {
+  record(subject2, raw, streaming, dispatchMessageId) {
     const message = readMessage(raw);
     if (message === null)
       return false;
@@ -35300,6 +35367,7 @@ class AgentStreamPublisher {
     this.#seq += 1;
     const entry = {
       at: message.timestamp,
+      dispatchMessageId: dispatchMessageId ?? this.#history.get(key)?.dispatchMessageId,
       key,
       message,
       seq: this.#seq,
@@ -35370,6 +35438,101 @@ function withDispatchFirst(messages, context) {
   ];
 }
 
+// src/dispatch-user-turn.ts
+function isUserTurnCandidate(rendered) {
+  const { delivery } = rendered;
+  return rendered.envelope?.source === "dispatch" && delivery?.resource === "message" && delivery.issueKey === null && delivery.broadcastId === undefined && rendered.dispatchActor?.kind === "user" && (delivery.mode === "aside" || delivery.mode === "steer");
+}
+var AcceptedDeliverySchema = exports_external.object({
+  message_id: exports_external.string(),
+  body: exports_external.string(),
+  delivery: exports_external.enum(["aside", "steer"])
+});
+function turnFromAccept(accepted) {
+  const parsed = AcceptedDeliverySchema.safeParse(accepted);
+  if (!parsed.success)
+    return;
+  return { body: parsed.data.body, messageId: parsed.data.message_id, mode: parsed.data.delivery };
+}
+var HANDLED_ATTEMPT_ENTRY = "envoy-dispatch-handled-attempt";
+function handledAttemptKey(messageId, attempt) {
+  return `${messageId}#${attempt}`;
+}
+function handledAttempts(entries) {
+  const handled = new Set;
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null)
+      continue;
+    if (!("type" in entry) || entry.type !== "custom")
+      continue;
+    if (!("customType" in entry) || entry.customType !== HANDLED_ATTEMPT_ENTRY)
+      continue;
+    if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
+      continue;
+    const { data } = entry;
+    if (!("message_id" in data) || typeof data.message_id !== "string")
+      continue;
+    if (!("attempt" in data) || typeof data.attempt !== "number")
+      continue;
+    handled.add(handledAttemptKey(data.message_id, data.attempt));
+  }
+  return handled;
+}
+function userMessageText(content) {
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content))
+    return "";
+  const pieces = [];
+  for (const part of content) {
+    if (typeof part !== "object" || part === null)
+      continue;
+    if ("type" in part && part.type === "text" && "text" in part && typeof part.text === "string") {
+      pieces.push(part.text);
+    }
+  }
+  return pieces.join(`
+`);
+}
+var INJECTED_USER_TURNS = Symbol.for("legion.pi-envoy.injected-user-turns");
+function injectedUserTurns() {
+  const store = globalThis;
+  const turns = store[INJECTED_USER_TURNS] ?? new Map;
+  store[INJECTED_USER_TURNS] = turns;
+  return turns;
+}
+function noteInjectedUserTurn(sessionID, body, messageId) {
+  const turns = injectedUserTurns();
+  const session = turns.get(sessionID) ?? { found: new Map, sent: [] };
+  session.sent.push({ body, messageId });
+  turns.set(sessionID, session);
+}
+function matchInjectedUserTurn(sessionID, message) {
+  if (typeof message !== "object" || message === null)
+    return;
+  if (!("role" in message) || message.role !== "user")
+    return;
+  if (!("timestamp" in message) || typeof message.timestamp !== "number")
+    return;
+  const session = injectedUserTurns().get(sessionID);
+  if (session === undefined)
+    return;
+  const known = session.found.get(message.timestamp);
+  if (known !== undefined)
+    return known;
+  const text = userMessageText("content" in message ? message.content : undefined);
+  const index = session.sent.findIndex((sent2) => sent2.body === text);
+  const sent = session.sent[index];
+  if (sent === undefined)
+    return;
+  session.sent.splice(index, 1);
+  session.found.set(message.timestamp, sent.messageId);
+  return sent.messageId;
+}
+function endInjectedUserTurns(sessionID) {
+  injectedUserTurns().delete(sessionID);
+}
+
 // src/envoy-session.ts
 import path2 from "path";
 var ENVOY_SESSIONS = Symbol.for("legion.pi-envoy.envoy-session");
@@ -35400,9 +35563,9 @@ function resolveEnvoySession(sessionFile) {
     const parent = `${directory}.jsonl`;
     if (parent === candidate)
       break;
-    const recorded = sessions.get(parent);
-    if (recorded !== undefined)
-      return recorded;
+    const recorded2 = sessions.get(parent);
+    if (recorded2 !== undefined)
+      return recorded2;
     if (path2.dirname(directory) === directory)
       break;
     candidate = parent;
@@ -35626,6 +35789,7 @@ var NATS_RETRY_INTERVAL_MS = 15000;
 var CAPABILITIES_WITHOUT_BTW = DELIVERY_CAPABILITIES.filter((capability) => capability !== "btw");
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
+var USER_TURN_ACCEPT_TIMEOUT_MS = 1e4;
 var LEGION_MANAGED_ENTRY = "legion-managed-session";
 var ASK_REMINDER_MESSAGE = "dispatch-ask-reminder";
 var ASK_PROMPT_LINE_SEPARATOR = /\r\n|[\r\n\u0085\u2028\u2029]/;
@@ -35755,6 +35919,7 @@ function envoyExtension(pi) {
   let runSeq = 0;
   let legionManagedTranscript = false;
   const legionManaged = (id) => legionManagedTranscript || legionRoleClaimBridge().managedSessions.has(id);
+  let handledDispatchAttempts = new Set;
   const availabilityWarningSessionIDs = new Set;
   const warnAskAvailability = (context, error48) => {
     const sessionID2 = context.sessionManager.getSessionId();
@@ -35812,6 +35977,7 @@ function envoyExtension(pi) {
       awarenessGeneration++;
     }
     legionManagedTranscript = branch.some(isLegionManagedEntry);
+    handledDispatchAttempts = handledAttempts(context.sessionManager.getEntries());
   };
   pi.on("resources_discover", async () => ({ skillPaths: [SKILLS_DIRECTORY] }));
   registerEnvoyMessageRenderer(pi);
@@ -35831,6 +35997,34 @@ function envoyExtension(pi) {
   const postDispatchReply = async (delivery, result) => {
     await postDeliveryReply(currentDispatchConfig(), sessionID, delivery, result);
   };
+  const acceptedUserTurn = async (rendered) => {
+    if (!isUserTurnCandidate(rendered))
+      return;
+    const { delivery } = rendered;
+    const key = handledAttemptKey(delivery.id, delivery.attempt);
+    if (handledDispatchAttempts.has(key)) {
+      logger.warn("envoy: a frame names a Dispatch attempt this session already delivered; it arrives as a card", { attempt: delivery.attempt, messageID: delivery.id });
+      return;
+    }
+    handledDispatchAttempts.add(key);
+    pi.appendEntry(HANDLED_ATTEMPT_ENTRY, { attempt: delivery.attempt, message_id: delivery.id });
+    try {
+      const config2 = activeDispatchConfig(process.env, { cwd: process.cwd() });
+      if (config2 === null)
+        return;
+      const accepted = await new DispatchClient(config2.url, config2.token, fetch, AbortSignal.timeout(USER_TURN_ACCEPT_TIMEOUT_MS)).acceptMessageDelivery(delivery.id, delivery.attempt, {
+        actor: { id: sessionID, kind: "session" }
+      });
+      const turn = turnFromAccept(accepted);
+      if (turn === undefined) {
+        logger.warn("envoy: Dispatch accepted a direct message without the stored body and mode to inject; it arrives as a card", { attempt: delivery.attempt, messageID: delivery.id });
+      }
+      return turn;
+    } catch (error48) {
+      logger.warn("envoy: Dispatch did not accept a direct message as this session's turn; it arrives as a card", { attempt: delivery.attempt, messageID: delivery.id, error: messageFor(error48) });
+      return;
+    }
+  };
   const deliver = async (subject2, raw, reply) => {
     const rendered = renderInbound(raw, sessionID, subject2);
     const directSubject = agentSubject(sessionID);
@@ -35889,10 +36083,16 @@ function envoyExtension(pi) {
             }
           }
         } else {
-          pi.sendMessage({ customType: "envoy-message", content: rendered.content, display: true }, {
-            deliverAs: rendered.delivery?.mode === "aside" ? "aside" : "steer",
-            triggerTurn: true
-          });
+          const turn = await acceptedUserTurn(rendered);
+          if (turn === undefined) {
+            pi.sendMessage({ customType: "envoy-message", content: rendered.content, display: true }, {
+              deliverAs: rendered.delivery?.mode === "aside" ? "aside" : "steer",
+              triggerTurn: true
+            });
+          } else {
+            noteInjectedUserTurn(sessionID, turn.body, turn.messageId);
+            pi.sendUserMessage(turn.body, turn.mode === "aside" ? { deliverAs: "aside" } : undefined);
+          }
         }
       } catch (error48) {
         console.warn(`[envoy] failed to deliver envelope ${envelope2?.event_id ?? "unknown"}`, error48);
@@ -36018,7 +36218,7 @@ function envoyExtension(pi) {
   const recordAgentStreamMessage = (message, streaming) => {
     if (sessionID === "")
       return;
-    agentStream.record(agentStreamFramesSubject(sessionID), message, streaming);
+    agentStream.record(agentStreamFramesSubject(sessionID), message, streaming, matchInjectedUserTurn(sessionID, message));
   };
   pi.on("message_start", async (event) => {
     recordAgentStreamMessage(event.message, true);
@@ -36495,6 +36695,7 @@ function envoyExtension(pi) {
   }
   pi.on("agent_end", async (event, context) => {
     const id = context.sessionManager.getSessionId();
+    endInjectedUserTurns(sessionID);
     const lastReply = event.messages?.findLast((message) => message.role === "assistant");
     const ask = sideTurn(pi, context);
     if (event.willContinue === true || lastReply?.stopReason !== "stop" || !context.hasUI || id === "" || ask === undefined || !checkOwed(id)) {

package/dist/legion.js

@@ -29965,6 +29965,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
   body: exports_external.string(),
   target: exports_external.string(),
   in_reply_to: exports_external.string().nullable(),
+  broadcast_id: exports_external.string().nullish(),
   deliveries: exports_external.array(exports_external.unknown()),
   created_at: exports_external.string()
 });
@@ -30646,6 +30647,8 @@ var EnvelopeSchema = exports_external.object({
 // ../contracts/src/handoff-schema.ts
 var HANDOFF_SCHEMA_VERSION = 1;
 var HANDOFF_PHASES = ["architect", "plan", "implement", "test", "review"];
+var PLAN_REVIEW_MAX_ROUNDS = 3;
+var PLAN_REVIEW_VERDICTS = ["approved", "rejected", "failed"];
 var isoTimestamp = exports_external.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
 var handoffPhase = exports_external.enum(HANDOFF_PHASES);
 var nonEmpty = exports_external.string().trim().min(1);
@@ -30682,6 +30685,16 @@ var requiredSkillsSchema = exports_external.object({
   test: exports_external.array(exports_external.string()).optional(),
   review: exports_external.array(exports_external.string()).optional()
 }).passthrough().optional();
+var gapAnalysisSchema = exports_external.object({
+  findings: exports_external.array(exports_external.object({ finding: exports_external.string(), answer: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
+var planReviewSchema = exports_external.object({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number(),
+  remainingIssues: exports_external.array(exports_external.object({ issue: exports_external.string(), evidence: exports_external.string() }).passthrough()).optional(),
+  error: exports_external.string().optional()
+}).passthrough().optional();
 var planSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("plan"),
   taskCount: exports_external.number().optional(),
@@ -30689,7 +30702,9 @@ var planSchema = baseHandoffSchema.extend({
   routingHints: routingHintsSchema,
   concerns: exports_external.array(exports_external.string()).optional(),
   workflowRecommendation: exports_external.string().optional(),
-  requiredSkills: requiredSkillsSchema
+  requiredSkills: requiredSkillsSchema,
+  gapAnalysis: gapAnalysisSchema,
+  planReview: planReviewSchema
 });
 var implementSchema = baseHandoffSchema.extend({
   phase: exports_external.literal("implement"),
@@ -30729,13 +30744,60 @@ var reviewSchema = baseHandoffSchema.extend({
   verdict: exports_external.enum(["approved", "changes_requested"]).optional(),
   keyFindings: exports_external.array(exports_external.object({ severity: exports_external.string(), file: exports_external.string(), description: exports_external.string() }).passthrough()).optional()
 });
-var nonEmptySkillList = exports_external.array(exports_external.string().trim().min(1)).min(1);
+var nonEmptySkillList = exports_external.array(nonEmpty).min(1);
+var recorded = (shape, whatToRecord) => exports_external.object(shape, {
+  error: (issue2) => issue2.input === undefined ? `missing \u2014 record ${whatToRecord}` : undefined
+}).passthrough();
+var gapAnalysisWriteSchema = recorded({
+  findings: exports_external.array(exports_external.object({ finding: nonEmpty, answer: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the gap analyst's `findings`, each with how the plan answers it (`[]` when it found none), or its failed call's `error`").refine((analysis) => analysis.findings === undefined !== (analysis.error === undefined), {
+  message: "record exactly one of `findings` or the failed call's `error`"
+});
+var planReviewWriteSchema = recorded({
+  verdict: exports_external.enum(PLAN_REVIEW_VERDICTS),
+  rounds: exports_external.number().int().min(1).max(PLAN_REVIEW_MAX_ROUNDS),
+  remainingIssues: exports_external.array(exports_external.object({ issue: nonEmpty, evidence: nonEmpty }).passthrough()).optional(),
+  error: nonEmpty.optional()
+}, "the plan review's `verdict` and `rounds`, with `remainingIssues` when it was rejected or `error` when a review's call failed").superRefine((review, ctx) => {
+  const remaining = review.remainingIssues?.length ?? 0;
+  if (review.verdict === "rejected" && remaining === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "a rejected review records the blocking issues its last round named"
+    });
+  }
+  if (review.verdict === "rejected" && review.rounds < PLAN_REVIEW_MAX_ROUNDS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["rounds"],
+      message: `a review still rejecting after ${review.rounds} of ${PLAN_REVIEW_MAX_ROUNDS} rounds is revised and reviewed again, not recorded`
+    });
+  }
+  if (review.verdict === "approved" && remaining > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["remainingIssues"],
+      message: "an approved review leaves no blocking issue standing"
+    });
+  }
+  if (review.verdict === "failed" !== (review.error !== undefined)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["error"],
+      message: "a failed review records its call's error, and only a failed review does"
+    });
+  }
+});
 var planWriteSchema = planSchema.extend({
   requiredSkills: exports_external.object({
     implement: nonEmptySkillList,
     test: nonEmptySkillList,
     review: nonEmptySkillList
-  }).passthrough()
+  }).passthrough(),
+  gapAnalysis: gapAnalysisWriteSchema,
+  planReview: planReviewWriteSchema
 });
 var phaseHandoffSchema = exports_external.discriminatedUnion("phase", [
   architectSchema,
@@ -31423,6 +31485,9 @@ class DispatchClient {
   async getMessageThread(id, session) {
     return this.#json("GET", ["api", "v1", "messages", id], undefined, { session });
   }
+  async acceptMessageDelivery(id, attempt, input) {
+    return this.#json("POST", ["api", "v1", "messages", id, "deliveries", String(attempt), "accept"], input);
+  }
   async artifact(issue2, input) {
     const artifactPath = ["api", "v1", "issues", await this.#resolveIssue(issue2), "artifacts"];
     if ("content" in input)
@@ -33611,7 +33676,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.28.0",
+  version: "5.30.0",
   type: "module",
   omp: {
     extensions: [
@@ -33656,6 +33721,101 @@ var package_default = {
   }
 };
 
+// src/dispatch-user-turn.ts
+function isUserTurnCandidate(rendered) {
+  const { delivery } = rendered;
+  return rendered.envelope?.source === "dispatch" && delivery?.resource === "message" && delivery.issueKey === null && delivery.broadcastId === undefined && rendered.dispatchActor?.kind === "user" && (delivery.mode === "aside" || delivery.mode === "steer");
+}
+var AcceptedDeliverySchema = exports_external.object({
+  message_id: exports_external.string(),
+  body: exports_external.string(),
+  delivery: exports_external.enum(["aside", "steer"])
+});
+function turnFromAccept(accepted) {
+  const parsed = AcceptedDeliverySchema.safeParse(accepted);
+  if (!parsed.success)
+    return;
+  return { body: parsed.data.body, messageId: parsed.data.message_id, mode: parsed.data.delivery };
+}
+var HANDLED_ATTEMPT_ENTRY = "envoy-dispatch-handled-attempt";
+function handledAttemptKey(messageId, attempt) {
+  return `${messageId}#${attempt}`;
+}
+function handledAttempts(entries) {
+  const handled = new Set;
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null)
+      continue;
+    if (!("type" in entry) || entry.type !== "custom")
+      continue;
+    if (!("customType" in entry) || entry.customType !== HANDLED_ATTEMPT_ENTRY)
+      continue;
+    if (!("data" in entry) || typeof entry.data !== "object" || entry.data === null)
+      continue;
+    const { data } = entry;
+    if (!("message_id" in data) || typeof data.message_id !== "string")
+      continue;
+    if (!("attempt" in data) || typeof data.attempt !== "number")
+      continue;
+    handled.add(handledAttemptKey(data.message_id, data.attempt));
+  }
+  return handled;
+}
+function userMessageText(content) {
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content))
+    return "";
+  const pieces = [];
+  for (const part of content) {
+    if (typeof part !== "object" || part === null)
+      continue;
+    if ("type" in part && part.type === "text" && "text" in part && typeof part.text === "string") {
+      pieces.push(part.text);
+    }
+  }
+  return pieces.join(`
+`);
+}
+var INJECTED_USER_TURNS = Symbol.for("legion.pi-envoy.injected-user-turns");
+function injectedUserTurns() {
+  const store = globalThis;
+  const turns = store[INJECTED_USER_TURNS] ?? new Map;
+  store[INJECTED_USER_TURNS] = turns;
+  return turns;
+}
+function noteInjectedUserTurn(sessionID, body, messageId) {
+  const turns = injectedUserTurns();
+  const session = turns.get(sessionID) ?? { found: new Map, sent: [] };
+  session.sent.push({ body, messageId });
+  turns.set(sessionID, session);
+}
+function matchInjectedUserTurn(sessionID, message) {
+  if (typeof message !== "object" || message === null)
+    return;
+  if (!("role" in message) || message.role !== "user")
+    return;
+  if (!("timestamp" in message) || typeof message.timestamp !== "number")
+    return;
+  const session = injectedUserTurns().get(sessionID);
+  if (session === undefined)
+    return;
+  const known = session.found.get(message.timestamp);
+  if (known !== undefined)
+    return known;
+  const text = userMessageText("content" in message ? message.content : undefined);
+  const index = session.sent.findIndex((sent2) => sent2.body === text);
+  const sent = session.sent[index];
+  if (sent === undefined)
+    return;
+  session.sent.splice(index, 1);
+  session.found.set(message.timestamp, sent.messageId);
+  return sent.messageId;
+}
+function endInjectedUserTurns(sessionID) {
+  injectedUserTurns().delete(sessionID);
+}
+
 // src/legion/classify.ts
 function classifySession(env) {
   if (env.LEGION_CONTROLLER !== undefined && env.LEGION_TREE !== undefined) {
@@ -35777,7 +35937,8 @@ function legionExtension(pi) {
   pi.on("message_start", async (event, context) => {
     if (!phaseWorkerSession(context))
       return;
-    const kind = inboundKind(event.message);
+    const injected = matchInjectedUserTurn(context.sessionManager.getSessionId(), event.message) !== undefined;
+    const kind = injected ? "inbound-event" : inboundKind(event.message);
     if (kind !== undefined)
       advancePhaseStall({ kind });
   });

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

@@ -6,7 +6,8 @@ human messages you directly from the Agents page.
 ## Targeted agent messages
 
 A human — or any bearer caller over HTTP, such as a test rig — can target the issue message at a
-live Envoy session or role as **BTW**, **Aside**, or **Steer**. The incoming Dispatch frame names
+live Envoy session or role as **BTW**, **Aside**, or **Steer** (the dashboard calls a steer
+**Send**). The incoming Dispatch frame names
 the issue and includes a `reply_with` hint (`{ tool, args }`, ready to issue on any host); reply on the same open issue with the existing
 tool, never a new targeted send:
 
@@ -32,9 +33,17 @@ target only a session that advertises the mode you want. Sending to a session wi
 
 ## Answering a direct message
 
-A human can also message you directly from the **Agents** page, with no issue at all. That frame
-names no issue and its `reply_with` hint carries none either; answer it with the message's bare
-id in `in_reply_to`, alone:
+A human can also message you directly from the **Agents** page, with no issue at all. On Oh My
+Pi, a person's **Send** or **Aside** arrives as their own user message, exactly as if they had
+typed it at your terminal: your Envoy plugin takes it only once Dispatch accepts it as a person's
+own fresh message to you, and injects the text Dispatch stored. Answer it in the conversation as
+you would anything typed, with no `dispatch_message`; the Agents page shows your conversation
+live, so they read your answer there.
+
+Everything else still arrives as a Dispatch frame: a **BTW**, a broadcast, a direct message on a
+host that takes no user turn from its plugin (Claude Code), and one Dispatch did not accept.
+That frame names no issue and its `reply_with` hint carries none either; answer it with the
+message's bare id in `in_reply_to`, alone:
 
 ```ts
 dispatch_message({

package/package.json

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