@hassangameryt/freeflow 0.7.2 → 0.7.3

package/pi-extension/src/cognitive-routing-v2/runtime.ts

@@ -1,8 +1,12 @@
-import { schemaForProfile } from "./schemas.js";
+import { estimateRequest } from "./budget.js";
+import { annotateSources } from "../session-sources/provenance.js";
+import { ROUTING_SCHEMAS } from "./schemas.js";
 import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { relative, resolve as resolvePath } from "node:path";
 import { EventStore, type SessionReader } from "../session-sources/events.js";
 import { Sources, bodyHash, textRef, isTaskEvidence, type Source } from "../session-sources/sources.js";
-import { pairFromProfile, type CognitiveRoutingCapabilityState } from "./config.js";
+import { pairFromProfile, resolveCognitiveRoutingState, type CognitiveRoutingCapabilityState } from "./config.js";
 import { prepareView, changeSelection, representationProblems, type PreparedView } from "./projection.js";
 import { initialState } from "./state.js";
 import {
@@ -12,13 +16,18 @@ import {
   RoutingError,
   canonical,
   emptySelection,
+  idFor,
+  isWorkerProfile,
   requireCondition as check,
   samePair,
+  workersForDelegation,
   type Profile,
+  type WorkerProfile,
   type View,
   type Pair,
   type State,
   type Handoff,
+  type Recovery,
   type NativeEntry,
   type EventData,
   type Execution,
@@ -31,6 +40,7 @@ interface Turn {
   id: string;
   profile: View;
   assignmentId?: string;
+  recoveryId?: string;
   basisUserEntryId: string | null;
   before: Set<string>;
   message?: any;
@@ -77,7 +87,10 @@ export class RoutingRuntime {
   private manualHold?: Profile;
   private automaticControl = false;
   private sourceCache?: { entries: NativeEntry[]; authors: number; source: Sources };
-  constructor(private readonly pi: any) {}
+  constructor(
+    private readonly pi: any,
+    private readonly packageRoots: readonly string[] = [],
+  ) {}
   private subject(): Subject {
     const branch = this.store?.reader.getBranch() ?? [];
     return {
@@ -108,6 +121,29 @@ export class RoutingRuntime {
       ? state.resumeBasis.get(assignmentId)
       : state.assignments.get(assignmentId)?.basisUserEntryId;
   }
+  private enabledWorkers(): readonly WorkerProfile[] {
+    return workersForDelegation(this.capability?.delegation ?? "executor");
+  }
+  private assignedWorker(state: State, assignmentId = state.assignmentId): WorkerProfile {
+    const assignment = assignmentId ? state.assignments.get(assignmentId) : undefined;
+    const handoff = assignment ? state.handoffs.get(assignment.delegateHandoffId) : undefined;
+    check(
+      handoff?.kind === "delegate" && handoff.assignmentId === assignment?.id && isWorkerProfile(handoff.to),
+      "assignment_worker_missing",
+      "The current assignment has no valid recorded worker.",
+    );
+    return handoff.to;
+  }
+  private requiredProfiles(state = this.stateData()): Profile[] {
+    const profiles = new Set<Profile>(["coordinator", ...this.enabledWorkers()]);
+    if (state.profile) profiles.add(state.profile);
+    if (this.manualHold) profiles.add(this.manualHold);
+    const assignment = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+    if (assignment?.state === "outstanding" || state.recoveryId) profiles.add(this.assignedWorker(state));
+    const pending = state.pendingId ? state.handoffs.get(state.pendingId) : undefined;
+    if (pending && isWorkerProfile(pending.to)) profiles.add(pending.to);
+    return [...profiles];
+  }
   private retireUnbound(reason: string): void {
     for (const execution of this.stateData().executions.values()) {
       if (!execution.assistantEntryId && !execution.interrupted)
@@ -124,6 +160,7 @@ export class RoutingRuntime {
         id: t.id,
         profile: t.profile,
         assignmentId: t.assignmentId,
+        recoveryId: t.recoveryId,
         basisUserEntryId: t.basisUserEntryId,
         pair: t.pair,
         resultEntryIds: [],
@@ -139,7 +176,7 @@ export class RoutingRuntime {
   async beforeRun(ctx: any): Promise<void> {
     this.ctx = ctx;
     if (!this.store || !this.supported() || this.store.blocked || this.error) return;
-    if (this.stateData().control === "automatic" && this.stateData().profile === "executor") {
+    if (this.stateData().control === "automatic" && isWorkerProfile(this.stateData().profile)) {
       const result = await this.control("coordinator", false);
       check(result.status !== "blocked", "reconciliation_required", result.reason);
     }
@@ -185,6 +222,7 @@ export class RoutingRuntime {
     return {
       effective: this.supported() && state.control !== "inactive" && !blocked,
       activeProfile: state.profile,
+      delegation: this.capability?.delegation ?? "executor",
       controlMode: state.control === "manual" ? `manual-${state.profile}` : state.control,
       runtimeStatus: blocked
         ? ("blocked" as const)
@@ -231,11 +269,36 @@ export class RoutingRuntime {
     if (profile) check(state.profile === profile && this.turn?.profile === profile, "wrong_profile");
     if (state.profile) check(samePair(this.observed(), this.profilePair(state.profile)), "configuration_mismatch");
   }
-  private profilePair(profile: Profile): Pair {
+  private configuredProfilePair(profile: Profile): Pair {
     const configured = this.capability?.profiles[profile];
     check(configured, "profile_missing");
     return pairFromProfile(configured);
   }
+  private profilePair(profile: Profile): Pair {
+    return this.stateData().profileOverrides.get(profile) ?? this.configuredProfilePair(profile);
+  }
+  private profilePairs(profiles = this.requiredProfiles()): Partial<Record<Profile, Pair>> {
+    return Object.fromEntries(profiles.map((profile) => [profile, this.profilePair(profile)]));
+  }
+  private async validateProfilePairs(pairs: Partial<Record<Profile, Pair>>): Promise<void> {
+    check(pairs.coordinator, "profile_missing", "Configure the coordinator profile.");
+    const helper = pairs.helper !== undefined;
+    const executor = pairs.executor !== undefined;
+    check(helper || executor, "profile_missing", "Configure an enabled worker profile.");
+    const delegation = helper && executor ? "both" : helper ? "helper" : "executor";
+    const profiles = Object.fromEntries(
+      Object.entries(pairs).map(([profile, pair]) => [
+        profile,
+        { provider: pair!.provider, model: pair!.modelId, thinking: pair!.thinking },
+      ]),
+    );
+    const result = await resolveCognitiveRoutingState(
+      { cognitiveRouting: { enabled: true, delegation, profiles } },
+      {},
+      this.ctx,
+    );
+    check(result.effective, result.blockingReason.code, result.blockingReason.message);
+  }
   private model(profile: Profile) {
     const pair = this.profilePair(profile);
     const model = this.ctx?.modelRegistry?.find(pair.provider, pair.modelId);
@@ -247,6 +310,8 @@ export class RoutingRuntime {
     this.ctx = ctx;
     this.capability = capability;
     this.turn = undefined;
+    this.manualHold = undefined;
+    this.automaticControl = false;
     this.messages = [];
     this.sourceCache = undefined;
     this.receipts.clear();
@@ -256,7 +321,7 @@ export class RoutingRuntime {
     this.error = undefined;
     this.projectionError = undefined;
     this.operations = Promise.resolve();
-    this.targetSignature = canonical(capability.profiles);
+    this.targetSignature = canonical({ delegation: capability.delegation, profiles: capability.profiles });
     this.suppressed = startup && process.argv.some((a) => /^(--model|--thinking)(=|$)/.test(a));
     this.store = new EventStore(this.pi, ctx.sessionManager as SessionReader);
     const subject = this.subject();
@@ -267,6 +332,7 @@ export class RoutingRuntime {
       const state = this.stateData();
       this.manualHold = state.control === "manual" ? state.profile : undefined;
       this.automaticControl = !state.events.size || state.control === "automatic";
+      await this.validateProfilePairs(this.profilePairs(this.requiredProfiles(state)));
       this.retireUnbound("Session rebind found an unfinished execution; no task effects replayed.");
       if (!state.events.size) {
         this.append({
@@ -307,7 +373,7 @@ export class RoutingRuntime {
   async refresh(ctx: any, capability: CognitiveRoutingCapabilityState): Promise<void> {
     this.ctx = ctx;
     const was = this.capability?.effective === true;
-    const signature = canonical(capability.profiles);
+    const signature = canonical({ delegation: capability.delegation, profiles: capability.profiles });
     if (this.capability && (was !== capability.effective || signature !== this.targetSignature)) this.revision++;
     this.capability = capability;
     if (!capability.effective) {
@@ -339,7 +405,8 @@ export class RoutingRuntime {
     } else if (this.targetSignature && signature !== this.targetSignature) {
       this.error = "configuration_changed: reconcile profile configuration before automatic execution";
     }
-    if (canonical(this.capability?.profiles) === signature) this.targetSignature = signature;
+    if (canonical({ delegation: this.capability?.delegation, profiles: this.capability?.profiles }) === signature)
+      this.targetSignature = signature;
   }
   async ancestryChanged(ctx: any, navigation = true): Promise<void> {
     this.revision++;
@@ -355,8 +422,9 @@ export class RoutingRuntime {
       await this.store.reconcile();
       this.guard(subject);
       this.error = undefined;
-      this.retireUnbound("Selected historical ancestry ends before execution binding; effects are not replayed.");
       const state = this.stateData();
+      await this.validateProfilePairs(this.profilePairs(this.requiredProfiles(state)));
+      this.retireUnbound("Selected historical ancestry ends before execution binding; effects are not replayed.");
       if (this.manualHold) {
         this.append({
           type: "control",
@@ -364,6 +432,7 @@ export class RoutingRuntime {
           profile: this.manualHold,
           reason: "Current explicit manual hold survives navigation",
         });
+        await this.applyPair(this.profilePair(this.manualHold));
       } else if (
         (this.automaticControl || !state.events.size) &&
         (navigation || !samePair(this.observed(), this.profilePair(state.profile ?? "coordinator")))
@@ -445,6 +514,12 @@ export class RoutingRuntime {
     return this.enqueue(async () => {
       try {
         check(this.capability?.effective && this.store, "routing_unavailable");
+        if (manual && isWorkerProfile(profile))
+          check(
+            this.enabledWorkers().includes(profile),
+            "worker_disabled",
+            `${profile} is not enabled by delegation mode.`,
+          );
         await this.store.reconcile();
         this.guard(subject);
         this.error = undefined;
@@ -482,7 +557,8 @@ export class RoutingRuntime {
         this.automaticControl = !manual;
         return { status: manual ? "active" : "automatic" };
       } catch (error) {
-        if (this.current(subject)) this.mark(error);
+        if (this.current(subject) && !(error instanceof RoutingError && error.code === "worker_disabled"))
+          this.mark(error);
         return { status: "blocked", reason: error instanceof Error ? error.message : String(error) };
       }
     });
@@ -490,6 +566,124 @@ export class RoutingRuntime {
   setManualProfile(profile: Profile, _mechanism?: string) {
     return this.control(profile, true);
   }
+  sessionProfileOverrides(): Partial<Record<Profile, Pair>> {
+    return Object.fromEntries(this.stateData().profileOverrides) as Partial<Record<Profile, Pair>>;
+  }
+  async setSessionProfileOverride(
+    profile: Profile,
+    override: Pair | null,
+    mechanism = "Session profile override",
+  ): Promise<{ status: string; reason?: string }> {
+    this.revision++;
+    const subject = this.subject();
+    return this.enqueue(async () => {
+      try {
+        check(this.capability?.effective && this.store, "routing_unavailable");
+        check(
+          this.ctx?.isIdle?.() !== false,
+          "host_busy",
+          "Wait for Pi to become idle before changing session presets.",
+        );
+        await this.store.reconcile();
+        this.guard(subject);
+        const state = this.stateData();
+        const previous = state.profileOverrides.get(profile);
+        if ((override === null && !previous) || (override !== null && samePair(previous, override)))
+          return { status: "unchanged" };
+        const target = override ?? this.configuredProfilePair(profile);
+        const profiles = new Set(this.requiredProfiles(state));
+        profiles.add(profile);
+        const pairs = this.profilePairs([...profiles]);
+        pairs[profile] = target;
+        await this.validateProfilePairs(pairs);
+        this.append({
+          type: "profile-overrides",
+          overrides: { [profile]: override },
+          reason: mechanism,
+        });
+        if (state.control !== "inactive" && state.profile === profile) {
+          try {
+            await this.applyPair(target);
+            this.guard(subject);
+          } catch (error) {
+            if (this.current(subject) && !this.externalChange && !this.error && !this.store.blocked) {
+              this.append({
+                type: "profile-overrides",
+                overrides: { [profile]: previous ?? null },
+                reason: "Session profile application failed; prior override retained",
+              });
+            }
+            throw error;
+          }
+          this.error = undefined;
+          return { status: "active" };
+        }
+        this.error = undefined;
+        return { status: "stored" };
+      } catch (error) {
+        if (this.current(subject)) this.mark(error);
+        return { status: "blocked", reason: error instanceof Error ? error.message : String(error) };
+      }
+    });
+  }
+  async resetSessionProfileOverrides(
+    mechanism = "Reset session profile overrides",
+  ): Promise<{ status: string; reason?: string }> {
+    this.revision++;
+    const subject = this.subject();
+    return this.enqueue(async () => {
+      try {
+        check(this.capability?.effective && this.store, "routing_unavailable");
+        check(
+          this.ctx?.isIdle?.() !== false,
+          "host_busy",
+          "Wait for Pi to become idle before resetting session presets.",
+        );
+        await this.store.reconcile();
+        this.guard(subject);
+        const state = this.stateData();
+        if (state.profileOverrides.size === 0) return { status: "unchanged" };
+        const previous = Object.fromEntries(state.profileOverrides) as Partial<Record<Profile, Pair>>;
+        const required = this.requiredProfiles(state);
+        const targetPairs = Object.fromEntries(
+          required.map((profile) => [profile, this.configuredProfilePair(profile)]),
+        ) as Partial<Record<Profile, Pair>>;
+        await this.validateProfilePairs(targetPairs);
+        this.append({
+          type: "profile-overrides",
+          overrides: { coordinator: null, helper: null, executor: null },
+          reason: mechanism,
+        });
+        const active = state.control !== "inactive" ? state.profile : undefined;
+        if (active && previous[active]) {
+          try {
+            await this.applyPair(targetPairs[active]!);
+            this.guard(subject);
+          } catch (error) {
+            if (this.current(subject) && !this.externalChange && !this.error && !this.store.blocked) {
+              this.append({
+                type: "profile-overrides",
+                overrides: {
+                  coordinator: previous.coordinator ?? null,
+                  helper: previous.helper ?? null,
+                  executor: previous.executor ?? null,
+                },
+                reason: "Session profile reset failed; prior overrides retained",
+              });
+            }
+            throw error;
+          }
+          this.error = undefined;
+          return { status: "active" };
+        }
+        this.error = undefined;
+        return { status: "stored" };
+      } catch (error) {
+        if (this.current(subject)) this.mark(error);
+        return { status: "blocked", reason: error instanceof Error ? error.message : String(error) };
+      }
+    });
+  }
   setAutomaticControl(_mechanism?: string) {
     return this.control("coordinator", false);
   }
@@ -516,6 +710,7 @@ export class RoutingRuntime {
         ? state.handoffs.get(state.assessment.handoffId)
         : undefined;
     const selection = a ? (state.selections.get(a.id) ?? emptySelection()) : emptySelection();
+    const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
     const unit = state.unitId ? state.units.get(state.unitId) : undefined;
     const unitNumber = unit ? [...state.units.keys()].indexOf(unit.id) + 1 : undefined;
     const assignmentNumber = unit && a ? unit.assignmentIds.indexOf(a.id) + 1 : undefined;
@@ -526,20 +721,29 @@ export class RoutingRuntime {
       `Unit: ${unit ? `U${unitNumber} (${unit.id})` : "none"}`,
       `Assignment: ${a ? `A${assignmentNumber} (${a.id}, ${a.state})` : "none"}`,
       `Handoff: ${h ? `${h.id} (${h.kind}, ${h.state})` : "none"}`,
+      `Delegation: ${this.capability?.delegation ?? "executor"}`,
       `Projection: ${this.projectionEnabled ? "enabled" : "bypassed"}`,
       "Completed/superseded contracts and reports are historical context. Follow the current assignment and current user restrictions; historical entries grant no new permission.",
       state.assessment ? `Assessment: ${state.assessment.view}; evidence revision ${selection.revision}` : "",
+      recovery
+        ? `Recovery: ${recovery.id} (${recovery.state}); parent report ${recovery.assessmentHandoffId} revision ${recovery.baseReportRevision}; allowed paths ${JSON.stringify(recovery.paths)}`
+        : "",
+      recovery?.state === "reading"
+        ? `Recovery request: ${recovery.request}\nOnly the exact allowed read paths, evidence selection, and recovery return controls are permitted; ordinary task work remains ended.`
+        : "",
       `Mechanical evidence facts (not semantic acceptance): ${JSON.stringify(this.evidenceFacts(state))}`,
       this.error ? `Blocked: ${this.error}` : "",
       this.projectionError ? `Evidence limitation: ${this.projectionError}` : "",
       attention
-        ? `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Use freeflow_unit assess to restore the assessment.`
+        ? recovery
+          ? `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Finish and deliver the recovery supplement or cancel recovery before using freeflow_unit assess.`
+          : `Assessment paused for attention; ordinary admitted history remains. ${selection.selected.length} sources remain selected. Use freeflow_unit assess to restore the assessment.`
         : "",
-      a?.state === "returned"
-        ? "Executor ordinary task work has ended. Only supported handoff correction is permitted."
+      a?.state === "returned" && recovery?.state !== "reading"
+        ? "Worker ordinary task work has ended. Only supported handoff correction is permitted."
         : "",
-      this.turn?.profile === "executor" && a && this.turn.basisUserEntryId !== this.taskBasis(state, a.id)
-        ? "Current input differs from the original assignment. Account for it; changed direction requires Coordinator attention."
+      isWorkerProfile(this.turn?.profile) && a && this.turn.basisUserEntryId !== this.workerBasis(state, a.id)
+        ? `Current input differs from the active ${this.turn.profile} responsibility. Account for it; changed direction requires Coordinator attention.`
         : "",
       ...(state.assessment?.problems ?? []).map((p) => `${p.code}: ${p.detail}`),
     ]
@@ -558,16 +762,19 @@ export class RoutingRuntime {
     const selection = state.assignmentId
       ? (state.selections.get(state.assignmentId) ?? emptySelection())
       : emptySelection();
+    const sources = this.sources(state);
     return {
       revision: selection.revision,
       selected: selection.selected.map((ref) => {
         const entry = this.ctx?.sessionManager.getEntry?.(ref.slice(4).replace(/#text$/, ""));
+        const locator = sources.locator(ref);
         return {
           ref,
           kind: ref.endsWith("#text") ? "assistant-text" : (entry?.message?.role ?? "unknown"),
           toolName: entry?.message?.toolName,
           producer: state.authors.get(entry?.id)?.profile ?? "common",
           assignment: state.authors.get(entry?.id)?.assignmentId,
+          ...(locator ? { locator } : {}),
         };
       }),
       unresolved: selection.unresolved,
@@ -589,18 +796,9 @@ export class RoutingRuntime {
       pair: this.profilePair(profile),
       systemPrompt: this.ctx.getSystemPrompt?.() ?? "",
       tools: (this.pi.getAllTools?.() ?? [])
-        .filter((tool: any) =>
-          ROUTING_TOOLS.includes(tool.name)
-            ? tool.name === "freeflow_unit" ||
-              (profile === "coordinator"
-                ? tool.name === "freeflow_delegate"
-                : tool.name === "freeflow_return" || (tool.name === "freeflow_project" && this.projectionEnabled))
-            : this.pi.getActiveTools?.().includes(tool.name),
-        )
+        .filter((tool: any) => this.pi.getActiveTools?.().includes(tool.name))
         .map((tool: any) =>
-          ROUTING_TOOLS.includes(tool.name)
-            ? { ...tool, parameters: schemaForProfile(tool.name, profile === "coordinator") }
-            : tool,
+          ROUTING_TOOLS.includes(tool.name) ? { ...tool, parameters: ROUTING_SCHEMAS[tool.name] } : tool,
         ),
       runtimeMessage: this.runtimeMessage(
         state,
@@ -611,6 +809,35 @@ export class RoutingRuntime {
       restoring,
     });
   }
+  budgetNotice(messages: any[], ctx: any): any | undefined {
+    if (!this.supported()) return;
+    const tools = (this.pi.getAllTools?.() ?? []).filter((tool: any) => this.pi.getActiveTools?.().includes(tool.name));
+    const estimate = estimateRequest(ctx.getSystemPrompt?.() ?? "", tools, messages, ctx.model);
+    if (!estimate.warnings.length) return;
+    return {
+      role: "custom",
+      customType: "freeflow-routing-budget",
+      display: false,
+      content: estimate.warnings.map((warning) => warning.detail).join("\n"),
+      timestamp: 0,
+    };
+  }
+  private ordinaryContext(input: any[]): any[] {
+    try {
+      const sources = this.sources(),
+        associated = sources.associate(input);
+      const mapped = new Map(associated.filter((item) => item.source).map((item) => [item.message, item.source!]));
+      return annotateSources(
+        input,
+        mapped,
+        new Set([...mapped.values()].map((source) => source.ref)),
+        sources,
+        this.token,
+      );
+    } catch {
+      return input;
+    }
+  }
   async context(ctx: any, incoming: any[]): Promise<any[]> {
     this.ctx = ctx;
     const input = incoming.filter(
@@ -621,10 +848,10 @@ export class RoutingRuntime {
         ),
     );
     this.messages = input;
-    if (!this.supported() || !this.store) return input;
+    if (!this.supported() || !this.store) return this.ordinaryContext(input);
     try {
       const state = this.stateData();
-      if (state.control !== "automatic") return input;
+      if (state.control !== "automatic") return this.ordinaryContext(input);
       check(!this.error && !this.store.blocked && state.profile, "routing_blocked", this.error ?? this.store.blocked);
       check(samePair(this.observed(), this.profilePair(state.profile!)), "prepared_pair_mismatch");
       const sources = this.sources(state),
@@ -640,16 +867,19 @@ export class RoutingRuntime {
           },
           JSON.stringify(["attention", state.assessment.handoffId, user]),
         );
-      // New input reaching an already prepared Executor request cannot be rerouted by changing only the live model.
+      // New input reaching an already prepared worker request cannot be rerouted by changing only the live model.
       const outstanding = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+      const worker = outstanding ? this.assignedWorker(state, outstanding.id) : undefined;
       const interrupted =
-        state.profile === "executor" && user !== (outstanding ? this.taskBasis(state, outstanding.id) : undefined);
+        isWorkerProfile(state.profile) &&
+        (state.profile !== worker || user !== (outstanding ? this.workerBasis(state, outstanding.id) : undefined));
       if (!this.turn || this.turn.bound) {
         this.receipts.clear();
         const execution: Execution = {
           id: randomUUID(),
           profile: state.profile!,
           assignmentId: state.assignmentId,
+          recoveryId: state.recoveryId,
           basisUserEntryId: user,
           pair: this.observed()!,
           resultEntryIds: [],
@@ -659,6 +889,7 @@ export class RoutingRuntime {
           id: execution.id,
           profile: execution.profile,
           assignmentId: execution.assignmentId,
+          recoveryId: execution.recoveryId,
           basisUserEntryId: user,
           before,
           pair: execution.pair,
@@ -681,12 +912,12 @@ export class RoutingRuntime {
       check(prepared.ready, "context_unavailable", prepared.problems.map((p) => p.detail).join("; "));
       const known = this.stateData().exposure;
       const added = prepared.fullSources.filter((s) => known.get(s.ref) !== s.hash);
-      if (this.turn.profile === "executor")
+      if (isWorkerProfile(this.turn.profile))
         for (let i = 0; i < added.length; i += 128)
           this.append({
             type: "sources-exposed",
             executionId: this.turn.id,
-            view: "executor",
+            view: this.turn.profile,
             sources: added.slice(i, i + 128).map((s) => ({ ref: s.ref, bodyHash: s.hash })),
           });
       if (interrupted)
@@ -703,7 +934,7 @@ export class RoutingRuntime {
     } catch (error) {
       this.mark(error);
       ctx.abort?.();
-      // Do not send an accidental full Executor history on a projection failure.
+      // Do not send an accidental full worker history on a projection failure.
       return [
         {
           role: "custom",
@@ -711,7 +942,7 @@ export class RoutingRuntime {
           content: `Automatic request blocked: ${this.error}`,
           display: false,
           timestamp: 0,
-          details: { routingInstance: this.token },
+          details: { routingInstance: this.token, routingRequestBlocked: true },
         },
       ];
     }
@@ -722,6 +953,57 @@ export class RoutingRuntime {
   private contextOperation(name: string, input: any): boolean {
     return name === "freeflow_context" && ["archive", "restore", "search", "retrieve"].includes(input?.operation);
   }
+  private handoffOperation(name: string, input: any): boolean {
+    if (name === "freeflow_delegate") return true;
+    if (name === "freeflow_return") return ["submit", "supplement", "retry"].includes(input?.operation);
+    return name === "freeflow_unit" && input?.operation === "recover";
+  }
+  private stableRecoveryPath(path: string): boolean {
+    return (
+      !path.startsWith("@") &&
+      path !== "~" &&
+      !path.startsWith("~/") &&
+      !path.startsWith("file://") &&
+      !/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/u.test(path) &&
+      !(process.platform === "win32" && /^\/(?:mnt\/|cygdrive\/)?[a-z](?:\/|$)/i.test(path))
+    );
+  }
+  private canonicalRecoveryPath(path: string): string {
+    check(this.stableRecoveryPath(path), "recovery_path_unsupported", `Recovery path spelling is unsupported: ${path}`);
+    const requested = resolvePath(this.ctx.cwd, path);
+    check(existsSync(requested), "recovery_path_unavailable", `Recovery path is unavailable: ${path}`);
+    try {
+      return realpathSync(requested);
+    } catch {
+      throw new RoutingError("recovery_path_unavailable", `Recovery path is unavailable: ${path}`);
+    }
+  }
+  private packagedInstruction(path: string): boolean {
+    return this.packageRoots.some((root) => {
+      const inside = relative(root, path);
+      if (!inside || inside.startsWith("..") || resolvePath(root, inside) !== path) return false;
+      return (
+        /^(?:skills|capabilities)\/[^/]+\/SKILL\.md$/.test(inside) ||
+        /^(?:skills|capabilities)\/[^/]+\/references\/[^/]+\.md$/.test(inside)
+      );
+    });
+  }
+  private recoveryReadAllowed(state: State, name: string, input: any): boolean {
+    if (name !== "read" || typeof input?.path !== "string" || !state.recoveryId) return false;
+    const recovery = state.recoveries.get(state.recoveryId);
+    if (!recovery || recovery.state !== "reading" || !this.stableRecoveryPath(input.path)) return false;
+    try {
+      const path = this.canonicalRecoveryPath(input.path);
+      return recovery.paths.includes(path) || this.packagedInstruction(path);
+    } catch {
+      return false;
+    }
+  }
+  private workerBasis(state: State, assignmentId: string): string | null {
+    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);
+  }
   private batch(callId: string, name: string): void {
     check(this.turn?.message, "batch_unavailable");
     const matches = (this.ctx.sessionManager.getBranch() as NativeEntry[]).filter(
@@ -739,14 +1021,16 @@ export class RoutingRuntime {
     this.turn.sourceFingerprint = fingerprint;
     this.turn.message = structuredClone(matches[0].message);
     const calls = (this.turn.message.content ?? []).filter((b: any) => b.type === "toolCall");
-    const handoffs = calls.filter((b: any) => HANDOFF_TOOLS.has(b.name));
+    const handoffs = calls.filter((b: any) => this.handoffOperation(b.name, b.arguments));
     check(
       !handoffs.length ||
         (handoffs.length === 1 &&
-          HANDOFF_TOOLS.has(calls.at(-1)?.name) &&
+          this.handoffOperation(calls.at(-1)?.name, calls.at(-1)?.arguments) &&
           calls.every(
             (b: any) =>
-              HANDOFF_TOOLS.has(b.name) || b.name === "freeflow_project" || this.contextOperation(b.name, b.arguments),
+              this.handoffOperation(b.name, b.arguments) ||
+              b.name === "freeflow_project" ||
+              this.contextOperation(b.name, b.arguments),
           )),
       "invalid_handoff_batch",
       "A handoff must be last and cannot accompany ordinary task tools.",
@@ -770,14 +1054,21 @@ export class RoutingRuntime {
       this.batch(event.toolCallId, name);
       check(!this.error && !this.store?.blocked, "routing_blocked");
       this.openTurn();
-      if (this.turn?.profile === "executor" && !isRouting && !this.contextOperation(name, event.input)) {
+      if (isWorkerProfile(this.turn?.profile) && !isRouting && !this.contextOperation(name, event.input)) {
         const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
-        check(
+        const worker = a ? this.assignedWorker(state, a.id) : undefined;
+        const ordinary =
           a?.state === "outstanding" &&
-            this.turn.basisUserEntryId === this.taskBasis(state, a.id) &&
-            state.profile === "executor",
-          "executor_task_phase_ended",
-        );
+          this.turn.basisUserEntryId === this.taskBasis(state, a.id) &&
+          state.profile === worker &&
+          this.turn.profile === worker;
+        const recovery =
+          a?.state === "returned" &&
+          this.turn.basisUserEntryId === this.workerBasis(state, a.id) &&
+          state.profile === worker &&
+          this.turn.profile === worker &&
+          this.recoveryReadAllowed(state, name, event.input);
+        check(ordinary || recovery, "worker_task_phase_ended");
       }
       return undefined;
     } catch (error) {
@@ -797,8 +1088,14 @@ export class RoutingRuntime {
       this.ctx = ctx;
       try {
         check(!signal?.aborted, "cancelled");
-        if (name === "freeflow_unit" && input.operation === "inspect") return this.result(this.inspectUnit(input));
-        this.assertAvailable(name === "freeflow_delegate" || name === "freeflow_unit" ? "coordinator" : "executor");
+        if (name === "freeflow_unit" && input.operation === "inspect") {
+          check(this.supported(), "routing_unavailable");
+          return this.result(this.inspectUnit(input));
+        }
+        const state = this.stateData();
+        const expected =
+          name === "freeflow_delegate" || name === "freeflow_unit" ? "coordinator" : this.assignedWorker(state);
+        this.assertAvailable(expected);
         const op = this.callOperation(callId, name);
         const cached = this.receipts.get(op);
         if (cached) {
@@ -813,7 +1110,7 @@ export class RoutingRuntime {
               : name === "freeflow_project"
                 ? this.project(input, op)
                 : name === "freeflow_unit"
-                  ? this.unit(input, op)
+                  ? this.unit(input, callId, op)
                   : undefined;
         if (value !== undefined) {
           this.receipts.set(op, { input: canonical(input), value: structuredClone(value) });
@@ -832,7 +1129,13 @@ export class RoutingRuntime {
               ? undefined
               : name === "freeflow_delegate" || name === "freeflow_unit"
                 ? "coordinator"
-                : "executor",
+                : (() => {
+                    try {
+                      return this.assignedWorker(this.stateData());
+                    } catch {
+                      return undefined;
+                    }
+                  })(),
           recoveryAction:
             error instanceof RoutingError &&
             [
@@ -853,26 +1156,48 @@ export class RoutingRuntime {
     return [...this.stateData().events.values()].find(
       (e) =>
         e.operationId === op &&
-        ["delegate-accepted", "return-accepted", "handoff-retry-requested"].includes(e.data.type),
+        [
+          "delegate-accepted",
+          "return-accepted",
+          "recovery-request-accepted",
+          "recovery-supplement-accepted",
+          "recovery-cancelled",
+          "handoff-retry-requested",
+        ].includes(e.data.type),
     );
   }
   private delegate(input: any, callId: string, op: string) {
     const prior = this.duplicate(op);
     if (prior) {
       check(
-        prior.data.type === "delegate-accepted" && prior.data.assignment.contract === input.contract,
+        prior.data.type === "delegate-accepted" &&
+          prior.data.assignment.contract === input.contract &&
+          (input.worker === undefined || prior.data.handoff.to === input.worker),
         "operation_conflict",
       );
       return { status: "accepted", handoff: prior.data.handoff.id, unchanged: true };
     }
     const state = this.stateData();
+    const enabled = this.enabledWorkers();
+    let worker: WorkerProfile;
+    if (input.worker === undefined) {
+      check(enabled.length === 1, "worker_required", "Delegation mode 'both' requires choosing helper or executor.");
+      worker = enabled[0]!;
+    } else {
+      check(isWorkerProfile(input.worker), "invalid_worker");
+      worker = input.worker;
+    }
+    check(enabled.includes(worker), "worker_disabled", `${worker} is not enabled by delegation mode.`);
     const unit = state.unitId
       ? state.units.get(state.unitId)!
       : { id: randomUUID(), objective: input.contract, state: "open" as const, assignmentIds: [] };
     const old = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
     if (input.operation === "replace") check(old?.state === "outstanding" && !this.applying, "no_quiescent_assignment");
     else
-      check(input.operation === "assign" && old?.state !== "outstanding" && !state.pendingId, "assignment_outstanding");
+      check(
+        input.operation === "assign" && old?.state !== "outstanding" && !state.pendingId && !state.recoveryId,
+        "assignment_outstanding",
+      );
     const assignmentId = randomUUID(),
       id = randomUUID();
     const assignment = {
@@ -889,7 +1214,7 @@ export class RoutingRuntime {
       assignmentId,
       text: input.contract,
       from: "coordinator",
-      to: "executor",
+      to: worker,
       executionId: this.turn!.id,
       toolCallId: callId,
       basisUserEntryId: this.turn!.basisUserEntryId,
@@ -919,6 +1244,7 @@ export class RoutingRuntime {
       status: "accepted",
       unit: unit.id,
       assignment: assignmentId,
+      worker,
       handoff: id,
       transition: "pending",
       contract: input.contract,
@@ -937,25 +1263,28 @@ export class RoutingRuntime {
     const state = this.stateData(),
       a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
     check(a, "assignment_missing");
-    const saved = a.returnHandoffId ? state.handoffs.get(a.returnHandoffId) : undefined;
+    const worker = this.assignedWorker(state, a.id);
+    const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
+    const original = a.returnHandoffId ? state.handoffs.get(a.returnHandoffId) : undefined;
+    const supplement = recovery?.supplementHandoffId ? state.handoffs.get(recovery.supplementHandoffId) : undefined;
+    const retryingSupplement = input.operation === "retry" && recovery?.state === "returning";
+    const saved = retryingSupplement || input.operation === "supplement" ? supplement : original;
     const selection = state.selections.get(a.id) ?? emptySelection();
     const duplicate = this.duplicate(op);
     if (duplicate) {
       if (input.operation === "retry") check(duplicate.data.type === "handoff-retry-requested", "operation_conflict");
-      else
+      else {
+        const expected = input.operation === "supplement" ? "recovery-supplement-accepted" : "return-accepted";
         check(
-          duplicate.data.type === "return-accepted" &&
+          duplicate.data.type === expected &&
             duplicate.data.handoff.text === input.report &&
             duplicate.data.handoff.outcome === input.outcome &&
             canonical(duplicate.data.handoff.limitations) === canonical(input.limitations ?? []),
           "operation_conflict",
         );
-      return {
-        status: "accepted",
-        reportSaved: true,
-        unchanged: true,
-        handoff: duplicate.data.handoffId ?? duplicate.data.handoff.id,
-      };
+      }
+      const handoff = duplicate.data.handoffId ?? duplicate.data.handoff.id;
+      return { ...this.returnReadiness(handoff), unchanged: true };
     }
     if (input.operation === "retry") {
       check(saved && ["blocked", "pending"].includes(saved.state), "saved_return_missing");
@@ -971,25 +1300,55 @@ export class RoutingRuntime {
         },
         op,
       );
-      return { ...this.returnReadiness(saved.id), reportUnchanged: true };
+      return {
+        ...this.returnReadiness(saved.id),
+        reportUnchanged: true,
+        supplementUnchanged: saved.kind === "recovery-return",
+      };
+    }
+    if (input.operation === "supplement") {
+      check(
+        recovery &&
+          ["reading", "returning"].includes(recovery.state) &&
+          (!supplement || ["pending", "blocked"].includes(supplement.state)),
+        "recovery_not_returnable",
+      );
+      const h: Handoff = {
+        id: supplement?.id ?? randomUUID(),
+        kind: "recovery-return",
+        assignmentId: a.id,
+        text: input.report,
+        from: worker,
+        to: "coordinator",
+        executionId: this.turn!.id,
+        toolCallId: callId,
+        basisUserEntryId: this.turn!.basisUserEntryId,
+        state: "pending",
+        reportRevision: (supplement?.reportRevision ?? 0) + 1,
+        outcome: input.outcome,
+        limitations: input.limitations ?? [],
+      };
+      this.append({ type: "recovery-supplement-accepted", recoveryId: recovery.id, handoff: h }, op);
+      return this.returnReadiness(h.id);
     }
     check(input.operation === "submit", "invalid_return_operation");
     check(
-      a.state === "outstanding" || (a.state === "returned" && saved && ["pending", "blocked"].includes(saved.state)),
+      a.state === "outstanding" ||
+        (a.state === "returned" && original && ["pending", "blocked"].includes(original.state)),
       "assignment_task_ended",
     );
     const h: Handoff = {
-      id: saved?.id ?? randomUUID(),
+      id: original?.id ?? randomUUID(),
       kind: "return",
       assignmentId: a.id,
       text: input.report,
-      from: "executor",
+      from: worker,
       to: "coordinator",
       executionId: this.turn!.id,
       toolCallId: callId,
       basisUserEntryId: this.turn!.basisUserEntryId,
       state: "pending",
-      reportRevision: (saved?.reportRevision ?? 0) + 1,
+      reportRevision: (original?.reportRevision ?? 0) + 1,
       outcome: input.outcome,
       limitations: input.limitations ?? [],
     };
@@ -997,16 +1356,25 @@ export class RoutingRuntime {
     return this.returnReadiness(h.id);
   }
   private returnReadiness(id: string) {
-    const h = this.stateData().handoffs.get(id)!;
+    const state = this.stateData();
+    const h = state.handoffs.get(id)!;
     const prepared = this.prepared("coordinator", this.messages, id);
+    const isSupplement = h.kind === "recovery-return";
+    const recovery = isSupplement
+      ? [...state.recoveries.values()].find((candidate) => candidate.supplementHandoffId === h.id)
+      : undefined;
     return {
       status: "accepted",
-      reportSaved: true,
+      reportSaved: !isSupplement,
+      supplementSaved: isSupplement,
       handoff: id,
-      reportRevision: h.reportRevision,
+      ...(recovery ? { recovery: recovery.id } : {}),
+      ...(isSupplement ? { supplementRevision: h.reportRevision } : { reportRevision: h.reportRevision }),
       assignmentRef: `assignment:${h.assignmentId}`,
-      reportRef: `report:${h.id}:${h.reportRevision}`,
-      producer: "executor",
+      ...(isSupplement
+        ? { supplementRef: `supplement:${recovery?.id ?? "unknown"}:${h.reportRevision}` }
+        : { reportRef: `report:${h.id}:${h.reportRevision}` }),
+      producer: h.from,
       outcome: h.outcome,
       limitations: h.limitations,
       ready: prepared.ready,
@@ -1017,8 +1385,8 @@ export class RoutingRuntime {
       finalExchangePending: true,
       provisional:
         "The finalized handoff exchange, target configuration and budget are revalidated at turn_end; this is not delivery evidence.",
-      report: h.text,
-      evidence: this.evidenceFacts(this.stateData()),
+      ...(isSupplement ? { supplement: h.text } : { report: h.text }),
+      evidence: this.evidenceFacts(state),
     };
   }
   private project(input: any, op: string) {
@@ -1053,7 +1421,7 @@ export class RoutingRuntime {
         [...sources.byRef.values()]
           .filter(
             (s) =>
-              s.producer === "executor" &&
+              isWorkerProfile(s.producer) &&
               (isTaskEvidence(s) || (scope === "selected" && next.selected.includes(s.ref))) &&
               (scope === "selected"
                 ? next.selected.includes(s.ref)
@@ -1067,12 +1435,14 @@ export class RoutingRuntime {
                 s.message.content?.some((b: any) => b.type === "text" && b.text?.trim())),
           )
           .map((s) => {
+            const locator = sources.locator(s.ref);
             return {
               ref: s.ref,
               kind: s.original ? "assistant-text" : s.message.role,
               producer: s.producer,
               assignment: s.assignmentId,
               toolName: s.message.toolName,
+              ...(locator ? { locator } : {}),
               active: s.active,
               selected: next.selected.includes(s.ref),
               retainedSelection: next.selected.includes(s.ref) && !isTaskEvidence(s),
@@ -1097,7 +1467,7 @@ export class RoutingRuntime {
           },
           otherAssignments: [...sources.byRef.values()].filter(
             (s) =>
-              s.producer === "executor" && s.assignmentId !== a.id && isTaskEvidence(s) && checksFor(s).targetReady,
+              isWorkerProfile(s.producer) && s.assignmentId !== a.id && isTaskEvidence(s) && checksFor(s).targetReady,
           ).length,
         }),
       );
@@ -1149,10 +1519,40 @@ export class RoutingRuntime {
       estimate: { tokens: prepared.estimatedTokens, method: prepared.estimateMethod },
     };
   }
-  private unit(input: any, op: string) {
+  private unit(input: any, callId: string, op: string) {
     const state = this.stateData();
     const prior = [...state.events.values()].find((e) => e.operationId === op);
     if (prior) {
+      if (input.operation === "recover") {
+        check(
+          prior.data.type === "recovery-request-accepted" &&
+            prior.data.recovery.request === input.request &&
+            canonical(prior.data.recovery.requestedPaths) === canonical([...new Set<string>(input.paths ?? [])]),
+          "operation_conflict",
+        );
+        const { recovery, handoff } = prior.data;
+        return {
+          status: "accepted",
+          unchanged: true,
+          recovery: recovery.id,
+          handoff: handoff.id,
+          assignmentRef: `assignment:${recovery.assignmentId}`,
+          reportRef: `report:${recovery.assessmentHandoffId}:${recovery.baseReportRevision}`,
+          request: recovery.request,
+          paths: recovery.paths,
+          transition: handoff.state,
+        };
+      }
+      if (input.operation === "cancel-recovery") {
+        check(prior.data.type === "recovery-cancelled" && prior.data.reason === input.reason, "operation_conflict");
+        return {
+          status: "cancelled",
+          unchanged: true,
+          recovery: prior.data.recoveryId,
+          reason: prior.data.reason,
+          assessment: state.assessment?.handoffId,
+        };
+      }
       check(
         (input.operation === "assess" && prior.data.type === "assessment-resumed") ||
           (input.operation === "close" &&
@@ -1163,18 +1563,95 @@ export class RoutingRuntime {
       );
       return { status: "unchanged", operation: input.operation };
     }
+    if (input.operation === "recover") {
+      const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+      const base = a?.returnHandoffId ? state.handoffs.get(a.returnHandoffId) : undefined;
+      check(
+        state.unitId &&
+          a?.state === "returned" &&
+          base?.kind === "return" &&
+          base.state === "configured" &&
+          state.assessment?.handoffId === base.id &&
+          !state.pendingId &&
+          !state.recoveryId &&
+          !this.applying,
+        "recovery_not_available",
+      );
+      const worker = this.assignedWorker(state, a.id);
+      const id = randomUUID(),
+        handoffId = randomUUID();
+      const paths = [...new Set<string>((input.paths ?? []).map((path: string) => this.canonicalRecoveryPath(path)))];
+      const recovery: Recovery = {
+        id,
+        assignmentId: a.id,
+        assessmentHandoffId: base.id,
+        baseReportRevision: base.reportRevision,
+        request: input.request,
+        requestedPaths: [...new Set<string>(input.paths ?? [])],
+        paths,
+        state: "requested",
+        requestHandoffId: handoffId,
+        supplementRevision: 0,
+      };
+      const handoff: Handoff = {
+        id: handoffId,
+        kind: "recovery-request",
+        assignmentId: a.id,
+        text: input.request,
+        from: "coordinator",
+        to: worker,
+        executionId: this.turn!.id,
+        toolCallId: callId,
+        basisUserEntryId: this.turn!.basisUserEntryId,
+        state: "pending",
+        reportRevision: 0,
+        limitations: [],
+      };
+      this.append({ type: "recovery-request-accepted", recovery, handoff }, op);
+      return {
+        status: "accepted",
+        recovery: id,
+        handoff: handoffId,
+        assignmentRef: `assignment:${a.id}`,
+        reportRef: `report:${base.id}:${base.reportRevision}`,
+        request: input.request,
+        paths,
+        transition: "pending",
+      };
+    }
+    if (input.operation === "cancel-recovery") {
+      check(state.recoveryId && !this.applying, "recovery_not_cancellable");
+      check(
+        ![...state.executions.values()].some(
+          (execution) =>
+            execution.recoveryId === state.recoveryId &&
+            isWorkerProfile(execution.profile) &&
+            !execution.assistantEntryId &&
+            !execution.interrupted,
+        ),
+        "recovery_not_cancellable",
+      );
+      this.append({ type: "recovery-cancelled", recoveryId: state.recoveryId, reason: input.reason }, op);
+      return {
+        status: "cancelled",
+        recovery: state.recoveryId,
+        reason: input.reason,
+        assessment: state.assessment?.handoffId,
+      };
+    }
     if (input.operation === "assess") {
       check(state.assessment, "assessment_missing");
+      check(!state.recoveryId, "recovery_outstanding");
       if (state.assessment.view === "active") return { status: "unchanged", ready: true };
       const prepared = this.prepared("coordinator", this.messages, state.assessment.handoffId, true);
       if (!prepared.ready) return { status: "suspended", ready: false, problems: prepared.problems };
-      check(prepared.reservation, "reservation_missing");
+      if (this.projectionEnabled) check(prepared.reservation, "reservation_missing");
       this.append(
         {
           type: "assessment-resumed",
           handoffId: state.assessment.handoffId,
           basisUserEntryId: this.turn!.basisUserEntryId,
-          reservation: prepared.reservation,
+          ...(prepared.reservation ? { reservation: prepared.reservation } : {}),
         },
         op,
       );
@@ -1189,6 +1666,19 @@ export class RoutingRuntime {
     check(input.operation === "close" && state.unitId, "unit_missing");
     const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
     check(!this.applying, "not_quiescent");
+    if (state.recoveryId) {
+      check(input.outcome !== "accepted", "unfinished_work");
+      check(
+        ![...state.executions.values()].some(
+          (execution) =>
+            execution.recoveryId === state.recoveryId &&
+            isWorkerProfile(execution.profile) &&
+            !execution.assistantEntryId &&
+            !execution.interrupted,
+        ),
+        "not_quiescent",
+      );
+    }
     this.append(
       {
         type: "unit-closed",
@@ -1279,6 +1769,7 @@ export class RoutingRuntime {
         [...state.assignments.values()].reverse().map((a) => {
           const u = state.units.get(a.unitId),
             h = a.returnHandoffId ? state.handoffs.get(a.returnHandoffId) : undefined;
+          const delegate = state.handoffs.get(a.delegateHandoffId);
           return {
             ref: `assignment:${a.id}`,
             unitRef: `unit:${a.unitId}`,
@@ -1290,8 +1781,8 @@ export class RoutingRuntime {
             summary: a.contract.slice(0, 160),
             reportAvailable: !!h,
             outcome: h?.outcome,
-            from: "coordinator",
-            to: "executor",
+            from: delegate?.from,
+            to: delegate?.to,
           };
         });
       const page = this.page("work-history", rows, input.cursor, input.limit ?? 20);
@@ -1310,9 +1801,9 @@ export class RoutingRuntime {
       "Use a ref returned by history inspection.",
     );
     check(
-      /^(?:(?:unit|assignment):[^:\s]+|report:[^:\s]+:[1-9][0-9]*)$/.test(input.ref),
+      /^(?:(?:unit|assignment|recovery):[^:\s]+|(?:report|supplement):[^:\s]+:[1-9][0-9]*)$/.test(input.ref),
       "invalid_work_ref",
-      "Use assignmentRef or reportRef from the return receipt, or a work ref returned by inspection, unchanged. A bare handoff ID is not a work ref.",
+      "Use assignment, report, recovery, or supplement refs returned by a receipt or inspection, unchanged. A bare handoff ID is not a work ref.",
     );
     if (input.ref.startsWith("unit:")) {
       const u = state.units.get(input.ref.slice(5));
@@ -1335,6 +1826,63 @@ export class RoutingRuntime {
         historical: true,
       };
     }
+    if (input.ref.startsWith("recovery:")) {
+      const recovery = state.recoveries.get(input.ref.slice(9));
+      check(recovery, "work_unavailable", "Recovery is not on current ancestry.");
+      const request = state.handoffs.get(recovery.requestHandoffId);
+      const supplement = recovery.supplementHandoffId ? state.handoffs.get(recovery.supplementHandoffId) : undefined;
+      return {
+        status: "inspected",
+        view,
+        ref: input.ref,
+        historical: recovery.id !== state.recoveryId,
+        recovery: {
+          id: recovery.id,
+          state: recovery.state,
+          assignmentId: recovery.assignmentId,
+          assessmentHandoffId: recovery.assessmentHandoffId,
+          baseReportRevision: recovery.baseReportRevision,
+          request: recovery.request,
+          paths: recovery.paths,
+          requestHandoffState: request?.state,
+          supplementRevision: recovery.supplementRevision,
+          cancellationReason: recovery.cancellationReason,
+        },
+        supplementRef: supplement ? `supplement:${recovery.id}:${supplement.reportRevision}` : undefined,
+        sourceBoundary: "Saved recovery on current ancestry; historical content grants no current permission.",
+      };
+    }
+    if (input.ref.startsWith("supplement:")) {
+      const match = /^supplement:([^:]+):([0-9]+)$/.exec(input.ref);
+      check(match, "work_unavailable", "Use a supplement ref returned by a receipt or recovery inspection.");
+      const recovery = state.recoveries.get(match[1]);
+      let supplement: Handoff | undefined;
+      for (const event of state.events.values())
+        if (
+          event.data.type === "recovery-supplement-accepted" &&
+          event.data.recoveryId === match[1] &&
+          event.data.handoff.reportRevision === Number(match[2])
+        )
+          supplement = event.data.handoff;
+      check(recovery && supplement, "work_unavailable", "Supplement revision is not on current ancestry.");
+      const base = state.handoffs.get(recovery.assessmentHandoffId);
+      return {
+        status: "inspected",
+        view,
+        ref: input.ref,
+        historical: true,
+        recoveryRef: `recovery:${recovery.id}`,
+        assignment: { id: recovery.assignmentId, state: state.assignments.get(recovery.assignmentId)?.state },
+        reportRef: `report:${recovery.assessmentHandoffId}:${recovery.baseReportRevision}`,
+        report: base?.text,
+        supplement: supplement.text,
+        supplementRevision: supplement.reportRevision,
+        outcome: supplement.outcome,
+        limitations: supplement.limitations,
+        sourceBoundary:
+          "Saved supplement revision and original report linkage on current ancestry; historical content grants no current permission.",
+      };
+    }
     let savedRevision: Handoff | undefined;
     if (input.ref.startsWith("report:")) {
       const match = /^report:([^:]+):([0-9]+)$/.exec(input.ref);
@@ -1383,8 +1931,23 @@ export class RoutingRuntime {
     return {
       ...this.state(),
       unit: unit ? { id: unit.id, state: unit.state, assignments: unit.assignmentIds.length } : null,
-      assignment: a ? { id: a.id, state: a.state } : null,
+      assignment: a ? { id: a.id, state: a.state, worker: this.assignedWorker(state, a.id) } : null,
       pendingHandoff: state.pendingId ?? null,
+      recovery: state.recoveryId
+        ? (() => {
+            const recovery = state.recoveries.get(state.recoveryId!);
+            return recovery
+              ? {
+                  id: recovery.id,
+                  state: recovery.state,
+                  assignmentId: recovery.assignmentId,
+                  assessmentHandoffId: recovery.assessmentHandoffId,
+                  paths: recovery.paths,
+                  supplementRevision: recovery.supplementRevision,
+                }
+              : null;
+          })()
+        : null,
       assessment: state.assessment
         ? { handoffId: state.assessment.handoffId, view: state.assessment.view, problems: state.assessment.problems }
         : null,
@@ -1471,23 +2034,29 @@ export class RoutingRuntime {
       "source_exchange_incomplete",
       "The saved handoff has an incomplete native exchange; reconcile or explicitly dispose of it.",
     );
-    if (h.kind === "return" && this.projectionEnabled) {
+    let attentionProblems: Problem[] = [];
+    if (["return", "recovery-return"].includes(h.kind) && this.projectionEnabled) {
       const prepared = this.prepared("coordinator", inputs, h.id);
       if (!prepared.ready) {
+        const attentionFallback = h.kind === "recovery-return" && h.outcome !== "completed";
         this.projectionError = prepared.problems.map((p) => p.code).join(", ");
-        this.append({
-          type: "handoff-state",
-          handoffId: h.id,
-          state: "blocked",
-          reason: prepared.problems
-            .map((p) => p.detail)
-            .join("; ")
-            .slice(0, 4096),
-        });
-        return;
+        if (attentionFallback) attentionProblems = prepared.problems;
+        else {
+          this.append({
+            type: "handoff-state",
+            handoffId: h.id,
+            state: "blocked",
+            reason: prepared.problems
+              .map((p) => p.detail)
+              .join("; ")
+              .slice(0, 4096),
+          });
+          return;
+        }
+      } else {
+        check(prepared.reservation, "reservation_missing");
+        this.append({ type: "handoff-prepared", handoffId: h.id, reservation: prepared.reservation });
       }
-      check(prepared.reservation, "reservation_missing");
-      this.append({ type: "handoff-prepared", handoffId: h.id, reservation: prepared.reservation });
     }
     try {
       const current = this.stateData();
@@ -1497,6 +2066,28 @@ export class RoutingRuntime {
       this.append({ type: "handoff-state", handoffId: h.id, state: "configured", observedPair: this.observed() });
       const completed = this.stateData();
       const reservation = completed.reservations.get(h.id);
+      const recovery =
+        h.kind === "recovery-return"
+          ? [...completed.recoveries.values()].find((candidate) => candidate.supplementHandoffId === h.id)
+          : undefined;
+      if (h.kind === "recovery-return" && recovery && completed.assessment?.view === "suspended") {
+        if (attentionProblems.length) {
+          this.append({
+            type: "assessment-suspended",
+            handoffId: recovery.assessmentHandoffId,
+            reason: "delivery-gap",
+            basisUserEntryId: this.lastDeliveredUser(this.sources(completed), inputs),
+            problems: attentionProblems,
+          });
+        } else if (completed.assessment.suspensionReason === "recovery") {
+          this.append({
+            type: "assessment-resumed",
+            handoffId: recovery.assessmentHandoffId,
+            basisUserEntryId: this.lastDeliveredUser(this.sources(completed), inputs),
+            ...(reservation ? { reservation } : {}),
+          });
+        }
+      }
       if (h.kind === "return" && completed.assessment?.view === "suspended" && reservation) {
         this.append({
           type: "assessment-resumed",
@@ -1505,7 +2096,7 @@ export class RoutingRuntime {
           reservation,
         });
       }
-      this.projectionError = undefined;
+      if (!attentionProblems.length) this.projectionError = undefined;
     } catch (error) {
       if (this.current(subject) && !this.store?.blocked && !this.error && this.stateData().pendingId === h.id) {
         this.append({
@@ -1515,7 +2106,7 @@ export class RoutingRuntime {
           reason: error instanceof Error ? error.message.slice(0, 4096) : "configuration_failed",
         });
         this.ctx.ui?.notify?.(
-          `Couldn’t switch to ${h.to === "coordinator" ? "Coordinator" : "Executor"} — ${h.kind === "return" ? "report" : "assignment"} saved.`,
+          `Couldn’t switch to ${h.to.charAt(0).toUpperCase()}${h.to.slice(1)} — ${["return", "recovery-return"].includes(h.kind) ? "report" : "assignment"} saved.`,
           "warning",
         );
       } else throw error;
@@ -1541,7 +2132,7 @@ export class RoutingRuntime {
     check(
       !ctx.hasPendingMessages?.(),
       "pending_input",
-      "Queued input must be delivered and reconciled before resuming Executor.",
+      "Queued input must be delivered and reconciled before resuming a worker.",
     );
     const pending = state.pendingId ? state.handoffs.get(state.pendingId) : undefined;
     if (pending) {
@@ -1551,17 +2142,18 @@ export class RoutingRuntime {
       this.guard(subject);
       if (this.stateData().pendingId) {
         check(
-          pending.kind === "return" && this.projectionError,
+          ["return", "recovery-return"].includes(pending.kind) && this.projectionError,
           "handoff_still_blocked",
           "Saved transfer is still blocked; reconcile its configuration before retrying.",
         );
+        const worker = this.assignedWorker(this.stateData(), pending.assignmentId);
         this.append({
           type: "control",
           control: "automatic",
-          profile: "executor",
+          profile: worker,
           reason: "Explicit resume of saved-return evidence correction only; ordinary assignment work remains ended",
         });
-        await this.applyPair(this.profilePair("executor"));
+        await this.applyPair(this.profilePair(worker));
       }
     } else {
       const assignment = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
@@ -1571,7 +2163,22 @@ export class RoutingRuntime {
         (x) =>
           x.profile === "coordinator" && x.basisUserEntryId === user && x.assistantEntryId && x.outcome === "completed",
       );
-      if (assignment?.state === "outstanding") {
+      const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
+      const worker = assignment ? this.assignedWorker(state, assignment.id) : undefined;
+      if (assignment?.state === "returned" && recovery?.state === "reading") {
+        check(
+          user === this.workerBasis(state, assignment.id) || coordinatorSawInput,
+          "input_unreconciled",
+          "New input needs Coordinator attention before evidence recovery can resume.",
+        );
+        this.append({
+          type: "control",
+          control: "automatic",
+          profile: worker!,
+          reason: "Explicit user resume of unchanged evidence recovery; ordinary assignment work remains ended",
+        });
+        await this.applyPair(this.profilePair(worker!));
+      } else if (assignment?.state === "outstanding") {
         check(
           user === this.taskBasis(state, assignment.id) || coordinatorSawInput,
           "input_unreconciled",
@@ -1581,10 +2188,10 @@ export class RoutingRuntime {
         this.append({
           type: "control",
           control: "automatic",
-          profile: "executor",
+          profile: worker!,
           reason: "Explicit user resume of the unchanged assignment; current restrictions remain applicable",
         });
-        await this.applyPair(this.profilePair("executor"));
+        await this.applyPair(this.profilePair(worker!));
       } else await this.applyPair(this.profilePair("coordinator"));
     }
     this.guard(subject);
@@ -1621,7 +2228,7 @@ export class RoutingRuntime {
       check(
         words.length === 2 && [...PROFILES, "auto"].includes(words[1]),
         "invalid_profile_command",
-        "Use /freeflow profile coordinator|executor|auto|history, or /freeflow resume.",
+        "Use /freeflow profile coordinator|helper|executor|auto|history, or /freeflow resume.",
       );
       const result =
         words[1] === "auto" ? await this.setAutomaticControl() : await this.setManualProfile(words[1] as Profile);