@hassangameryt/freeflow 0.8.0 → 0.9.0

package/pi-extension/dist/cognitive-routing/gate.js

@@ -2,10 +2,12 @@ import { existsSync, realpathSync } from "node:fs";
 import { relative, resolve as resolvePath } from "node:path";
 import { ROUTING_RECOVERY_HINT } from "./session.js";
 export { ROUTING_RECOVERY_HINT };
+import { requiredReads } from "./bootstrap.js";
 import { bodyHash } from "./sources.js";
 import { initialState } from "./state.js";
 import { RoutingError, isWorkerProfile, requireCondition as check, ROUTING_TOOLS } from "./types.js";
 import { cachedBranch } from "../host/branch.js";
+const BOOTSTRAP_GATED = new Set(["bash", "bash_background", "monitor", "edit", "write", "apply_patch"]);
 /**
  * What routing allows while a profile runs, and what it tells the tool runtime: which ordinary tools a worker may
  * still call, which recovery reads an assessment permits, handoff batching rules, and the operation, admission, and
@@ -115,9 +117,9 @@ export class ToolGate {
     }
   }
   handoffOperation(name, input) {
-    if (name === "freeflow_delegate") return true;
-    if (name === "freeflow_return") return ["submit", "supplement", "retry"].includes(input?.operation);
-    return name === "freeflow_unit" && input?.operation === "recover";
+    if (name === "delegate_work") return true;
+    if (name === "return_work") return ["submit", "supplement", "retry"].includes(input?.operation);
+    return name === "routing_unit" && input?.operation === "recover";
   }
   stableRecoveryPath(path) {
     return (
@@ -192,7 +194,7 @@ export class ToolGate {
       !handoffs.length ||
         (handoffs.length === 1 &&
           this.handoffOperation(calls.at(-1)?.name, calls.at(-1)?.arguments) &&
-          calls.every((b) => this.handoffOperation(b.name, b.arguments) || b.name === "freeflow_project")),
+          calls.every((b) => this.handoffOperation(b.name, b.arguments) || b.name === "select_evidence")),
       "invalid_handoff_batch",
       "A handoff must be last and cannot accompany ordinary task tools.",
     );
@@ -211,12 +213,25 @@ export class ToolGate {
     try {
       const state = this.session.stateData();
       if (state.control === "manual")
-        return isRouting && name !== "freeflow_unit" ? { block: true, reason: "Manual control is active." } : undefined;
+        return isRouting && name !== "routing_unit" ? { block: true, reason: "Manual control is active." } : undefined;
       if (state.control !== "automatic")
         return isRouting ? { block: true, reason: "Automatic routing is inactive." } : undefined;
       this.batch(event.toolCallId, name, nested);
       check(!this.session.error && !this.session.store?.blocked, "routing_blocked");
       this.session.openTurn();
+      const skill = this.session.routingSkill;
+      // Commands and edits wait for the bootstrap read of the skill and the profile's role reference; reads and
+      // controls do not (`bootstrap.ts`). A codemode script's calls reach this gate under their own names.
+      if (skill && BOOTSTRAP_GATED.has(name) && !state.recoveryId && this.session.turn?.skillInView === false) {
+        const [path, reference] = requiredReads(skill, this.session.turn?.profile);
+        check(
+          false,
+          "routing_skill_unread",
+          reference
+            ? `Read the complete cognitive-routing skill and the reference for your profile first: ${path} and ${reference}. Under automatic routing each profile needs both in view before commands or edits, and a compaction takes them out of view. Read them in a response of their own.`
+            : `Read the complete cognitive-routing skill first: ${path}. Under automatic routing each profile needs it in view before commands or edits, and a compaction takes it out of view. Read it in a response of their own.`,
+        );
+      }
       if (isWorkerProfile(this.session.turn?.profile) && !isRouting) {
         const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
         const worker = a ? this.session.assignedWorker(state, a.id) : undefined;

package/pi-extension/dist/cognitive-routing/handlers.js

@@ -4,7 +4,7 @@ import { bodyHash, isTaskEvidence } from "./sources.js";
 import { RoutingError, canonical, emptySelection, idFor, isWorkerProfile, requireCondition as check } from "./types.js";
 import { cachedBranch } from "../host/branch.js";
 /**
- * Runs the routing tools (freeflow_delegate, freeflow_return, freeflow_project, freeflow_unit) one at a time on the
+ * Runs the routing tools (delegate_work, return_work, select_evidence, routing_unit) one at a time on the
  * session's queue. Each accepted call is recorded once under its operation id, so a repeated call returns the saved
  * result instead of acting again; a refused call returns a blocked result that names what to reconcile.
  */
