@sjawhar/pi-legion-envoy 5.1.0 → 5.2.0

package/dist/envoy.js

@@ -34979,8 +34979,15 @@ var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
 var LEGION_MANAGED_ENTRY = "legion-managed-session";
 var ASK_REMINDER_MESSAGE = "dispatch-ask-reminder";
-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.";
+var ASK_SELF_CHECK_PROMPT = "Your run has just ended. Answer with exactly one word and nothing else: WAITING or PROCEEDING. " + "WAITING \u2014 you stopped because you need a decision, an approval, or information from a human. " + "PROCEEDING \u2014 you finished, you will carry on by yourself, or you are waiting only on tools, " + "subagents, or events.";
+var WAITING_VERDICT = /^\W*WAITING\b/;
+var ECHOED_CHOICE = /\bPROCEEDING\b/;
+var isWaitingVerdict = (reply) => WAITING_VERDICT.test(reply) && !ECHOED_CHOICE.test(reply);
+var ASK_SELF_CHECK_TIMEOUT_MS = 60000;
+var ASK_CHECKS_PER_PERIOD = 5;
+var UNASKED_WAIT_REMINDER = "You just said you are waiting on a human, but you have no open ask in Dispatch, so nobody knows you are waiting. Open it now with dispatch_ask \u2014 or dispatch_request_approval when what you need is approval of a document \u2014 naming exactly what you need and from whom. Do not reply just to acknowledge this reminder.";
 var ASK_OPENING_TOOLS = ["dispatch_ask", "dispatch_request_approval"];
