@sjawhar/pi-legion 11.6.0 → 12.1.0

package/README.md

@@ -55,7 +55,7 @@ entry, writes the notices and stages this package's partition of `skills/`. It r
 the committed manifest, whose `omp.extensions` names `extensions/legion.ts`; the release workflow's
 `pi_legion_build` job (`.github/workflows/release.yaml`), the worker image and the e2e pack step
 rewrite it to `["dist/legion.js"]` before `bun pm pack`. Only the e2e pack step restores it
-afterwards: the build job's tree is discarded, and `pi_legion_publish` commits the version bump to
+afterwards: the build job's tree is discarded, and the `publish` job commits the version bump to
 the committed manifest, touching `.version` alone. The manifest's `legion` key carries the daemon
 API contract the plugin was built against; `src/daemon-api-version.test.ts` pins it to the daemon's
 golden fixture.

package/dist/legion.js

@@ -5149,7 +5149,10 @@ var IssueEventPayloadSchema = object({
   status: string2().optional(),
   priority: number2().int().min(0).max(3).nullable().optional(),
   rank: string2().optional(),
-  route: string2().nullish()
+  route: string2().nullish(),
+  changed: array(string2()).optional(),
+  ancestors: array(string2()).optional(),
+  thread_logins: array(string2()).optional()
 });
 var ArtifactCreatedEventPayloadSchema = object({
   artifact: object({ id: string2().optional(), slug: string2().optional(), name: string2().optional() }).optional()
@@ -5203,11 +5206,12 @@ var askEventPayloadFields = {
     primary: boolean2().optional()
   }).optional(),
   resolution: object({
-    kind: _enum(["retracted", "resolved"]).optional(),
+    kind: _enum(["retracted", "resolved", "withdrawn"]).optional(),
     reason: string2().optional(),
     actor: object({ kind: string2().optional(), id: string2().optional() }).passthrough().optional(),
     at: string2().optional()
-  }).nullish()
+  }).nullish(),
+  thread_logins: array(string2()).optional()
 };
 var AskEventPayloadSchema = intersection(object(askEventPayloadFields), object({
   previous: never().optional(),
@@ -5269,7 +5273,8 @@ var CommentEventPayloadSchema = object({
   author: object({ kind: string2(), id: string2() }).optional(),
   created_at: string2().optional(),
   mentions: array(CommentMentionSchema).optional(),
-  deliveries: array(CommentDeliverySchema).optional()
+  deliveries: array(CommentDeliverySchema).optional(),
+  thread_logins: array(string2()).optional()
 }).passthrough();
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
@@ -5278,7 +5283,8 @@ var MessageEventPayloadSchema = object({
   in_reply_to: string2().nullish(),
   reply_body: string2().optional(),
   thread_target: string2().optional(),
-  author: object({ kind: string2(), id: string2() }).optional()
+  author: object({ kind: string2(), id: string2() }).optional(),
+  thread_logins: array(string2()).optional()
 });
 var DispatchTargetedResourceIDSchema = uuid2();
 var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
@@ -5508,7 +5514,7 @@ var dispatchToolSpecs = [
       priority: 1,
       before: "DSP-2"
     },
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. A closed issue takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. Never reassign an issue a person holds to get a " + "faster answer: who holds it is their call. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, because a closed issue refuses messages, comments, and " + "artifacts; reason goes only with status done. Closing an issue withdraws every open ask " + "it holds (resolution kind withdrawn, naming the closer), and reopening it brings exactly " + "those asks back. A closed issue takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. Never reassign an issue a person holds to get a " + "faster answer: who holds it is their call. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -5535,7 +5541,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_claim",
     example: { issue: "DSP-1" },
-    description: "Claim a Dispatch issue before you start implementing it, so no other session takes the same work, " + "and release it when you stop. Pass the issue alone to claim it, or --release to give it up. " + "Your claim records your own session and shows on every read of the issue: the dashboard header, the " + "issue list and board, dispatch read, and dispatch issues. Claiming is refused with 409 ISSUE_CLAIMED " + "when another session holds the issue and is still running; the refusal names that session, so talk to " + "it instead of working the same issue in parallel. When a human holds the claim the refusal names the " + "person, not a session: there is nothing running to message, so ask them on the issue rather than " + "taking it. 409 CLAIM_CONTENDED means the issue changed " + "hands twice while your call ran, so nothing was applied and nobody's liveness was checked: read " + "the issue and decide again. A claim whose session is no longer running may be " + "taken: the takeover is recorded on the issue and the session that lost it is told. A claim is not the " + "issue's status \u2014 claiming moves nothing, and the result names who moves the status: you, with " + "dispatch issue-update, or Legion's daemon on an issue it runs, where a status written by anyone " + "else is undone. A claim is released by its holder or any human, and by " + "any agent once the holder's session is no longer running. " + ISSUE_REFERENCE,
+    description: "Claim a Dispatch issue before you start implementing it, so no other session takes the same work, " + "and release it when you stop. Pass the issue alone to claim it, or --release to give it up. " + "Your claim records your own session and shows on every read of the issue: the dashboard header, the " + "issue list and board, dispatch read, and dispatch issues. While you hold it, a person's answers, " + "comments and messages on the issue reach your session directly (a new comment that mentions you " + "arrives once, as the mention, when the mention reached you; when the mention's send fails, the " + "comment still reaches you directly; a mention whose receipt timed out can arrive twice, and the " + "second copy is the same comment); an agent's events and every other change on the issue still " + "need a subscription to it, except in an ask you follow: anyone else's answer, hand-back, " + "resolution or edit of it (other than a quiet edit), and every reply there (new, edited, resolved " + "or reopened), reach you " + "as its follower. Claiming is refused with 409 ISSUE_CLAIMED " + "when another session holds the issue and is still running; the refusal names that session, so talk to " + "it instead of working the same issue in parallel. When a human holds the claim the refusal names the " + "person, not a session: there is nothing running to message, so ask them on the issue rather than " + "taking it. 409 CLAIM_CONTENDED means the issue changed " + "hands twice while your call ran, so nothing was applied and nobody's liveness was checked: read " + "the issue and decide again. A claim whose session is no longer running may be " + "taken: the takeover is recorded on the issue and the session that lost it is told. A claim is not the " + "issue's status \u2014 claiming moves nothing, and the result names who moves the status: you, with " + "dispatch issue-update, or Legion's daemon on an issue it runs, where a status written by anyone " + "else is undone. A claim is released by its holder or any human, and by " + "any agent once the holder's session is no longer running. " + ISSUE_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       release: z.boolean().describe("Give up your claim instead of taking it; the issue's status does not change.").optional()
@@ -5622,7 +5628,7 @@ var dispatchToolSpecs = [
       kind: "retracted",
       reason: "A newer question supersedes this one."
     },
-    description: "Retract an open question that is moot or resolve one after finding the answer. This closes " + "the question without answering it. An ask that lives as an `ask` block in a document is " + 'closed in the document too. A reason beginning "removed from the document in version" is ' + "refused: that marks a retraction the document's own settlement wrote. Use retracted for an ask " + "a newer one replaces or the design made moot, resolved for one whose answer you found; an " + "answered ask cannot be resolved, and resolving records no decision by a person.",
+    description: "Retract an open question that is moot or resolve one after finding the answer. This closes " + "the question without answering it. An ask that lives as an `ask` block in a document is " + 'closed in the document too. A reason beginning "removed from the document in version" is ' + "refused: that marks a retraction the document's own settlement wrote. Use retracted for an ask " + "a newer one replaces or the design made moot, resolved for one whose answer you found; an " + "answered ask cannot be resolved, and resolving records no decision by a person. An issue's " + "close withdrew its open asks (kind withdrawn, which only Dispatch writes, never this tool); " + "an ask on a closed issue is refused (409 ISSUE_CLOSED): reopen the issue first.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id (uuid) to close; an 8+ hex prefix unique among this session's own open asks " + "works too."),
       kind: z.enum(["retracted", "resolved"]).describe("Whether the ask is retracted or self-resolved."),
@@ -5741,7 +5747,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_doc_read",
     example: { issue: "DSP-1" },
-    description: "Read a live document or a named document version, or the text of an uploaded file at its latest or named version. " + "Do not use it for issue status, asks, or events; " + "use dispatch read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + "A live read returns its document token for an optional dispatch doc-edit precondition. With blocks it lists the live document's blocks instead of its markdown, in document order: each block's id, type, token, anchored comments and asks, and opening words, and under a table each row by the index delete_row takes and each cell by its row and the column delete_column takes; block ids, block tokens and those indexes are what dispatch doc-edit takes. " + "A picture (an uploaded PNG, JPEG, GIF or WebP of at most 3,750,000 bytes, 5 MB once base64-encoded) comes back as an image you see, with its name, type, size and version, every time you ask, including one a read already showed this session; " + "any other file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
+    description: "Read a live document or a named document version, or the text of an uploaded file at its latest or named version. " + "Do not use it for issue status, asks, or events; " + "use dispatch read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + "A live read returns its document token for an optional dispatch doc-edit precondition. With blocks it lists the live document's blocks instead of its markdown, in document order: each block's id, type, token, anchored comments and asks, and opening words, and under a table each row by the index delete_row takes and each cell by its row and the column delete_column takes; block ids, block tokens and those indexes are what dispatch doc-edit takes. " + "After the markdown it prints every open thread anchored on the document in full: an open ask with its id and question and each reply's author, time and text, and a comment thread with its root's id, author, quote and text and each reply's author, time and text, in order; a resolved thread, and an ask that is answered or resolved, is not printed. " + "A picture (an uploaded PNG, JPEG, GIF or WebP of at most 3,750,000 bytes, 5 MB once base64-encoded) comes back as an image you see, with its name, type, size and version, every time you ask, including one a read already showed this session; " + "any other file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -6480,8 +6486,8 @@ class DispatchClient {
   async resolveComment(id, actor) {
     return this.#json("POST", ["api", "v1", "comments", id, "resolve"], { actor });
   }
-  async getComments(issue, artifact) {
-    return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], undefined, artifact ? { artifact } : undefined);
+  async getComments(issue) {
+    return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"]);
   }
   async getIssueReferences(issue) {
     return this.#json("GET", [
@@ -7489,7 +7495,7 @@ async function findHandoffCommit(input) {
 
 // ../pi-shared/src/interface.ts
 import { logger } from "@oh-my-pi/pi-utils";
-var ENVOY_PLUGIN_INTERFACE_VERSION = 3;
+var ENVOY_PLUGIN_INTERFACE_VERSION = 4;
 var ENVOY_PLUGIN_INTERFACE_KEY = Symbol.for("legion.pi-shared.envoy-plugin-interface");
 var LEGION_PLUGIN_LOADED_KEY = Symbol.for("legion.pi-legion.loaded");
 var LEGACY_LEGION_LOADED_KEY = Symbol.for("legion.pi-envoy.legion-loaded");
@@ -7509,7 +7515,8 @@ function envoyPluginInterface() {
       slackRoleOwned: false
     },
     injectedUserTurns: new Map,
-    bootstrappedSession: { file: undefined }
+    bootstrappedSession: { file: undefined },
+    startupTurn: undefined
   };
   store[ENVOY_PLUGIN_INTERFACE_KEY] = created;
   return created;
@@ -7604,6 +7611,19 @@ function onEnvoyRoleRegained(listener) {
   legionRoleClaimBridge().regained = listener;
 }
 
+// ../pi-shared/src/startup-turn.ts
+function markStartupTurnSent(sessionID) {
+  envoyPluginInterface().startupTurn = { session: sessionID, sentAt: Date.now() };
+}
+function clearStartupTurn(sessionID) {
+  const reading = readEnvoyPluginInterface();
+  if (reading.kind !== "present")
+    return;
+  if (reading.iface.startupTurn?.session !== sessionID)
+    return;
+  reading.iface.startupTurn = undefined;
+}
+
 // ../pi-shared/src/subagent-session.ts
 import fs from "fs";
 import path2 from "path";
@@ -7660,7 +7680,7 @@ function subagentSessionCheck() {
 }
 
 // extensions/legion.ts
-import { logger as logger3 } from "@oh-my-pi/pi-utils";
+import { logger as logger4 } from "@oh-my-pi/pi-utils";
 
 // src/capability-report.ts
 import { readdir, stat } from "fs/promises";
@@ -8158,7 +8178,7 @@ async function bootLegionClaim(host) {
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion",
-  version: "11.6.0",
+  version: "12.1.0",
   license: "Apache-2.0",
   type: "module",
   omp: {
@@ -8170,7 +8190,7 @@ var package_default = {
     ]
   },
   legion: {
-    daemonApiVersion: 40
+    daemonApiVersion: 41
   },
   repository: {
     type: "git",
@@ -8185,7 +8205,7 @@ var package_default = {
     prepack: "../../scripts/pi-plugin-prepack.sh",
     postpack: "rm -rf dist/skills",
     typecheck: "bunx tsc --noEmit",
-    test: "bun test",
+    test: "bun test --path-ignore-patterns=extensions/controller-start-omp.test.ts && bun test ./extensions/controller-start-omp.test.ts",
     lint: "bunx biome lint extensions/ src/"
   },
   devDependencies: {
@@ -8373,6 +8393,9 @@ function createClaimSession(deps) {
   };
 }
 
+// src/controller-session.ts
+import { logger as logger3 } from "@oh-my-pi/pi-utils";
+
 // src/slack-channels.ts
 function daemonLaunchedController(env) {
   return env.LEGION_CONTROLLER === "1" && env.LEGION_TREE === undefined && (env.LEGION_BOOT_TOKEN_FILE !== undefined || env.LEGION_BOOT_TOKEN !== undefined);
@@ -8394,30 +8417,60 @@ function daemonControllerSlackChannels(env) {
 }
 
 // src/controller-session.ts
+var CLAIM_WIDGET = "legion-controller-claim";
+function operatorLaunchedController(env) {
+  return classifySession(env).kind === "controller" && !daemonLaunchedController(env);
+}
 function createControllerSession(deps) {
   const { daemon, persistedTranscript, pi } = deps;
   let controllerSessionID;
   let controllerCapability;
   let mintControllerGrant;
   let startMessageSent = false;
+  let claimComplete = false;
   let controllerTranscript;
-  const claim = async (context) => {
+  let claimChain = Promise.resolve();
+  let claimsQueued = 0;
+  let startHandedOver = false;
+  let claimWidget;
+  let startTurnSession;
+  const serialised = (task) => {
+    claimsQueued += 1;
+    const run = claimChain.then(task).finally(() => {
+      claimsQueued -= 1;
+    });
+    claimChain = run.catch(() => {
+      return;
+    });
+    return run;
+  };
+  const claim = (context) => queueClaim(context, { registered: false });
+  const noteWait = (context) => {
+    if (claimsQueued > 0) {
+      context.ui.notify("legion: waiting for the controller claim already running to finish.", "info");
+    }
+  };
+  const queueClaim = (context, progress) => {
+    noteWait(context);
+    return serialised(() => claimOnce(context, progress));
+  };
+  const claimOnce = async (context, progress) => {
     const supervised = daemonLaunchedController(process.env);
     if (!supervised)
-      return claimWith(context, false);
+      return claimWith(context, false, progress);
     try {
-      await claimWith(context, true);
+      await claimWith(context, true, progress);
     } catch (error) {
-      console.error(`[legion] the daemon-launched controller's claim failed; exiting so the daemon launches it again: ${messageFor(error)}`);
+      logger3.error(`[legion] the daemon-launched controller's claim failed; exiting so the daemon launches it again: ${messageFor(error)}`);
       deps.exitProcess(1);
     }
   };
-  const claimWith = async (context, supervised) => {
+  const claimWith = async (context, supervised, progress) => {
     const sessionID = context.sessionManager.getSessionId();
     const capability = controllerCapability ?? (supervised ? requiredSecret(process.env, "LEGION_BOOT_TOKEN") : requiredControllerCapability(process.env));
     controllerCapability = capability;
     const launched = classifySession(process.env).kind === "controller";
-    const startMessage = launched && !supervised ? requiredEnvironment(process.env, "LEGION_CONTROLLER_START_MESSAGE") : undefined;
+    const startMessage = operatorLaunchedController(process.env) ? requiredEnvironment(process.env, "LEGION_CONTROLLER_START_MESSAGE") : undefined;
     const { sessionFile, agentId } = await persistedTranscript(context);
     if (launched)
       recordBootstrappedSession(sessionFile);
@@ -8437,24 +8490,41 @@ function createControllerSession(deps) {
       pluginContract: package_default.legion.daemonApiVersion
     }).catch((error) => {
       if (error instanceof LegionDaemonApiError) {
-        console.error(`[legion] claims/register for the controller failed (${error.status}): ${error.detail}`);
+        logger3.error(`[legion] claims/register for the controller failed (${error.status}): ${error.detail}`);
       }
       throw error;
     });
     if (controllerToken(project) !== registration.claimToken) {
       throw new Error(`LEGION_PROJECT ${project} names controller role ${controllerToken(project)}, but the daemon registered this controller as ${registration.claimToken}`);
     }
+    claimComplete = false;
+    mintControllerGrant = () => client.controllerGrant({ sessionId: sessionID, secret: registration.secret });
+    controllerSessionID = sessionID;
+    controllerTranscript = launched ? sessionFile : undefined;
+    progress.registered = true;
     const envoyContext = "setInterval" in context ? context : undefined;
-    await claimEnvoyRole(sessionID, registration.claimToken, envoyContext);
     if (startMessage !== undefined && !startMessageSent) {
-      pi.sendUserMessage(startMessage);
+      if (context.sessionManager.getSessionId() !== sessionID) {
+        startHandedOver = true;
+        return;
+      }
+      if (context.isIdle?.() === false) {
+        pi.sendUserMessage(startMessage, { deliverAs: "followUp" });
+      } else {
+        markStartupTurnSent(sessionID);
+        startTurnSession = sessionID;
+        pi.sendUserMessage(startMessage);
+      }
       startMessageSent = true;
     }
+    await claimEnvoyRole(sessionID, registration.claimToken, envoyContext);
     await subscribeLegionNotice(sessionID, legionControllerNoticeSubject(project), envoyContext, registration.claimToken);
     for (const channel of slackChannels) {
       await subscribeLegionNotice(sessionID, slackMentionTopic(channel), envoyContext, registration.claimToken);
     }
     if (supervised) {
+      markStartupTurnSent(sessionID);
+      startTurnSession = sessionID;
       await client.ready({
         claimToken: registration.claimToken,
         sessionId: sessionID,
@@ -8462,30 +8532,100 @@ function createControllerSession(deps) {
         generation: registration.generation
       });
     }
-    mintControllerGrant = () => client.controllerGrant({ sessionId: sessionID, secret: registration.secret });
-    controllerSessionID = sessionID;
-    controllerTranscript = launched ? sessionFile : undefined;
+    claimComplete = true;
+    claimWidget?.clear();
+    claimWidget = undefined;
   };
   const handleSessionStart = async (context) => {
-    if (classifySession(process.env).kind !== "controller")
+    if (!daemonLaunchedController(process.env))
       return;
     const sessionID = context.sessionManager.getSessionId();
     if (controllerSessionID === undefined || controllerSessionID === sessionID) {
       await claim(context);
     }
   };
+  const startCommand = (context) => {
+    noteWait(context);
+    return serialised(async () => {
+      if (!operatorLaunchedController(process.env) || claimComplete) {
+        context.ui.notify("legion: nothing to do: the controller claim already succeeded in this process, or this session claims no controller from this command (a hand-started takeover, or the controller the daemon launched).", "info");
+        return;
+      }
+      if (startMessageSent) {
+        context.ui.notify("legion: this process already sent the start message, but its controller claim did not finish; run /legion-claim-controller to claim the controller role and its wakes again.", "warning");
+        return;
+      }
+      try {
+        await claimOnce(context, { registered: false });
+      } catch (error) {
+        const message = messageFor(error);
+        logger3.error(`[legion] the controller claim failed: ${message}`);
+        context.ui.notify(startMessageSent ? `legion: the controller claim failed after the start message was sent: ${message}. The start turn has the controller's registration; run /legion-claim-controller to claim the controller role and its wakes again.` : `legion: the controller claim failed: ${message}. Run /legion-claim-controller to claim again; it sends the start message once the claim succeeds.`, "warning");
+      }
+    });
+  };
   const reclaimAfterSessionChange = async (context) => {
     if (classifySession(process.env).kind !== "controller")
       return;
-    if (context.sessionManager.getSessionId() === controllerSessionID && context.sessionManager.getSessionFile() === controllerTranscript) {
+    if (claimComplete && context.sessionManager.getSessionId() === controllerSessionID && context.sessionManager.getSessionFile() === controllerTranscript) {
+      if (claimWidget !== undefined && claimWidget.session !== controllerSessionID) {
+        claimWidget.clear();
+        claimWidget = undefined;
+      }
       return;
     }
+    const notices = [];
+    let shown = false;
+    const notify = (message, level) => {
+      if (shown)
+        context.ui.notify(message, level);
+      else
+        notices.push({ message, level });
+    };
+    const deferred = Object.create(context, { ui: { value: { notify } } });
+    const progress = { registered: false };
     try {
-      await claim(context);
+      noteWait(context);
+      await serialised(async () => {
+        if (startHandedOver) {
+          startHandedOver = false;
+          notify("legion: the session changed while the controller claim ran; the claim for the new session follows and sends the start message there.", "info");
+        }
+        await claimOnce(deferred, progress);
+      });
     } catch (error) {
-      context.ui.notify(`legion: re-claiming the controller for this session failed (${messageFor(error)}). Until a re-claim succeeds, controller wakes and merges will not reach this session, and the \`legion\` tool's set_status and its other operations that call the daemon have no controller grant to mint and fail.`, "warning");
+      notify(progress.registered ? `legion: re-claiming the controller for this session failed (${messageFor(error)}). The session keeps its controller registration, so the \`legion\` tool's set_status still works, but until a re-claim succeeds controller wakes and merges will not reach this session.` : `legion: re-claiming the controller for this session failed (${messageFor(error)}). Until a re-claim succeeds, controller wakes and merges will not reach this session, and the \`legion\` tool's set_status and its other operations that call the daemon have no controller grant to mint and fail.`, "warning");
+    } finally {
+      const { ui } = context;
+      if (ui.setWidget === undefined) {
+        context.setTimeout(() => {
+          shown = true;
+          for (const { message, level } of notices.splice(0))
+            ui.notify(message, level);
+        }, 0);
+      } else {
+        shown = true;
+        if (notices.length > 0) {
+          ui.setWidget(CLAIM_WIDGET, notices.splice(0).map(({ message }) => message));
+          claimWidget = {
+            session: context.sessionManager.getSessionId(),
+            clear: () => ui.setWidget?.(CLAIM_WIDGET, undefined)
+          };
+        }
+      }
     }
   };
+  const handleAgentStart = (context) => {
+    const sessionID = context.sessionManager.getSessionId();
+    if (startTurnSession === sessionID) {
+      startTurnSession = undefined;
+      return;
+    }
+    if (claimWidget?.session !== sessionID)
+      return;
+    claimWidget.clear();
+    claimWidget = undefined;
+  };
   const isClaimedSession = (sessionID) => controllerSessionID === sessionID && mintControllerGrant !== undefined;
   const mintGrant = async (sessionID) => {
     if (controllerSessionID !== sessionID || mintControllerGrant === undefined) {
@@ -8493,7 +8633,15 @@ function createControllerSession(deps) {
     }
     return mintControllerGrant();
   };
-  return { claim, handleSessionStart, reclaimAfterSessionChange, isClaimedSession, mintGrant };
+  return {
+    claim,
+    handleSessionStart,
+    handleAgentStart,
+    reclaimAfterSessionChange,
+    startCommand,
+    isClaimedSession,
+    mintGrant
+  };
 }
 
 // src/phase-stall.ts
@@ -9004,7 +9152,7 @@ function envoyPluginRefusal() {
 }
 function legionExtension(pi) {
   const instance = randomUUID().slice(0, 8);
-  logger3.debug("extension instance loaded", { extension: import.meta.url, instance });
+  logger4.debug("extension instance loaded", { extension: import.meta.url, instance });
   globalThis[LEGION_PLUGIN_LOADED_KEY] = {
     from: import.meta.url,
     envoyInterface: ENVOY_PLUGIN_INTERFACE_VERSION
@@ -9071,7 +9219,7 @@ function legionExtension(pi) {
       return;
     const refusal = envoyPluginRefusal();
     if (refusal !== undefined) {
-      logger3.error(refusal);
+      logger4.error(refusal);
       exitProcess(1);
     }
     if (session.kind === "controller") {
@@ -9099,8 +9247,13 @@ function legionExtension(pi) {
     resentNoticeId = recreatedNotice.id;
     return { message: workspaceRecreatedMessage(recreatedNotice) };
   });
-  pi.on("agent_start", async () => {
+  pi.on("agent_start", async (_event, context) => {
     recreatedNotice = undefined;
+    clearStartupTurn(context.sessionManager.getSessionId());
+    controllerSession.handleAgentStart(context);
+  });
+  pi.on("session_shutdown", async (_event, context) => {
+    clearStartupTurn(context.sessionManager.getSessionId());
   });
   pi.on("context", async (event) => {
     if (resentNoticeId === undefined)
@@ -9193,6 +9346,12 @@ function legionExtension(pi) {
       await activateLegionTool();
     }
   });
+  pi.registerCommand("legion-controller-start", {
+    description: "Claim the Legion controller and send its start message as the session's first turn; `legion controller start` passes this command on Oh My Pi's command line",
+    handler: async (_args, context) => {
+      await controllerSession.startCommand(context);
+    }
+  });
 }
 export {
   legionExtension as default,

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

@@ -12,7 +12,7 @@ except a clear defect a role reports ([Issues handed to Legion](#issues-handed-t
 
 ## Rules
 
-- Handle no wake until the extension's startup claim of `legion-<project>-controller` succeeded, because without it the daemon does not know you as its controller.
+- Handle no wake until the extension has registered this session with the daemon as the project's controller, at session startup or, in a controller an operator started, from its first command once Oh My Pi has started, because without that registration the daemon does not know you as its controller.
 - Answer a person's direct message first, in the conversation. A plain user turn that is neither the start message nor a task sent with `legion claims deliver` is a person writing from Dispatch's Agents page.
 - A direct Dispatch message that decides scope, priority or an owner is a ruling: after you answer it, run the weekly-plan reconciliation (`skill://legion-controller/references/backlog-stewardship.md`), because the plan must record the rule.
 - Handle one wake per turn, then end the turn. Never poll or wait for an event, because the daemon wakes you again (`tick` at least every `controller_wake_interval_seconds`).

package/dist/skills/legion-controller/references/daily-report.md

@@ -30,9 +30,9 @@ unassigned.
 
 Each time you read it:
 
-- `Status: done` means someone closed it, and Dispatch then refuses an ask or a message there
-  (`409 ISSUE_CLOSED`) and hides its open asks. Reopen it with `set_status` to `icebox` and say so
-  in the day's report.
+- `Status: done` means someone closed it: the close withdrew its open asks (each recorded
+  `withdrawn`; a reopen brings them back), and Dispatch refuses an ask or a message there
+  (`409 ISSUE_CLOSED`). Reopen it with `set_status` to `icebox` and say so in the day's report.
 - `Assignee: unassigned` with a person known: assign it, naming your session (`dispatch whoami`):
   `curl -sS -X PATCH -H "Authorization: Bearer $(cat "$DISPATCH_TOKEN_FILE")" -H 'Content-Type: application/json' -d '{"assignee": "<email>", "actor": {"kind": "session", "id": "<session id>"}}' "$DISPATCH_URL/api/v1/issues/<REPORT KEY>"`.
   An answer that does not print the issue with its new `assignee` left the assignee as it was

package/dist/skills/legion-controller/references/session.md

@@ -83,8 +83,8 @@ environment, then run:
 It checks `LEGION_PROJECT` against the daemon, registers the session, claims the Envoy role, and
 moves the daemon's recorded controller session id to this session; the `legion` tool's controller
 operations then work there. Never pass the secret as a command argument or copy it into a
-transcript, because others read transcripts. Do not set `LEGION_CONTROLLER=1`, because a session
-carrying that marker claims at startup as the launched controller. Run `/legion-claim-controller`
+transcript, because others read transcripts. Do not set `LEGION_CONTROLLER=1`: that marker makes
+the session the launched controller, which needs a start message. Run `/legion-claim-controller`
 once per session; do not run it again after an Envoy listener restart, because the heartbeat
 re-claims the role.
 

package/dist/skills/legion-worker/references/findings.md

@@ -118,9 +118,9 @@ An ask goes on the controller's report issue whenever it is open: the issue the
 instructions name for Legion's reports, else the project's `Legion daily report`, which
 `dispatch search --query '"Legion daily report"' --project <PROJECT>` finds. It stays open in
 `icebox`, so the ask stays answerable whatever happens to the issue it came from; once an issue
-closes, Dispatch takes its open asks out of the Inbox and refuses their answers
-(`409 ISSUE_CLOSED`). The question names the issue the finding came from by its `dispatch://`
-reference.
+closes, its close withdraws its open asks (a reopen brings them back), and Dispatch refuses their
+answers (`409 ISSUE_CLOSED`). The question names the issue the finding came from by its
+`dispatch://` reference.
 
 When the project has no report issue yet, or a person closed it (`dispatch read` shows `Status:
 done`, and Dispatch refuses the ask with `409 ISSUE_CLOSED`), do not create or reopen one yourself

package/dist/skills/legion-worker/references/merge-gate.md

@@ -289,10 +289,11 @@ reviewing until you finish.
   repository's deploy workflow (`projects.<KEY>.deploys`), at each completed run of that workflow
   on the default branch whose named step (such as `Apply`) succeeded after the merge, once per such
   job; or, for `sjawhar/legion`, on a Legion daemon's boot on a build containing the merge, on
-  Dispatch's `server.started` naming such a build, or on the build the daemon read from Dispatch at
-  its boot. The woken look's task names the event (`Dispatch's issue.deployed: run <id> completed <t>`,
+  Dispatch's `server.started` announcing that every server process serves such a build, or on the
+  build the daemon read from Dispatch at its boot. The woken look's task names the event
+  (`Dispatch's issue.deployed: run <id> completed <t>`,
   `the deploy workflow's run: <repo> <workflow> run <id> attempt <n>, job <job name>: <step> succeeded at <t>`,
-  `the Legion daemon's boot on build <sha>`, `Dispatch's start on build <sha>`,
+  `the Legion daemon's boot on build <sha>`, `Dispatch serving build <sha> on every server process`,
   `Dispatch's build <sha>`), and its `Production:` line names it too, so the pull request carries
   the cause. Never poll for the deploy, never wait on a reply, and never ask anyone for approval
   to deploy. Open a `dispatch ask` to a person only when the instructions name nobody for that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion",
-  "version": "11.6.0",
+  "version": "12.1.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {
@@ -12,7 +12,7 @@
     ]
   },
   "legion": {
-    "daemonApiVersion": 40
+    "daemonApiVersion": 41
   },
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
     "prepack": "../../scripts/pi-plugin-prepack.sh",
     "postpack": "rm -rf dist/skills",
     "typecheck": "bunx tsc --noEmit",
-    "test": "bun test",
+    "test": "bun test --path-ignore-patterns=extensions/controller-start-omp.test.ts && bun test ./extensions/controller-start-omp.test.ts",
     "lint": "bunx biome lint extensions/ src/"
   },
   "devDependencies": {