@@ -42,13 +42,13 @@ export class ToolHandlers {
       this.session.ctx = ctx;
       try {
         check(!signal?.aborted, "cancelled");
-        if (name === "freeflow_unit" && input.operation === "inspect") {
+        if (name === "routing_unit" && input.operation === "inspect") {
           check(this.session.supported(), "routing_unavailable");
           return this.result(this.inspectUnit(input));
         }
         const state = this.session.stateData();
         const expected =
-          name === "freeflow_delegate" || name === "freeflow_unit" ? "coordinator" : this.session.assignedWorker(state);
+          name === "delegate_work" || name === "routing_unit" ? "coordinator" : this.session.assignedWorker(state);
         this.session.assertAvailable(expected);
         const op = this.callOperation(callId, name);
         const cached = this.session.receipts.get(op);
@@ -57,13 +57,13 @@ export class ToolHandlers {
           return this.result(structuredClone(cached.value));
         }
         const value =
-          name === "freeflow_delegate"
+          name === "delegate_work"
             ? this.delegate(input, callId, op)
-            : name === "freeflow_return"
+            : name === "return_work"
               ? this.returnReport(input, callId, op)
-              : name === "freeflow_project"
+              : name === "select_evidence"
                 ? this.project(input, op)
-                : name === "freeflow_unit"
+                : name === "routing_unit"
                   ? await this.unit(input, callId, op)
                   : undefined;
         if (value !== undefined) {
@@ -79,9 +79,9 @@ export class ToolHandlers {
           problems: error instanceof RoutingError ? error.problems : [],
           observed: this.session.observed(),
           expectedProfile:
-            name === "freeflow_unit" && input.operation === "inspect"
+            name === "routing_unit" && input.operation === "inspect"
               ? undefined
-              : name === "freeflow_delegate" || name === "freeflow_unit"
+              : name === "delegate_work" || name === "routing_unit"
                 ? "coordinator"
                 : (() => {
                     try {
@@ -101,7 +101,7 @@ export class ToolHandlers {
               "invalid_inspection",
             ].includes(error.code)
               ? "Inspect again without a cursor and use a returned work ref. Lookup recovery does not require a new assignment."
-              : "Preserve saved work. Use freeflow_unit inspect; reconcile current input/control before retrying the named operation.",
+              : "Preserve saved work. Use routing_unit inspect; reconcile current input/control before retrying the named operation.",
         });
       }
     });
@@ -341,8 +341,10 @@ export class ToolHandlers {
       warnings: prepared.warnings,
       stage: "completed-input preparation",
       finalExchangePending: true,
-      provisional:
-        "The finalized handoff exchange, target configuration and budget are revalidated at turn_end; this is not delivery evidence.",
+      // The Coordinator reads this receipt too, after delivery; it must not read as "the evidence was not delivered".
+      provisional: prepared.ready
+        ? "Saved. When this turn ends, Freeflow checks the handoff and delivers the report to Coordinator; selected evidence stays in place in the worker's run, where Coordinator sees it."
+        : "Saved, but blocked: Coordinator receives nothing until the problems below are fixed. Fix the selection with select_evidence, then call return_work with operation retry.",
       // The text is already in the call arguments; the hash identifies it without a second copy.
       ...(isSupplement ? { supplementSha256: bodyHash(h.text) } : { reportSha256: bodyHash(h.text) }),
       evidence: this.assembler.evidenceFacts(state),
@@ -547,7 +549,7 @@ export class ToolHandlers {
         check(
           !idFor(resultId),
           "result_unavailable",
-          `${resultId} is a context ref, not a captured result id: name it in the request instead, and the worker selects it as evidence with freeflow_project.`,
+          `${resultId} is a context ref, not a captured result id: name it in the request instead, and the worker selects it as evidence with select_evidence.`,
         );
         const grant = await this.resultGrants?.resolve(resultId, this.session.ctx);
         check(grant?.id === resultId, "result_unavailable", `Captured result is unavailable: ${resultId}`);

package/pi-extension/dist/cognitive-routing/model-control.js

@@ -33,30 +33,38 @@ export class ModelControl {
     }
     return observed && !samePair(observed, expected) ? { profile: state.profile, expected, observed } : undefined;
   }
-  /** Set by a user prompt's before_agent_start; consumed by the run it starts. */
+  /** Set when a run is prepared before it starts (in beforeRun, or by routing itself); consumed by the run it starts. */
   promptRun = false;
-  /** A run that no user prompt prepared has started and its first message has not been seen yet. */
+  /** A run that nothing prepared has started and its first message has not been seen yet. */
   unpreparedRun = false;
   /** The next run is already prepared by routing itself (explicit resume sends the message that starts it). */
   preparedRun() {
     this.promptRun = true;
   }
-  /** Pi starts a run: from a user prompt (prepared in beforeRun), a message an extension sent, or a retry. */
+  /** Pi starts a run: from a user prompt or an extension's message (prepared in beforeRun), or a retry. */
   runStarted() {
     this.unpreparedRun = !this.promptRun;
     this.promptRun = false;
   }
   /**
-   * Whether this message starts a run an extension's message triggered. Pi skips before_agent_start for those runs,
-   * so routing prepares them here, before their first request. A retry's run starts with no message and is left as is.
+   * Whether this message starts a run an extension's message triggered that beforeRun did not prepare. Pi before 1.2.0
+   * skips before_agent_start for those runs, so routing prepares them here, before their first request; from 1.2.0 Pi
+   * fires it for them and this returns false. A retry's run starts with no message and is left as is.
    */
   startedByMessage(message) {
     if (!this.unpreparedRun) return false;
     this.unpreparedRun = false;
     return message?.role === "custom";
   }
-  async beforeRun(ctx, fromPrompt = true) {
-    if (fromPrompt) this.promptRun = true;
+  /**
+   * Prepare a run before its first request. `prompt` and `message` come from before_agent_start, which Pi 1.2.0 and
+   * later also fire for a run an extension's message starts; a run routing prepared itself (explicit resume) is not
+   * prepared again, so the resumed worker keeps its model. `late` comes from the first message of a run Pi started
+   * without before_agent_start.
+   */
+  async beforeRun(ctx, trigger = "prompt") {
+    if (trigger === "message" && this.promptRun) return;
+    if (trigger !== "late") this.promptRun = true;
     this.session.ctx = ctx;
     if (this.session.store && this.session.supported() && !this.session.store.blocked && !this.session.error) {
       if (this.session.stateData().control === "automatic" && isWorkerProfile(this.session.stateData().profile)) {
@@ -123,7 +131,8 @@ export class ModelControl {
       this.session.enabledWorkers(state),
       (provider, modelId) => this.session.ctx?.modelRegistry?.find?.(provider, modelId),
       (model) => keepsCacheAcrossEffort(model, this.session.ctx),
-      // Pi's only retention control; unset means the short tier.
+      // The host's default retention, which Freeflow reads and never sets; unset means the short tier. (Pi also takes a
+      // per-request cacheRetention option, which Freeflow does not pass.)
       process.env.PI_CACHE_RETENTION === "long" ? "long" : "short",
     );
   }

package/pi-extension/dist/cognitive-routing/projection.js

@@ -1,6 +1,6 @@
 import { annotateSources } from "./provenance.js";
 import { randomUUID } from "node:crypto";
-import { bodyHash, deliveredSelection } from "./sources.js";
+import { bodyHash, deliveredSelection, isTaskEvidence } from "./sources.js";
 import { canonical, emptySelection, isWorkerProfile, PROFILES, requireCondition as check } from "./types.js";
 import { estimateRequest } from "./budget.js";
 import { occurrenceIdentity, tagDerived } from "../host/projection-tags.js";
@@ -217,9 +217,18 @@ export function prepareView(options) {
     // A structural worker envelope keeps only its calls for the selected results; worker narration is never evidence.
     const structuralWorker =
       role === "assistant" && selective && isWorkerProfile(source.producer) && !full.has(source.ref);
-    const omitted = role === "toolResult" && !full.has(source.ref);
+    // Why a result is not shown, said plainly: "omitted" read as lost evidence, and grok-4.7 Coordinators recovered
+    // results that were shown in full beside it (Task 004 S-005).
+    const omitted =
+      role === "toolResult" && !full.has(source.ref)
+        ? required.has(source.ref)
+          ? "[Selected, but not shown: see the evidence problems in the Cognitive Routing Runtime State]"
+          : isTaskEvidence(source)
+            ? "[Not shown: the worker did not select this result as evidence]"
+            : "[Routing receipt, not shown]"
+        : undefined;
     const renamed = role === "toolResult" ? unpaired.get(source.message.toolCallId) : undefined;
-    const variant = `${withheld ? 1 : 0}${structuralWorker ? 1 : 0}${omitted ? 1 : 0}${renamed === undefined ? "" : `:${renamed}`}`;
+    const variant = `${withheld ? 1 : 0}${structuralWorker ? 1 : 0}${omitted ?? 0}${renamed === undefined ? "" : `:${renamed}`}`;
     let variants = cache.renderings.get(source.entry);
     if (!variants) cache.renderings.set(source.entry, (variants = new Map()));
     let rendering = variants.get(variant);
@@ -231,7 +240,7 @@ export function prepareView(options) {
       if (omitted)
         message = {
           ...message,
-          content: [{ type: "text", text: "[Worker result omitted from this view]" }],
+          content: [{ type: "text", text: omitted }],
           details: undefined,
         };
       if (renamed !== undefined) message = { ...message, toolCallId: renamed };
@@ -254,6 +263,13 @@ export function prepareView(options) {
   const shared = sources.nonWorkerBefore;
   const activeRefs = new Set(associated.flatMap((i) => (i.source ? [i.source.ref] : [])));
   const deferredAt = new Map();
+  // Deferred evidence is delivered between call groups: providers such as Anthropic reject anything between a call
+  // and its results. A selection is recorded before Pi stores the select_evidence result, so its admission point is
+  // that result.
+  const afterResults = (at) => {
+    while (sources.entries[at]?.message?.role === "toolResult") at++;
+    return at;
+  };
   if (selective && (options.admissions || options.resumedAt !== undefined))
     for (const source of full.values()) {
       // An attention view omitted required evidence that is no longer in the active context, so after a
@@ -263,7 +279,8 @@ export function prepareView(options) {
           ? options.resumedAt
           : undefined;
       const admitted = options.admissions?.get(source.ref);
-      const at = admitted === undefined ? resumed : Math.max(admitted, resumed ?? 0),
+      const latest = admitted === undefined ? resumed : Math.max(admitted, resumed ?? 0),
+        at = latest === undefined ? undefined : afterResults(latest),
         own = rank.get(source.entry.id) ?? 0;
       if (at === undefined || at <= own || !isWorkerProfile(source.producer) || shared[at] <= shared[own + 1]) continue;
       const group = sources.exchange(source).sources;
@@ -408,7 +425,7 @@ export function prepareView(options) {
         a.id,
         options.compactedInAssignment === undefined
           ? a.contract
-          : `${a.contract}\n\nCompaction: you compacted during this assignment, and cycle ${options.compactedInAssignment} began then. A compaction this contract asks for is done: continue with the rest of the contract, or return it with freeflow_return if compacting was all it asked.`,
+          : `${a.contract}\n\nCompaction: you compacted during this assignment, and cycle ${options.compactedInAssignment} began then. A compaction this contract asks for is done: continue with the rest of the contract, or return it with return_work if compacting was all it asked.`,
       );
   }
   if (baseReport) {

package/pi-extension/dist/cognitive-routing/provenance.js

@@ -56,8 +56,10 @@ export function annotateSources(
         isWorkerProfile(s.producer) && isTaskEvidence(s) && full.has(s.ref)
           ? "task evidence; selection checks apply"
           : "not offered for new evidence selection";
+      // The call's path or command lets a reader match this ref to the result above it.
+      const label = s.message.toolName ? sources.callLabel(s.ref) : undefined;
       return [
-        `${s.ref} | producer: ${s.producer} | ${s.message.role}${s.message.toolName ? ` | ${s.message.toolName}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}`,
+        `${s.ref} | producer: ${s.producer} | ${s.message.role}${s.message.toolName ? ` | ${s.message.toolName}${label ? `: ${label}` : ""}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}`,
       ];
     });
     const keys = new Set(attributed.map((s) => `${s.producer}\u0000${s.assignmentId ?? ""}`));

package/pi-extension/dist/cognitive-routing/render.js

@@ -9,14 +9,14 @@ const locatorText = (locator) => {
   return locator.label ? `${locator.label}${locator.truncated ? " [truncated]" : ""} · ${identity}` : identity;
 };
 function title(name, operation) {
-  if (name === "freeflow_delegate") return operation === "replace" ? "Replace assignment" : "Delegate assignment";
-  if (name === "freeflow_return")
+  if (name === "delegate_work") return operation === "replace" ? "Replace assignment" : "Delegate assignment";
+  if (name === "return_work")
     return operation === "retry"
       ? "Retry return"
       : operation === "supplement"
         ? "Return recovery supplement"
         : "Return to Coordinator";
-  if (name === "freeflow_project")
+  if (name === "select_evidence")
     return (
       {
         add: "Select evidence",
@@ -25,7 +25,7 @@ function title(name, operation) {
         list: "List evidence",
       }[operation ?? ""] ?? "Evidence"
     );
-  if (name === "freeflow_unit")
+  if (name === "routing_unit")
     return (
       {
         inspect: "Inspect routing",
@@ -41,14 +41,14 @@ function title(name, operation) {
 }
 function draft(name, args, expanded) {
   const sections = [];
-  if (name === "freeflow_delegate") sections.push(text(args.contract));
-  if (name === "freeflow_return") sections.push(text(args.report));
-  if (name === "freeflow_unit" && args.operation === "close") sections.push(text(args.assessment));
-  if (name === "freeflow_unit" && args.operation === "recover") sections.push(text(args.request));
+  if (name === "delegate_work") sections.push(text(args.contract));
+  if (name === "return_work") sections.push(text(args.report));
+  if (name === "routing_unit" && args.operation === "close") sections.push(text(args.assessment));
+  if (name === "routing_unit" && args.operation === "recover") sections.push(text(args.request));
   // Metadata can arrive before the main text and otherwise occupy the entire
   // trailing preview forever. Keep the live prose moving; expansion keeps all fields.
   if (!expanded && sections.length) return sections.filter(Boolean).join("\n\n");
-  if (name === "freeflow_project" && Array.isArray(args.refs))
+  if (name === "select_evidence" && Array.isArray(args.refs))
     sections.push(args.refs.filter((r) => typeof r === "string").join("\n"));
   for (const key of ["scope", "view", "ref", "cursor"])
     if (typeof args[key] === "string") sections.push(`${capital(key)}: ${args[key]}`);
@@ -63,13 +63,13 @@ export function renderRoutingCall(name, args = {}, context = {}) {
   if (context.isPartial === false) return new Text(heading, 0, 0);
   const writing = context.argsComplete !== true;
   const noun =
-    name === "freeflow_delegate"
+    name === "delegate_work"
       ? "assignment"
-      : name === "freeflow_return"
+      : name === "return_work"
         ? args.operation === "supplement"
           ? "supplement"
           : "report"
-        : name === "freeflow_unit" && args.operation === "close"
+        : name === "routing_unit" && args.operation === "close"
           ? "assessment"
           : undefined;
   const body = draft(name, args, context.expanded === true);
@@ -108,8 +108,8 @@ function summary(receipt, name, args) {
     return reasons[receipt.code] || text(receipt.message).split("\n")[0] || "Operation needs attention";
   }
   if (receipt.status === "suspended") return "Couldn’t restore evidence · Assessment remains paused";
-  if (name === "freeflow_delegate") return `${operation === "replace" ? "Replacement" : "Assignment"} saved`;
-  if (name === "freeflow_project") {
+  if (name === "delegate_work") return `${operation === "replace" ? "Replacement" : "Assignment"} saved`;
+  if (name === "select_evidence") {
     const selected = (receipt.selected ?? receipt.evidence?.selected ?? []).length;
     if (operation === "list")
       return `${count(receipt.count ?? receipt.items?.length ?? 0, "source")}${Number.isInteger(receipt.selectableCount) ? ` · ${receipt.selectableCount} selectable` : ""}`;
@@ -132,7 +132,7 @@ function summary(receipt, name, args) {
       receipt.items.every((i) => ["already_selected", "unchanged"].includes(i.status));
     return `${unchanged ? "No changes · " : ""}${count(selected, "source")} selected${receipt.ready === false ? ` · ${issue}` : operation === "inspect" ? " · No unresolved references" : ""}`;
   }
-  if (name === "freeflow_unit") {
+  if (name === "routing_unit") {
     if (operation === "close") return capital(receipt.outcome ?? "closed");
     if (operation === "recover") return "Recovery request saved";
     if (operation === "cancel-recovery") return "Evidence recovery cancelled";

package/pi-extension/dist/cognitive-routing/runtime.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { findRoutingSkill } from "./bootstrap.js";
 import { ContextAssembler } from "./assembler.js";
 import { EventStore } from "./event-store.js";
 import { ToolGate } from "./gate.js";
@@ -29,6 +30,7 @@ export class RoutingRuntime {
   constructor(pi, packageRoots = []) {
     this.pi = pi;
     this.packageRoots = packageRoots;
+    this.session.routingSkill = findRoutingSkill(this.packageRoots);
     this.models = new ModelControl(this.session, this.pi);
     this.status = new RoutingStatus(this.session, this.models);
     this.gate = new ToolGate(this.session, this.packageRoots);
@@ -280,8 +282,8 @@ export class RoutingRuntime {
     }
     return true;
   }
-  beforeRun(ctx, fromPrompt = true) {
-    return this.models.beforeRun(ctx, fromPrompt);
+  beforeRun(ctx, trigger) {
+    return this.models.beforeRun(ctx, trigger);
   }
   runStarted() {
     this.models.runStarted();

package/pi-extension/dist/cognitive-routing/schemas.js

@@ -40,7 +40,7 @@ const report = (name) =>
     ["operation", "report", "outcome"],
   );
 export const ROUTING_SCHEMAS = {
-  freeflow_delegate: {
+  delegate_work: {
     oneOf: [
       object({ operation: operation("assign"), contract: string(), worker }, ["operation", "contract"]),
       object({ operation: operation("replace"), contract: string(), reason: string(2048), worker }, [
@@ -50,8 +50,8 @@ export const ROUTING_SCHEMAS = {
       ]),
     ],
   },
-  freeflow_return: { oneOf: [report("submit"), report("supplement"), object({ operation: operation("retry") })] },
-  freeflow_unit: {
+  return_work: { oneOf: [report("submit"), report("supplement"), object({ operation: operation("retry") })] },
+  routing_unit: {
     oneOf: [
       object(
         {
@@ -81,7 +81,7 @@ export const ROUTING_SCHEMAS = {
       }),
     ],
   },
-  freeflow_project: {
+  select_evidence: {
     oneOf: [
       object(
         {

package/pi-extension/dist/cognitive-routing/session.js

@@ -18,6 +18,8 @@ export class RoutingSession {
   capability;
   token = randomUUID();
   turn;
+  /** The packaged routing skill and role references the bootstrap read must cover; undefined when the skill cannot be read. */
+  routingSkill;
   messages = [];
   error;
   projectionError;
@@ -216,6 +218,6 @@ export class RoutingSession {
   workerBasis(state, assignmentId) {
     const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
     if (recovery?.state === "reading") return state.handoffs.get(recovery.requestHandoffId)?.basisUserEntryId ?? null;
-    return this.taskBasis(state, assignmentId);
+    return this.taskBasis(state, assignmentId) ?? null;
   }
 }

package/pi-extension/dist/cognitive-routing/sources.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { canonical, idFor, isWorkerProfile, refFor } from "./types.js";
+import { canonical, idFor, isWorkerProfile, refFor, ROUTING_TOOLS, routingToolName } from "./types.js";
 import { isHostEdited, isProjected, projectedEntryId } from "../host/projection-tags.js";
 export const bodyHash = (value) => createHash("sha256").update(canonical(value)).digest("hex");
 /** Define a memoized hash so history is hashed only when a consumer needs it. */
@@ -11,11 +11,11 @@ function lazyHash(target, compute) {
     get: () => (value ??= compute()),
   });
 }
-const routingTools = new Set(["freeflow_delegate", "freeflow_return", "freeflow_project", "freeflow_unit"]);
+const routingTools = new Set(ROUTING_TOOLS);
 // Discovery, new selections, and delivery share this policy: evidence is what tools produced. What a worker
 // says belongs in its report, so its assistant messages are never evidence.
 export function isTaskEvidence(source) {
-  return source.message.role === "toolResult" && !routingTools.has(source.message.toolName);
+  return source.message.role === "toolResult" && !routingTools.has(routingToolName(source.message.toolName));
 }
 /** Saved selections keep their delivery, except assistant messages (whole or `#text`), which are never evidence. */
 export function deliveredSelection(sources, ref) {
@@ -83,7 +83,7 @@ export class Sources {
       const source = lazyHash({ ref: refFor(entry.id), entry, message, producer: "common", active: false }, () =>
         bodyHash(message),
       );
-      if (message.role === "toolResult" && message.toolName === "freeflow_return") {
+      if (message.role === "toolResult" && routingToolName(message.toolName) === "return_work") {
         for (const block of message.content ?? [])
           if (block.type === "text") {
             try {
@@ -281,6 +281,31 @@ export class Sources {
     );
     return matches.length === 1 ? locatorForCall(group.assistant, matches[0], this.locatorProvider) : undefined;
   }
+  /**
+   * What a tool result's call did, in a few words: its path, command or first short string argument. Coordinator
+   * matches a selected ref to the result in its view by this label (Task 004 S-005); undefined when unknown.
+   */
+  callLabel(ref) {
+    const source = this.byRef.get(ref);
+    if (!source || source.message.role !== "toolResult") return undefined;
+    const call = (this.owners.get(source.ref)?.assistant.message.content ?? []).find(
+      (block) =>
+        block.type === "toolCall" && block.id === source.message.toolCallId && block.name === source.message.toolName,
+    );
+    const args = call?.arguments;
+    if (!args || typeof args !== "object") return undefined;
+    // A path keeps its end, where the file name is; anything else keeps its start.
+    const path = typeof args.path === "string" ? args.path.trim() : "";
+    if (path) return path.length > 100 ? `...${path.slice(-97)}` : path;
+    const chosen =
+      ["command", "pattern", "query", "url"]
+        .map((key) => args[key])
+        .find((value) => typeof value === "string" && value.trim()) ??
+      Object.values(args).find((value) => typeof value === "string" && value.trim() && value.length <= 200);
+    const label = normalizeLabel(chosen)?.label;
+    if (!label) return undefined;
+    return label.length > 100 ? `${label.slice(0, 97)}...` : label;
+  }
   ordered(sources) {
     const ids = new Set([...sources].map((s) => s.ref));
     return this.entries.flatMap((entry) => {

package/pi-extension/dist/cognitive-routing/state.js

@@ -115,7 +115,7 @@ function applyEvent(state, event, owned = false) {
       for (const profile of PROFILES) {
         if (!Object.hasOwn(d.overrides, profile)) continue;
         const override = d.overrides[profile];
-        if (override === null) s.profileOverrides.delete(profile);
+        if (override === null || override === undefined) s.profileOverrides.delete(profile);
         else s.profileOverrides.set(profile, override);
       }
       break;
@@ -242,8 +242,8 @@ function applyEvent(state, event, owned = false) {
           d.recovery.supplementRevision === 0 &&
           d.recovery.supplementHandoffId === undefined &&
           d.recovery.cancellationReason === undefined &&
-          s.assessment?.handoffId === base?.id &&
           base?.kind === "return" &&
+          s.assessment?.handoffId === base.id &&
           a.returnHandoffId === base.id &&
           base.state === "configured" &&
           base.reportRevision === d.recovery.baseReportRevision &&
@@ -267,9 +267,13 @@ function applyEvent(state, event, owned = false) {
       s.handoffs.set(h.id, h);
       s.pendingId = h.id;
       s.assessment.view = "suspended";
-      s.assessment.suspensionReason = "recovery";
-      s.assessment.basisUserEntryId = h.basisUserEntryId;
-      s.assessment.problems = [];
+      // A recovery answers the Coordinator's evidence question, not new user input: an assessment already waiting
+      // for that attention keeps waiting for it after the recovery, instead of resuming when the supplement arrives.
+      if (s.assessment.suspensionReason !== "user-attention") {
+        s.assessment.suspensionReason = "recovery";
+        s.assessment.basisUserEntryId = h.basisUserEntryId;
+        s.assessment.problems = [];
+      }
       break;
     }
     case "recovery-supplement-accepted": {
@@ -281,7 +285,8 @@ function applyEvent(state, event, owned = false) {
         s.control === "automatic" &&
           s.profile === assignmentWorker() &&
           a?.state === "returned" &&
-          r?.id === s.recoveryId &&
+          r !== undefined &&
+          r.id === s.recoveryId &&
           r.assignmentId === a.id &&
           s.assessment?.handoffId === r.assessmentHandoffId &&
           s.handoffs.get(r.assessmentHandoffId)?.reportRevision === r.baseReportRevision &&
@@ -308,7 +313,8 @@ function applyEvent(state, event, owned = false) {
       check(
         s.control === "automatic" &&
           s.profile === "coordinator" &&
-          r?.id === s.recoveryId &&
+          r !== undefined &&
+          r.id === s.recoveryId &&
           ["requested", "reading", "returning"].includes(r.state),
         "recovery_not_cancellable",
       );
@@ -421,7 +427,11 @@ function applyEvent(state, event, owned = false) {
       const u = s.units.get(d.unitId),
         a = assignment();
       check(
-        s.control === "automatic" && s.profile === "coordinator" && u?.id === s.unitId && u.state === "open",
+        s.control === "automatic" &&
+          s.profile === "coordinator" &&
+          u !== undefined &&
+          u.id === s.unitId &&
+          u.state === "open",
         "unit_not_open",
       );
       if (d.outcome === "accepted")

package/pi-extension/dist/cognitive-routing/status.js

@@ -19,7 +19,9 @@ export class RoutingStatus {
     } catch {
       state = initialState();
     }
-    const blocked = this.session.error ?? this.session.store?.blocked;
+    // A model or effort named on Pi's command line holds routing at startup (`startup_selection`). Its store is not
+    // reconciled then, so the store's own reason would hide why (Task 008 S-005).
+    const blocked = this.session.error ?? (this.session.suppressed ? "startup_selection" : this.session.store?.blocked);
     return {
       effective: this.session.supported() && state.control !== "inactive" && !blocked,
       activeProfile: state.profile,
@@ -30,8 +32,7 @@ export class RoutingStatus {
         : this.session.supported() && state.control !== "inactive"
           ? "active"
           : "inactive",
-      runtimeReason:
-        blocked ?? (this.session.suppressed ? "startup_selection" : this.session.capability?.blockingReason.message),
+      runtimeReason: blocked ?? this.session.capability?.blockingReason.message,
       projectionFailure: this.session.projectionError,
       ...((pending) => (pending ? { pendingPair: `${pending.modelId}/${pending.thinking}` } : {}))(
         this.models.pending(),