+var DISPATCH_TOOL_PREFIX = "dispatch_";
 function isLegionManagedEntry(entry) {
   if (typeof entry !== "object" || entry === null)
     return false;
@@ -35051,11 +35058,23 @@ function envoyExtension(pi) {
     session_id: "",
     period: 0,
     baseline_as_of: null,
-    fired: false,
-    saw_ask: false
+    check_due: false,
+    checks: 0
   };
   let awarenessGeneration = 0;
   let askCheckInFlight = false;
+  let settledDuringCheck;
+  const takeSettledDuringCheck = () => {
+    const settle = settledDuringCheck;
+    settledDuringCheck = undefined;
+    return settle;
+  };
+  let askCheckAbort;
+  const abortSelfCheck = (reason) => {
+    askCheckAbort?.abort(new Error(reason));
+    askCheckAbort = undefined;
+  };
+  let runSeq = 0;
   let legionManagedTranscript = false;
   const legionManaged = (id) => legionManagedTranscript || legionRoleClaimBridge().managedSessions.has(id);
   const availabilityWarningSessionIDs = new Set;
@@ -35066,6 +35085,19 @@ function envoyExtension(pi) {
     availabilityWarningSessionIDs.add(sessionID2);
     context.ui.notify(`envoy: Dispatch open-ask check unavailable (${messageFor(error48)}); the stop-time ask reminder is off until it recovers`, "warning");
   };
+  const askEphemeral = pi.askEphemeral;
+  const overriddenTimeout = Number(process.env.ENVOY_SELF_CHECK_TIMEOUT_MS);
+  const selfCheckTimeoutMs = Number.isFinite(overriddenTimeout) && overriddenTimeout > 0 ? overriddenTimeout : ASK_SELF_CHECK_TIMEOUT_MS;
+  const selfCheckWarningSessionIDs = new Set;
+  const logSelfCheckFailure = (failedSessionID, error48) => {
+    if (selfCheckWarningSessionIDs.has(failedSessionID))
+      return;
+    selfCheckWarningSessionIDs.add(failedSessionID);
+    logger.warn("envoy: run-end waiting self-check failed; no reminder was sent", {
+      sessionID: failedSessionID,
+      error: messageFor(error48)
+    });
+  };
   const queryOpenAsks = async (requestedSessionID, since) => {
     const config2 = activeDispatchConfig();
     if (config2 === null)
@@ -35086,15 +35118,18 @@ function envoyExtension(pi) {
     sessionID = context.sessionManager.getSessionId();
     activeSessionContext = context;
     const branch = context.sessionManager.getBranch?.() ?? [];
-    askAwareness = {
-      session_id: sessionID,
-      period: 0,
-      baseline_as_of: null,
-      fired: false,
-      saw_ask: false
-    };
+    if (askAwareness.session_id !== sessionID) {
+      abortSelfCheck(`session changed from ${askAwareness.session_id || "none"} to ${sessionID}`);
+      askAwareness = {
+        session_id: sessionID,
+        period: 0,
+        baseline_as_of: null,
+        check_due: false,
+        checks: 0
+      };
+      awarenessGeneration++;
+    }
     legionManagedTranscript = branch.some(isLegionManagedEntry);
-    awarenessGeneration++;
   };
   pi.on("resources_discover", async () => ({ skillPaths: [SKILLS_DIRECTORY] }));
   registerEnvoyMessageRenderer(pi);
@@ -35610,69 +35645,148 @@ function envoyExtension(pi) {
   registerEnvoyWhoamiCommand(pi, () => sessionID);
   pi.on("before_agent_start", async (event, context) => {
     const id = context.sessionManager.getSessionId();
-    if (id === "" || event.prompt.trim() === "" || !context.hasUI || legionManaged(id)) {
+    if (id === "" || event.prompt.trim() === "" || !context.hasUI || askEphemeral === undefined || legionManaged(id)) {
       return;
     }
     if (await isSubagent(context))
       return;
+    awarenessGeneration++;
+    abortSelfCheck("a new user turn superseded the self-check");
     try {
       const open = await queryOpenAsks(id);
       if (open !== null)
-        armAskAwareness(id, event.prompt, open.snapshot.as_of);
+        armAskAwareness(id, open.snapshot.as_of);
     } catch (error48) {
       warnAskAvailability(context, error48);
     }
     return;
   });
-  function armAskAwareness(id, prompt, asOf) {
-    if (prompt.trim() === "")
-      return;
-    awarenessGeneration++;
+  pi.on("agent_start", async () => {
+    runSeq += 1;
+  });
+  function armAskAwareness(id, asOf) {
     askAwareness = {
       session_id: id,
       period: (askAwareness.session_id === id ? askAwareness.period : 0) + 1,
       baseline_as_of: asOf,
-      fired: false,
-      saw_ask: false
+      check_due: true,
+      checks: 0
     };
   }
   pi.on("agent_end", async (event, context) => {
     const id = context.sessionManager.getSessionId();
     const lastReply = event.messages?.findLast((message) => message.role === "assistant");
-    if (event.willContinue === true || lastReply?.stopReason !== "stop" || shuttingDown || !context.hasUI || id === "" || id !== sessionID || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period === 0 || askAwareness.fired || askAwareness.saw_ask || askAwareness.baseline_as_of === null || askCheckInFlight) {
+    if (event.willContinue === true || lastReply?.stopReason !== "stop" || !context.hasUI || id === "" || !checkOwed(id)) {
+      return;
+    }
+    if (askCheckInFlight) {
+      settledDuringCheck = { context, seenRun: runSeq };
       return;
     }
-    const period = askAwareness.period;
-    const generation = awarenessGeneration;
     askCheckInFlight = true;
     try {
-      let open;
-      try {
-        open = await queryOpenAsks(id, askAwareness.baseline_as_of);
-      } catch (error48) {
-        if (generation === awarenessGeneration)
-          warnAskAvailability(context, error48);
-        return;
-      }
-      if (open === null || shuttingDown || generation !== awarenessGeneration || sessionID !== id || context.sessionManager.getSessionId() !== id || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period !== period || askAwareness.fired || askAwareness.saw_ask) {
-        return;
+      let settle = { context, seenRun: runSeq };
+      while (settle !== undefined) {
+        await checkAtSettle(id, settle);
+        settle = takeSettledDuringCheck();
+        if (settle?.context.sessionManager.getSessionId() !== id || settle.seenRun !== runSeq || !checkOwed(id)) {
+          settle = undefined;
+        }
       }
-      if (open.snapshot.count > 0 || open.snapshot.opened_since)
-        return;
-      askAwareness = { ...askAwareness, fired: true };
-      pi.sendMessage({ customType: ASK_REMINDER_MESSAGE, content: OPEN_ASKS_REMINDER, display: false }, { deliverAs: "steer", triggerTurn: true });
     } finally {
       askCheckInFlight = false;
+      settledDuringCheck = undefined;
     }
   });
+  function checkOwed(id) {
+    return !(shuttingDown || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period === 0 || !askAwareness.check_due || askAwareness.checks >= ASK_CHECKS_PER_PERIOD || askAwareness.baseline_as_of === null || askEphemeral === undefined);
+  }
+  async function checkAtSettle(id, settle) {
+    const { context, seenRun } = settle;
+    const period = askAwareness.period;
+    const generation = awarenessGeneration;
+    const baseline = askAwareness.baseline_as_of;
+    if (baseline === null || askEphemeral === undefined)
+      return;
+    const stale = () => shuttingDown || generation !== awarenessGeneration || context.sessionManager.getSessionId() !== id || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period !== period || !askAwareness.check_due;
+    let open;
+    try {
+      open = await queryOpenAsks(id, baseline);
+    } catch (error48) {
+      if (generation === awarenessGeneration)
+        warnAskAvailability(context, error48);
+      return;
+    }
+    if (open === null || stale())
+      return;
+    if (runSeq !== seenRun)
+      return;
+    if (open.snapshot.count > 0 || open.snapshot.opened_since) {
+      askAwareness = {
+        ...askAwareness,
+        check_due: false,
+        baseline_as_of: open.snapshot.as_of
+      };
+      return;
+    }
+    const abort = new AbortController;
+    askCheckAbort = abort;
+    let answered;
+    try {
+      answered = askEphemeral({ prompt: ASK_SELF_CHECK_PROMPT, signal: abort.signal }).then((reply) => reply.replyText, (error48) => {
+        if (!abort.signal.aborted)
+          logSelfCheckFailure(id, error48);
+        return;
+      });
+    } catch (error48) {
+      logSelfCheckFailure(id, error48);
+      answered = Promise.resolve(undefined);
+    }
+    const expiry = Promise.withResolvers();
+    const expire = setTimeout(() => {
+      const timedOut = new Error(`self-check timed out after ${selfCheckTimeoutMs} ms`);
+      abort.abort(timedOut);
+      logSelfCheckFailure(id, timedOut);
+      expiry.resolve(undefined);
+    }, selfCheckTimeoutMs);
+    let verdict;
+    try {
+      verdict = await Promise.race([answered, expiry.promise]);
+    } finally {
+      clearTimeout(expire);
+      if (askCheckAbort === abort)
+        askCheckAbort = undefined;
+    }
+    if (stale()) {
+      abort.abort(new Error("the self-check was superseded before its verdict arrived"));
+      return;
+    }
+    const superseded = runSeq !== seenRun;
+    askAwareness = {
+      ...askAwareness,
+      check_due: superseded,
+      checks: askAwareness.checks + 1,
+      baseline_as_of: open.snapshot.as_of
+    };
+    if (superseded)
+      return;
+    if (verdict === undefined || !isWaitingVerdict(verdict.trim()))
+      return;
+    pi.sendMessage({ customType: ASK_REMINDER_MESSAGE, content: UNASKED_WAIT_REMINDER, display: false }, { deliverAs: "steer", triggerTurn: true });
+  }
   const announceFollow = createFollowAnnouncer((text) => {
     pi.sendMessage({ customType: "envoy-message", content: text, display: true, details: LOCAL_ENVOY_NOTICE }, { deliverAs: "steer", triggerTurn: false });
   });
-  pi.on("tool_result", async (event) => {
+  pi.on("tool_result", async (event, context) => {
     if (event.isError)
       return;
-    if (ASK_OPENING_TOOLS.includes(event.toolName) && askAwareness.session_id === sessionID && askAwareness.period > 0 && !askAwareness.saw_ask) {
-      askAwareness = { ...askAwareness, saw_ask: true };
+    if (askAwareness.session_id === context.sessionManager.getSessionId() && askAwareness.period > 0) {
+      if (ASK_OPENING_TOOLS.includes(event.toolName)) {
+        askAwareness = { ...askAwareness, check_due: false };
+        abortSelfCheck("the agent opened the ask itself");
+      } else if (!event.toolName.startsWith(DISPATCH_TOOL_PREFIX)) {
+        askAwareness = { ...askAwareness, check_due: true };
+      }
     }
     announceFollow(event.details);
   });

package/dist/legion.js

@@ -16142,7 +16142,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.1.0",
+  version: "5.2.0",
   type: "module",
   omp: {
     extensions: [

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

@@ -233,8 +233,7 @@ Preserve this order exactly:
 
 1. tester green and review cycles complete;
 2. on a clean review, `spawn_worker` the implementer once more to push only the `.legion/`
-   deletion (only the implementer pushes the issue branch), then the reviewer approves that
-   head. The deletion must land before that approval, which is head-pinned. An implementer
+   deletion, then the reviewer approves that head. The deletion must land before that approval, which is head-pinned. An implementer
    completion advances the status only from `in_progress` to `testing`; this push, like retro
    later, leaves the status where it is, so you set nothing by hand — on its `phase-complete`
    wake, `spawn_worker` the reviewer to approve that head (a finished reviewer may already be
@@ -259,8 +258,8 @@ What returns the tree to review: a changed diff — a commit above the approved
 touches anything outside `docs/solutions/`, or a rebase whose fingerprint
 (`skill://legion-worker`'s unchanged-diff check) differs from the approved head's. What does not: retro's
 `docs/solutions/` commit, and a rebase forced by a GitHub-reported conflict whose fingerprint
-is unchanged. For that rebase the order is: the implementer rebases and posts the before/after
-fingerprints; the tester re-runs the bare gates only; the reviewer confirms and approves the new
+is unchanged. For that rebase the order is: the implementer rebases, pushes the rebased chain with
+`legion-worker`'s procedure for rewritten commits, and posts the before/after fingerprints; the tester re-runs the bare gates only; the reviewer confirms and approves the new
 head by SHA (or continues its round if it had not approved); the merger republishes READY.
 Retro does not re-run. A rebase happens only when GitHub reports `CONFLICTING`
 (`legion gh -- pr view <n> --json mergeable,mergeStateStatus`); read that on every end-game
@@ -271,8 +270,9 @@ it. Do not let the merger publish `READY` for an obsolete approval.
 If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused
 to resolve, open a `dispatch_ask` that names the thread's URL and GitHub's message for a human to
 resolve it by hand, with options for resolved / could not; the merger does not publish while it
-is open. That is the one review-thread step a human takes: the review App cannot resolve threads,
-and the implementer's and merger's runs of the command close every accepted one.
+is open. That is the one review-thread step a human takes: the review App cannot resolve a thread
+on a pull request the implementer opened, and the implementer's and merger's runs of the command
+close every accepted one.
 
 ## 7. Close
 
@@ -311,7 +311,7 @@ active phase worker.
 | `worker-recovered` | Payload `{type:"worker-recovered", issue, role, fromRef, delivery?}`. The worker's tree volume was lost and the daemon replaced it from the committed handoff on `fromRef`. `delivery: "spawned"` means the current assignment was preserved on the new worker; do not resend it. `delivery: "queued"` means that preserved assignment awaits capacity; wait for `worker-started`. Without `delivery`, inspect `.legion/` and the active phase before deciding whether work needs a new assignment. |
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
 | `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |
-| `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count; a push the daemon cannot classify (a listener without `changed_paths`, a list capped at 100, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
+| `pr-blocked` | Payload `{type:"pr-blocked", pr, attempts}`. `attempts` counts heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list capped at 100, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
 | `pr-merged` | Payload `{type:"pr-merged", pr, mergeCommitSha}`. The PR merged because a human merged it under the repository's rules. `spawn_worker` the **implementer** with the production-check task naming that merge commit (it resumes the same agent; a retired role has no live holder, so never `envoy_publish` for this). Its `phase-complete` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it and set the issue `done`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
 | `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |

package/dist/skills/legion-worker/SKILL.md

@@ -232,15 +232,9 @@ commit is `plan: record handoff`.
 
 ## Implementer push and pull request
 
-Only the implementer creates the issue bookmark, pushes it, and opens the pull request.
-After its implementation commit and verification, it uses this exact branch name and push
-procedure:
-
-```bash
-cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
-```
+The implementer opens the pull request. After its implementation commit and verification, it
+pushes the issue branch under this exact name with the one push procedure every role uses
+(*Every role pushes its own commits*, below).
 
 The provisioned issue workspace configures `credential.helper` with the daemon's absolute
 credential command, so `jj -R "$LEGION_WORKSPACE" git push` authenticates transparently
@@ -286,7 +280,7 @@ Verified the implementer's proof by <re-running its command | driving the same s
 **Fast-follow:** <one named cleanup item and where it will land>, or "none".
 
 **Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
-**Retarget:** Retargeting a pull request to a new base does not re-run Tests; after a retarget, rebase onto the new base and push — the new head runs Tests against the new merge result — and cite that run in the PR body.
+**Retarget:** Retargeting a pull request to a new base does not re-run Tests; after a retarget, record the pushed tip, rebase onto the new base, and push with `legion-worker`'s procedure for rewritten commits — the new head runs Tests against the new merge result — and cite that run in the PR body.
 ```
 
 **A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
@@ -314,9 +308,9 @@ this proof.
   `Accepted: not a defect — <reason>`, or `Still open: <what remains>`; nothing else is an
   acceptance, and nobody replies after an `Accepted:` (any later reply that is not itself an
   `Accepted:` — the opener's own follow-up included — leaves the thread open, since the command
-  reads only the newest comment). The review App can reply on a thread, but GitHub refuses it
-  `resolveReviewThread` (its token reads `viewerCanResolve: false`), and the workflow gives
-  pushing to the implementer alone (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps) — so the
+  reads only the newest comment). The review App can reply on a thread but cannot resolve it:
+  GitHub grants resolving a review thread to the pull request's author, and the implementer opens
+  every Legion pull request (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps). So the
   **implementer** runs `legion threads resolve --pr <number> --repo <owner>/<repo>` before every
   push that answers a review (the corrective push and the final `.legion/` deletion push) and
   pastes its output into the `Threads` section. The command resolves each unresolved thread
@@ -341,7 +335,8 @@ this proof.
   tip; post one PR comment (Legion footer):
   `rebase <old-tip-sha> → <new-tip-sha>; fingerprint <before> → <after>; unchanged|changed`.
   Rebase the whole chain — `jj -R "$LEGION_WORKSPACE" rebase -s 'roots(main@origin..@)' -d main@origin` —
-  so the tester's and reviewer's commits move with yours.
+  so the tester's and reviewer's commits move with yours. Record the pushed tip before it and
+  push the rebased chain with the push procedure (*Rewriting pushed commits*, below).
 - **No deferrals.** Sami, 2026-09-11, verbatim: "My rule is no deferrals." The `Fast-follow:`
   field names naming, duplication, or wording cleanup only; anything that changes behaviour,
   hides an error, or breaks a gate lands in this PR.
@@ -399,8 +394,7 @@ this proof.
   Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
   finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
   Then return the issue to the architect; when clean, have the architect send the implementer
-  back to push the `.legion/` deletion (only the implementer pushes the issue branch), then review **that** head
-  and approve it by name. After a conflict-forced rebase, compute the fingerprint at the
+  back to push the `.legion/` deletion, then review **that** head and approve it by name. After a conflict-forced rebase, compute the fingerprint at the
   `commit_id` of your last submitted review and at the new head. Equal and that review was
   `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
   and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
@@ -535,29 +529,61 @@ cd -- "$LEGION_WORKSPACE" && \
   jj -R "$LEGION_WORKSPACE" split -m "<phase>: record handoff" .legion/<phase>.json
 ```
 
-**Only the implementer pushes the issue branch.** It acts as the code-writing App
-(`legion-implementer[bot]`, `appRoleForLegionRole` in `packages/daemon/src/daemon/github-apps.ts`),
-the one role the workflow lets push (the review App's installation holds `contents: write` too, but
-no role acting as it pushes; the merger acts as the implement App but pushes nothing: it
-verifies and publishes READY). If you are the implementer, advance the issue bookmark and push it
-with the provisioned credential helper. `--bookmark` also publishes the locally provisioned
-bookmark on its first push — a bookmark not yet tracking a remote one is tracked automatically:
+**Every role pushes its own commits.** After the handoff commit — and, for the tester, the red
+tests it wrote — advance the issue bookmark and push it with the provisioned credential helper,
+which authenticates as your role's App (`appRoleForLegionRole` in
+`packages/daemon/src/daemon/github-apps.ts`). `-r @-` puts the bookmark on the commit you just
+split off: the working copy left above it has no description, and `jj git push` refuses a
+commit without one. `--allow-backwards` is for that local step alone: after a split the bookmark
+can sit on the undescribed working copy above `@-`. `--bookmark` also publishes the locally
+provisioned bookmark on its first push — a bookmark not yet tracking a remote one is tracked
+automatically. This is the one push procedure; every push of the issue branch uses it:
 
 ```bash
 cd -- "$LEGION_WORKSPACE" && \
-  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> && \
-  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
+  tip_file="${TMPDIR:-/tmp}/legion-<KEY>-$LEGION_ROLE-rewritten-tip" && \
+  old=$(cat -- "$tip_file" 2>/dev/null || true) && \
+  behind=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
+    -r "remote_bookmarks(exact:\"legion/<KEY>\", exact:\"origin\") ~ (::@-${old:+ | $old})") && \
+  { [ -z "$behind" ] || { echo "legion/<KEY>@origin is at $behind, which @- does not descend from" >&2; false; }; } && \
+  jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- --allow-backwards && \
+  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY> && \
+  rm -f -- "$tip_file"
 ```
 
-Every other role — planner, tester, reviewer, architects — acts as the review App
-(`legion-reviewer[bot]`) and never pushes: the `split` above is your last step, and the commit
-rides the implementer's next push (the corrective push after a review, or the final `.legion/`
-deletion). GitHub does not stop a push from one of those roles: the review App's installation
-holds `contents: write`, so the push would succeed. The rule is the workflow's, and nothing but
-the rule enforces it.
+The `behind` check refuses unless `@-` descends from `legion/<KEY>@origin` (or the branch is not
+on GitHub yet). Every issue workspace shares one clone, so another role's push moves
+`legion/<KEY>@origin` here at once. With the flag and no check, `jj git push` then moves the
+remote branch sideways onto your commit and drops theirs (jj 0.45.1:
+`bookmark: legion/K [move sideways from <theirs> to <yours>]`). A clone that has not seen the other
+push is refused by jj itself (`unexpectedly moved on the remote`).
+
+**Rewriting pushed commits** — the conflict-forced rebase, the rebase after a retarget, or a
+`jj squash --into` a commit already on GitHub — leaves the pushed tip outside `::@-`, so record
+that tip first, after a fetch and while your chain still descends from it:
+
+```bash
+cd -- "$LEGION_WORKSPACE" && \
+  jj -R "$LEGION_WORKSPACE" git fetch && \
+  behind=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
+    -r 'remote_bookmarks(exact:"legion/<KEY>", exact:"origin") ~ ::@-') && \
+  { [ -z "$behind" ] || { echo "legion/<KEY>@origin is at $behind, which @- does not descend from" >&2; false; }; } && \
+  jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id' \
+    -r 'remote_bookmarks(exact:"legion/<KEY>", exact:"origin")' \
+    >"${TMPDIR:-/tmp}/legion-<KEY>-$LEGION_ROLE-rewritten-tip"
+```
+
+Then rewrite, resolve, and push with the procedure above. It lets the remote branch sit on the
+tip you recorded, which the rewrite replaced, and on nothing else: when another role pushed after
+you recorded it, the push is refused. The push deletes the file.
+
+Before the push, check ancestry and identity as above: the chain carries every earlier phase's
+commits, and pushing them with yours is expected. A refusal, and a push the remote rejects, is a
+report to the architect with the output, never a force-push. The merger makes no commit and
+pushes nothing.
 
-Do not report phase completion until the write, existence check, and handoff commit succeed —
-and, for the implementer, until the push has too. This is the committed copy the next phase
+Do not report phase completion until the write, existence check, handoff commit, and push
+succeed. This is the committed copy the next phase
 reads after revival. It is removed once, at the end of a clean review: the implementer pushes
 that deletion at the reviewer's direction. No other phase removes it — and once it is gone
 (`jj -R "$LEGION_WORKSPACE" file list -r @- .legion` prints nothing on stdout; jj warns on

package/package.json

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