token-harness 0.1.27 → 0.1.28

package/token-harness.mjs

@@ -70,7 +70,7 @@ function assessMcpServer(server) {
   const status = [server.runtimeStatus, server.authStatus].filter((value3) => value3 !== null).join(" ").toLowerCase();
   const usability = status.includes("disabled") ? "disabled" : /fail|error|needs authentication|authenticationrequired|unauthenticated/.test(status) ? "attention" : /connected|running|ready/.test(status) ? "usable" : "unknown";
   const action = usability === "attention" ? "fix-or-disable-if-unneeded" : exposure === "high" ? "review-exposure" : "none";
-  const reason3 = usability === "attention" ? "the server is not currently usable; task relevance is still unknown" : exposure === "high" ? "the server exposes at least 20 known tools; usage and task relevance are not observed" : exposure === "moderate" ? "the server exposes 10-19 known tools; usage and task relevance are not observed" : exposure === "low" ? "the server exposes fewer than 10 known tools; usage and task relevance are not observed" : "tool exposure is unknown; usage and task relevance are not observed";
+  const reason4 = usability === "attention" ? "the server is not currently usable; task relevance is still unknown" : exposure === "high" ? "the server exposes at least 20 known tools; usage and task relevance are not observed" : exposure === "moderate" ? "the server exposes 10-19 known tools; usage and task relevance are not observed" : exposure === "low" ? "the server exposes fewer than 10 known tools; usage and task relevance are not observed" : "tool exposure is unknown; usage and task relevance are not observed";
   return {
     harnessId: server.harnessId,
     name: server.name,
@@ -79,7 +79,7 @@ function assessMcpServer(server) {
     usability,
     action,
     hasRemovalEvidence: false,
-    reason: reason3
+    reason: reason4
   };
 }
 function benchmarkPolicySnapshot(observation) {
@@ -434,12 +434,12 @@ function assessWindowPace(window, now, reservePercent) {
     spendableRemainingPercent: null,
     spendablePercentPerHour: null
   };
-  const unknown = (reason3) => ({
+  const unknown = (reason4) => ({
     ...base,
     state: "unknown",
     targetUsedPercent: null,
     minutesToReset: null,
-    reason: reason3
+    reason: reason4
   });
   if (window.confidence === "cached" || window.confidence === "estimated") {
     return unknown("cached or estimated usage is displayed but not used for live pacing");
@@ -1531,6 +1531,264 @@ var init_context_governor = __esm({
 });
 
 // packages/core/dist/src/domain/efficiency-decision.js
+function reason(code, summary) {
+  return { code, summary };
+}
+function isEfficiencyHarness(value3) {
+  return value3 === "claude" || value3 === "codex";
+}
+function uniqueSorted(items) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const item of items)
+    unique.set(`${item.code}\0${item.summary}`, item);
+  return [...unique.values()].sort((left, right) => left.code.localeCompare(right.code) || left.summary.localeCompare(right.summary));
+}
+function uniqueSortedEvidence(items) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    unique.set(`${item.source}\0${item.code}\0${item.summary}`, item);
+  }
+  return [...unique.values()].sort((left, right) => left.source.localeCompare(right.source) || left.code.localeCompare(right.code) || left.summary.localeCompare(right.summary));
+}
+function addEvidence(target, source, items) {
+  for (const item of items)
+    target.push({ source, ...item });
+}
+function chooseHarness(input, evidence4, reasons) {
+  const scheduler = input.scheduler;
+  if (scheduler === null || scheduler === void 0) {
+    reasons.push(reason("efficiency-harness-kept", "No compatible scheduler decision was supplied; keep the current harness"));
+    return input.currentHarness;
+  }
+  addEvidence(evidence4, "scheduler", scheduler.reasons);
+  if (scheduler.taskClass !== input.taskClass || scheduler.currentHarness !== input.currentHarness || !isEfficiencyHarness(scheduler.candidateHarness)) {
+    reasons.push(reason("efficiency-scheduler-mismatch", "Scheduler evidence does not match this harness and task-class snapshot; keep the current harness"));
+    return input.currentHarness;
+  }
+  if (scheduler.decision !== "switch") {
+    reasons.push(reason(scheduler.decision === "stay" ? "efficiency-scheduler-stay" : "efficiency-scheduler-unknown", scheduler.decision === "stay" ? "The existing scheduler recommends keeping the current harness" : "The existing scheduler lacks evidence for a cross-harness recommendation"));
+    return input.currentHarness;
+  }
+  const candidate = scheduler.candidateHarness;
+  const advice = input.optimization.filter((item) => item.harnessId === candidate);
+  if (advice.length !== 1 || advice[0].state === "absent" || advice[0].state === "unavailable") {
+    reasons.push(reason("efficiency-candidate-policy-unavailable", "The scheduler recommends the candidate, but one usable candidate policy snapshot is not available; keep the current harness"));
+    return input.currentHarness;
+  }
+  reasons.push(reason("efficiency-scheduler-switch-advised", "The evidence-backed scheduler recommends the candidate harness; this decision remains read-only"));
+  return candidate;
+}
+function chooseContextAction(advice, contextGovernorAction) {
+  if (advice.state === "absent" || advice.state === "unavailable")
+    return "unknown";
+  if (advice.budgetDecision?.state === "wait-for-reset" && advice.budgetDecision.reasons.length > 0 || advice.workloadCoverage?.state === "exhausted" && advice.workloadCoverage.reasons.length > 0 || advice.workloadCoverage?.state === "shortfall" && advice.workloadCoverage.reasons.length > 0) {
+    return "checkpoint";
+  }
+  if (contextGovernorAction !== null)
+    return contextGovernorAction;
+  if (advice.contextPressure === "low")
+    return "keep";
+  return "unknown";
+}
+function contextGovernorForHarness(input, harness, reasons) {
+  const snapshot = input.contextGovernor;
+  if (snapshot === null || snapshot === void 0)
+    return null;
+  if (snapshot.harnessId !== harness) {
+    reasons.push(reason("efficiency-context-governor-harness-mismatch", "Ignore context material evidence because it belongs to a different harness snapshot"));
+    return null;
+  }
+  return decideContextGovernor(snapshot);
+}
+function contextActionSummary(action) {
+  switch (action) {
+    case "keep":
+      return "Keep the observed context because no safer item-level reduction is supported";
+    case "mask":
+      return "Deterministically mask explicitly superseded tool or repository output";
+    case "summarize":
+      return "Condense durable material only where no reducer has already summarized it";
+    case "compact":
+      return "Compact durable state for the continuing task within its configured byte budget";
+    case "checkpoint":
+      return "Preserve durable task state before an observed allowance, reset or task boundary";
+    case "fresh-session":
+      return "Start a fresh session at the evidenced task boundary";
+    case "unknown":
+      return "Context evidence is incomplete; do not invent a cleanup action";
+  }
+}
+function recommendationEvidence(advice, area, target) {
+  return advice.recommendations.filter((item) => item.area === area && item.target === target).flatMap((item) => item.evidence);
+}
+function hasLearnedControlEvidence(advice, area, current, recommended, support) {
+  const codes = new Set(support.map((item) => item.code));
+  if (area === "model") {
+    const learning2 = advice.modelLearning;
+    return learning2?.state === "learned" && learning2.baseModel === current && learning2.candidateModel === recommended && learning2.recommendedModel === recommended && learning2.policy.reasoningEffort === advice.currentEffort && learning2.policy.verbosity === advice.currentVerbosity && (codes.has("model-allowance-throughput-improved") || codes.has("model-quality-recovery-with-capacity"));
+  }
+  const learning = advice.verbosityLearning;
+  return learning?.state === "learned" && learning.baseVerbosity === current && learning.candidateVerbosity === recommended && learning.recommendedVerbosity === recommended && learning.policy.model === advice.currentModel && learning.policy.reasoningEffort === advice.currentEffort && (codes.has("verbosity-allowance-throughput-improved") || codes.has("verbosity-quality-recovery-with-capacity") || codes.has("verbosity-quality-recovery-capacity-unproven"));
+}
+function choosePolicy(advice, choices, taskClass, contextAction, evidence4, reasons) {
+  const selected = Object.fromEntries(choices.map((choice) => [choice.area, choice.current]));
+  if (choices.filter((choice) => choice.recommended !== null && choice.recommended !== choice.current).length > 1) {
+    reasons.push(reason("efficiency-single-control-guard", "Keep the observed policy because more than one native control would change at once"));
+    return selected;
+  }
+  const supportedChanges = choices.filter((choice) => {
+    if (choice.recommended === null || choice.recommended === choice.current)
+      return false;
+    const support = recommendationEvidence(advice, choice.area, choice.recommended);
+    if (support.length === 0) {
+      reasons.push(reason(`efficiency-${choice.area}-evidence-missing`, `Keep the current ${choice.area} because the recommendation has no attributable evidence`));
+      return false;
+    }
+    if ((choice.area === "model" || choice.area === "verbosity") && !hasLearnedControlEvidence(advice, choice.area, choice.current, choice.recommended, support)) {
+      reasons.push(reason(`efficiency-${choice.area}-learning-unproven`, `Keep the current ${choice.area} because the exact single-control learning gate is not evidenced`));
+      return false;
+    }
+    addEvidence(evidence4, "optimizer", support);
+    return true;
+  });
+  const change = supportedChanges[0];
+  if (change === void 0)
+    return selected;
+  if (change.area === "reasoning") {
+    const recommendedRank = effortRank(change.recommended);
+    const floorRank = effortRank(taskEffortFloor(taskClass));
+    if (recommendedRank !== null && floorRank !== null && recommendedRank < floorRank) {
+      reasons.push(reason("efficiency-quality-floor-protected", "Keep the observed reasoning effort because the recommendation falls below the task quality floor"));
+      return selected;
+    }
+    const currentRank = effortRank(change.current);
+    if (contextAction !== "keep" && currentRank !== null && recommendedRank !== null && recommendedRank > currentRank && advice.budgetDecision?.allowEffortIncrease === true) {
+      reasons.push(reason("efficiency-context-before-quota-escalation", "Keep the observed reasoning effort until the recommended context action is completed"));
+      return selected;
+    }
+  }
+  selected[change.area] = change.recommended;
+  reasons.push(reason(`efficiency-${change.area}-selected`, `Use the existing evidence-backed ${change.area} recommendation as the single policy change`));
+  return selected;
+}
+function exactCapacityBudget(input, harness, policy, evidence4, reasons) {
+  const empty2 = { fiveHourPercent: null, weeklyPercent: null };
+  const matches = (input.capacities ?? []).filter((item) => item.harnessId === harness && item.taskClass === input.taskClass && item.policy !== void 0 && item.policy.model === policy.model && item.policy.reasoningEffort === policy.reasoningEffort && item.policy.verbosity === policy.verbosity);
+  if (matches.length !== 1) {
+    reasons.push(reason(matches.length === 0 ? "efficiency-task-budget-unknown" : "efficiency-task-budget-ambiguous", matches.length === 0 ? "Exact-policy accepted-task capacity is unavailable; task allowance budgets remain unknown" : "Multiple exact-policy capacity estimates were supplied; task allowance budgets remain unknown"));
+    return empty2;
+  }
+  const capacity = matches[0];
+  const fiveHour = capacity.fiveHour.p75UsedPercentPerAcceptedTask;
+  const weekly = capacity.weekly.p75UsedPercentPerAcceptedTask;
+  const valid = (value3) => value3 !== null && Number.isFinite(value3) && value3 > 0 && value3 <= 100;
+  const fiveHourSpendable = capacity.fiveHour.spendableRemainingPercent;
+  const weeklySpendable = capacity.weekly.spendableRemainingPercent;
+  if (capacity.status !== "estimated" || !valid(fiveHour) || !valid(weekly) || fiveHourSpendable === null || !Number.isFinite(fiveHourSpendable) || fiveHourSpendable < fiveHour || weeklySpendable === null || !Number.isFinite(weeklySpendable) || weeklySpendable < weekly) {
+    addEvidence(evidence4, "capacity", capacity.reasons.map((summary, index) => ({
+      code: `capacity-reason-${String(index + 1)}`,
+      summary
+    })));
+    reasons.push(reason("efficiency-task-budget-unknown", "Complete exact-policy task cost must fit within both observed spendable allowances after reserve"));
+    return empty2;
+  }
+  evidence4.push({
+    source: "capacity",
+    code: "exact-policy-task-cost",
+    summary: `Accepted-task p75 cost is ${String(fiveHour)}% five-hour and ${String(weekly)}% weekly at the selected model/effort/verbosity policy`
+  });
+  for (const window of [capacity.fiveHour, capacity.weekly]) {
+    for (const receiptId of window.receiptIds ?? [])
+      evidence4.push({
+        source: "capacity",
+        code: `capacity-receipt-${window.scope}`,
+        summary: receiptId
+      });
+  }
+  reasons.push(reason("efficiency-task-budget-evidenced", "Keep five-hour and weekly task budgets separate at their exact-policy empirical p75 costs"));
+  return { fiveHourPercent: fiveHour, weeklyPercent: weekly };
+}
+function attemptBudget(input, evidence4, reasons) {
+  const budget = input.attemptBudget;
+  if (budget === null || budget === void 0 || !Number.isSafeInteger(budget.maxAttempts) || budget.maxAttempts < 1 || !Number.isSafeInteger(budget.premiumEscalations) || budget.premiumEscalations < 0 || budget.premiumEscalations >= budget.maxAttempts || budget.evidence.length === 0) {
+    reasons.push(reason("efficiency-attempt-budget-unknown", "No reviewed evidence-backed attempt and premium-escalation budget is available"));
+    return { maxAttempts: null, premiumEscalationBudget: null };
+  }
+  addEvidence(evidence4, "attempt-budget", budget.evidence);
+  reasons.push(reason("efficiency-attempt-budget-evidenced", "Use the supplied evidence-backed attempt and premium-escalation ceilings"));
+  return {
+    maxAttempts: budget.maxAttempts,
+    premiumEscalationBudget: budget.premiumEscalations
+  };
+}
+function decideEfficiency(input) {
+  const evidence4 = [];
+  const reasons = [];
+  const harness = chooseHarness(input, evidence4, reasons);
+  const matchingAdvice = input.optimization.filter((item) => item.harnessId === harness);
+  const advice = matchingAdvice.length === 1 ? matchingAdvice[0] : null;
+  const contextGovernor = contextGovernorForHarness(input, harness, reasons);
+  if (contextGovernor !== null)
+    addEvidence(evidence4, "context", contextGovernor.evidence);
+  if (advice === null || advice.state === "absent" || advice.state === "unavailable") {
+    reasons.push(reason(advice !== null ? "efficiency-optimizer-evidence-unavailable" : matchingAdvice.length === 0 ? "efficiency-optimizer-evidence-missing" : "efficiency-optimizer-evidence-ambiguous", "One optimizer snapshot is required for the selected harness; policy remains unknown and context uses only its separate evidence"));
+    const contextAction2 = contextGovernor?.action ?? "unknown";
+    reasons.push(reason(`efficiency-context-${contextAction2}`, contextActionSummary(contextAction2)));
+    const attempts2 = attemptBudget(input, evidence4, reasons);
+    return {
+      harness,
+      taskClass: input.taskClass,
+      model: null,
+      reasoningEffort: null,
+      verbosity: null,
+      contextAction: contextAction2,
+      contextGovernor,
+      allowanceBudget: { fiveHourPercent: null, weeklyPercent: null },
+      ...attempts2,
+      evidence: uniqueSortedEvidence(evidence4),
+      reasons: uniqueSorted(reasons)
+    };
+  }
+  addEvidence(evidence4, "budget", advice.budgetDecision?.reasons ?? []);
+  addEvidence(evidence4, "capacity", advice.workloadCoverage?.reasons ?? []);
+  const contextEvidence2 = advice.recommendations.filter((item) => item.area === "context" || item.area === "session").flatMap((item) => item.evidence);
+  const contextAction = chooseContextAction(advice, contextGovernor?.action ?? null);
+  addEvidence(evidence4, "context", contextEvidence2);
+  reasons.push(reason(`efficiency-context-${contextAction}`, contextActionSummary(contextAction)));
+  const policy = choosePolicy(advice, [
+    { area: "model", current: advice.currentModel, recommended: advice.recommendedModel },
+    { area: "reasoning", current: advice.currentEffort, recommended: advice.recommendedEffort },
+    {
+      area: "verbosity",
+      current: advice.currentVerbosity,
+      recommended: advice.recommendedVerbosity
+    }
+  ], input.taskClass, contextAction, evidence4, reasons);
+  const selectedRank = effortRank(policy.reasoning);
+  const floorRank = effortRank(taskEffortFloor(input.taskClass));
+  if (selectedRank !== null && floorRank !== null && selectedRank < floorRank) {
+    policy.reasoning = null;
+    reasons.push(reason("efficiency-observed-effort-below-floor", "Neither the observed effort nor a supported recommendation establishes the task quality floor"));
+  }
+  const selectedPolicy = {
+    model: policy.model,
+    reasoningEffort: policy.reasoning,
+    verbosity: policy.verbosity
+  };
+  const allowanceBudget = exactCapacityBudget(input, harness, selectedPolicy, evidence4, reasons);
+  const attempts = attemptBudget(input, evidence4, reasons);
+  return {
+    harness,
+    taskClass: input.taskClass,
+    ...selectedPolicy,
+    contextAction,
+    contextGovernor,
+    allowanceBudget,
+    ...attempts,
+    evidence: uniqueSortedEvidence(evidence4),
+    reasons: uniqueSorted(reasons)
+  };
+}
 var init_efficiency_decision = __esm({
   "packages/core/dist/src/domain/efficiency-decision.js"() {
     "use strict";
@@ -1708,7 +1966,7 @@ var init_cross_harness_quality = __esm({
 });
 
 // packages/core/dist/src/domain/cross-harness-scheduler.js
-function reason(code, summary) {
+function reason2(code, summary) {
   return { code, summary };
 }
 function hasPressure(evidence4, tasksRemaining) {
@@ -1720,24 +1978,24 @@ function hasSafeHeadroom(evidence4, tasksRemaining) {
 }
 function validateTransfer(transfer) {
   if (!Number.isInteger(transfer.handoffBytes) || transfer.handoffBytes < 0 || !Number.isInteger(transfer.maxHandoffBytes) || transfer.maxHandoffBytes <= 0) {
-    return reason("invalid-transfer-evidence", "handoff byte evidence is invalid");
+    return reason2("invalid-transfer-evidence", "handoff byte evidence is invalid");
   }
   if (transfer.handoffBytes > transfer.maxHandoffBytes) {
-    return reason("handoff-over-budget", `compact handoff is ${transfer.handoffBytes} bytes, above the ${transfer.maxHandoffBytes}-byte transfer budget`);
+    return reason2("handoff-over-budget", `compact handoff is ${transfer.handoffBytes} bytes, above the ${transfer.maxHandoffBytes}-byte transfer budget`);
   }
   return null;
 }
 function validateQuality(evidence4, taskClass) {
   if (!Number.isInteger(evidence4.qualitySamples) || evidence4.qualitySamples < 0) {
-    return reason("invalid-quality-evidence", "quality sample count is invalid");
+    return reason2("invalid-quality-evidence", "quality sample count is invalid");
   }
   if (evidence4.quality === "unknown")
     return null;
   if (evidence4.qualitySamples < 1 || evidence4.qualityTaskClass === null) {
-    return reason("candidate-quality-unattributed", "candidate quality evidence is not attributable to a measured task class");
+    return reason2("candidate-quality-unattributed", "candidate quality evidence is not attributable to a measured task class");
   }
   if (evidence4.qualityTaskClass !== taskClass) {
-    return reason("candidate-quality-task-mismatch", `candidate quality evidence covers ${evidence4.qualityTaskClass}, not ${taskClass}`);
+    return reason2("candidate-quality-task-mismatch", `candidate quality evidence covers ${evidence4.qualityTaskClass}, not ${taskClass}`);
   }
   return null;
 }
@@ -1746,7 +2004,7 @@ function validateCapacity(evidence4, subject) {
   if (value3 === void 0 || value3 === null)
     return null;
   if (!Number.isInteger(value3) || value3 < 0) {
-    return reason("invalid-capacity-evidence", `${subject} accepted-task capacity must be a non-negative whole number when present`);
+    return reason2("invalid-capacity-evidence", `${subject} accepted-task capacity must be a non-negative whole number when present`);
   }
   return null;
 }
@@ -1762,7 +2020,7 @@ function scheduleCrossHarness(input) {
     return {
       ...base,
       decision: "stay",
-      reasons: [reason("same-harness", "the candidate is the current harness")]
+      reasons: [reason2("same-harness", "the candidate is the current harness")]
     };
   }
   const transferProblem = validateTransfer(input.transfer);
@@ -1777,7 +2035,7 @@ function scheduleCrossHarness(input) {
     return {
       ...base,
       decision: "stay",
-      reasons: [reason("candidate-unavailable", "the candidate harness is not currently usable")]
+      reasons: [reason2("candidate-unavailable", "the candidate harness is not currently usable")]
     };
   }
   if (tasksRemaining !== null && (!Number.isSafeInteger(tasksRemaining) || tasksRemaining <= 0)) {
@@ -1785,7 +2043,7 @@ function scheduleCrossHarness(input) {
       ...base,
       decision: "insufficient-evidence",
       reasons: [
-        reason("invalid-workload-target", "remaining workload must be a positive whole number of accepted tasks")
+        reason2("invalid-workload-target", "remaining workload must be a positive whole number of accepted tasks")
       ]
     };
   }
@@ -1811,7 +2069,7 @@ function scheduleCrossHarness(input) {
       ...base,
       decision: "stay",
       reasons: [
-        reason("candidate-quality-failed", "quality-gated evidence rejects the candidate for this task class")
+        reason2("candidate-quality-failed", "quality-gated evidence rejects the candidate for this task class")
       ]
     };
   }
@@ -1821,7 +2079,7 @@ function scheduleCrossHarness(input) {
         ...base,
         decision: "insufficient-evidence",
         reasons: [
-          reason("current-workload-capacity-unknown", "current harness capacity for the stated remaining workload is unknown")
+          reason2("current-workload-capacity-unknown", "current harness capacity for the stated remaining workload is unknown")
         ]
       };
     }
@@ -1830,14 +2088,14 @@ function scheduleCrossHarness(input) {
         ...base,
         decision: "insufficient-evidence",
         reasons: [
-          reason("current-quota-unknown", "current harness allowance pressure is not known well enough to justify a switch")
+          reason2("current-quota-unknown", "current harness allowance pressure is not known well enough to justify a switch")
         ]
       };
     }
     return {
       ...base,
       decision: "stay",
-      reasons: [reason("current-headroom-healthy", "the current harness is not over pace")]
+      reasons: [reason2("current-headroom-healthy", "the current harness is not over pace")]
     };
   }
   if (!hasSafeHeadroom(input.candidate, tasksRemaining)) {
@@ -1846,7 +2104,7 @@ function scheduleCrossHarness(input) {
         ...base,
         decision: "insufficient-evidence",
         reasons: [
-          reason("candidate-workload-capacity-unknown", "candidate capacity for the stated remaining workload is unknown")
+          reason2("candidate-workload-capacity-unknown", "candidate capacity for the stated remaining workload is unknown")
         ]
       };
     }
@@ -1855,7 +2113,7 @@ function scheduleCrossHarness(input) {
         ...base,
         decision: "stay",
         reasons: [
-          reason("candidate-capacity-below-workload", `candidate has ${String(input.candidate.acceptedTasksRemaining)} accepted-task equivalents for ${String(tasksRemaining)} stated task(s)`)
+          reason2("candidate-capacity-below-workload", `candidate has ${String(input.candidate.acceptedTasksRemaining)} accepted-task equivalents for ${String(tasksRemaining)} stated task(s)`)
         ]
       };
     }
@@ -1864,7 +2122,7 @@ function scheduleCrossHarness(input) {
         ...base,
         decision: "stay",
         reasons: [
-          reason("candidate-capacity-below-one", "candidate safe allowance is below one empirical accepted-task equivalent")
+          reason2("candidate-capacity-below-one", "candidate safe allowance is below one empirical accepted-task equivalent")
         ]
       };
     }
@@ -1873,7 +2131,7 @@ function scheduleCrossHarness(input) {
         ...base,
         decision: "insufficient-evidence",
         reasons: [
-          reason("candidate-quota-unknown", "candidate allowance headroom is not known well enough to justify a switch")
+          reason2("candidate-quota-unknown", "candidate allowance headroom is not known well enough to justify a switch")
         ]
       };
     }
@@ -1881,7 +2139,7 @@ function scheduleCrossHarness(input) {
       ...base,
       decision: "stay",
       reasons: [
-        reason("candidate-over-pace", "the candidate is already over pace in an observed allowance window")
+        reason2("candidate-over-pace", "the candidate is already over pace in an observed allowance window")
       ]
     };
   }
@@ -1890,7 +2148,7 @@ function scheduleCrossHarness(input) {
       ...base,
       decision: "insufficient-evidence",
       reasons: [
-        reason("candidate-quality-unknown", "no quality-gated empirical result proves the candidate for this task class")
+        reason2("candidate-quality-unknown", "no quality-gated empirical result proves the candidate for this task class")
       ]
     };
   }
@@ -1899,7 +2157,7 @@ function scheduleCrossHarness(input) {
       ...base,
       decision: "stay",
       reasons: [
-        reason("transfer-cost-not-worth-it", "comparable evidence says the expected switch benefit does not exceed handoff cost")
+        reason2("transfer-cost-not-worth-it", "comparable evidence says the expected switch benefit does not exceed handoff cost")
       ]
     };
   }
@@ -1908,18 +2166,18 @@ function scheduleCrossHarness(input) {
       ...base,
       decision: "insufficient-evidence",
       reasons: [
-        reason("transfer-benefit-unknown", "no comparable evidence proves that the expected switch benefit exceeds handoff cost")
+        reason2("transfer-benefit-unknown", "no comparable evidence proves that the expected switch benefit exceeds handoff cost")
       ]
     };
   }
   const reasons = [
-    tasksRemaining !== null && input.current.acceptedTasksRemaining !== void 0 && input.current.acceptedTasksRemaining !== null && input.current.acceptedTasksRemaining < tasksRemaining ? reason("current-capacity-below-workload", `current harness has ${String(input.current.acceptedTasksRemaining)} accepted-task equivalents for ${String(tasksRemaining)} stated task(s)`) : input.current.acceptedTasksRemaining === 0 ? reason("current-capacity-below-one", "current safe allowance is below one empirical accepted-task equivalent") : reason("current-over-pace", "the current harness is over pace in at least one observed allowance window"),
-    reason("candidate-headroom", "the candidate is on pace or under pace in its observed allowance windows")
+    tasksRemaining !== null && input.current.acceptedTasksRemaining !== void 0 && input.current.acceptedTasksRemaining !== null && input.current.acceptedTasksRemaining < tasksRemaining ? reason2("current-capacity-below-workload", `current harness has ${String(input.current.acceptedTasksRemaining)} accepted-task equivalents for ${String(tasksRemaining)} stated task(s)`) : input.current.acceptedTasksRemaining === 0 ? reason2("current-capacity-below-one", "current safe allowance is below one empirical accepted-task equivalent") : reason2("current-over-pace", "the current harness is over pace in at least one observed allowance window"),
+    reason2("candidate-headroom", "the candidate is on pace or under pace in its observed allowance windows")
   ];
   if (input.candidate.acceptedTasksRemaining !== void 0 && input.candidate.acceptedTasksRemaining !== null) {
-    reasons.push(tasksRemaining !== null ? reason("candidate-workload-covered", `candidate has ${String(input.candidate.acceptedTasksRemaining)} accepted-task equivalents for ${String(tasksRemaining)} stated task(s)`) : reason("candidate-capacity-sufficient", `candidate has ${String(input.candidate.acceptedTasksRemaining)} conservative accepted-task equivalents remaining`));
+    reasons.push(tasksRemaining !== null ? reason2("candidate-workload-covered", `candidate has ${String(input.candidate.acceptedTasksRemaining)} accepted-task equivalents for ${String(tasksRemaining)} stated task(s)`) : reason2("candidate-capacity-sufficient", `candidate has ${String(input.candidate.acceptedTasksRemaining)} conservative accepted-task equivalents remaining`));
   }
-  reasons.push(reason("candidate-quality-passed", "quality-gated empirical evidence passes for this task class"), reason("transfer-benefit-positive", "comparable evidence says expected switch benefit exceeds handoff cost"));
+  reasons.push(reason2("candidate-quality-passed", "quality-gated empirical evidence passes for this task class"), reason2("transfer-benefit-positive", "comparable evidence says expected switch benefit exceeds handoff cost"));
   return {
     ...base,
     decision: "switch",
@@ -2164,7 +2422,7 @@ function parseCrossHarnessTransferReceipt(value3) {
   const basis = row2["basis"];
   const reasons = row2["reasons"];
   const recordedAt = row2["recordedAt"];
-  if (typeof benchmarkId !== "string" || !isTaskBenchmarkId(benchmarkId) || typeof projectId !== "string" || projectId === "" || typeof taskClass !== "string" || !isTaskClass(taskClass) || typeof currentHarness !== "string" || !isHarnessId(currentHarness) || typeof candidateHarness !== "string" || !isHarnessId(candidateHarness) || currentHarness === candidateHarness || typeof handoffBytes !== "number" || !Number.isInteger(handoffBytes) || handoffBytes < 0 || typeof handoffDigest !== "string" || !isDigest(handoffDigest) || typeof maxHandoffBytes !== "number" || !Number.isInteger(maxHandoffBytes) || maxHandoffBytes <= 0 || typeof benefit !== "string" || !BENEFITS.has(benefit) || typeof basis !== "string" || !BASES.has(basis) || !Array.isArray(reasons) || reasons.length < 1 || !reasons.every((reason3) => typeof reason3 === "string" && reason3.length > 0) || !validInstant2(recordedAt)) {
+  if (typeof benchmarkId !== "string" || !isTaskBenchmarkId(benchmarkId) || typeof projectId !== "string" || projectId === "" || typeof taskClass !== "string" || !isTaskClass(taskClass) || typeof currentHarness !== "string" || !isHarnessId(currentHarness) || typeof candidateHarness !== "string" || !isHarnessId(candidateHarness) || currentHarness === candidateHarness || typeof handoffBytes !== "number" || !Number.isInteger(handoffBytes) || handoffBytes < 0 || typeof handoffDigest !== "string" || !isDigest(handoffDigest) || typeof maxHandoffBytes !== "number" || !Number.isInteger(maxHandoffBytes) || maxHandoffBytes <= 0 || typeof benefit !== "string" || !BENEFITS.has(benefit) || typeof basis !== "string" || !BASES.has(basis) || !Array.isArray(reasons) || reasons.length < 1 || !reasons.every((reason4) => typeof reason4 === "string" && reason4.length > 0) || !validInstant2(recordedAt)) {
     return {
       ok: false,
       reason: "invalid-shape",
@@ -2270,6 +2528,9 @@ function estimateScope(input) {
   });
   return {
     scope: input.scope,
+    receiptIds: [
+      ...new Set(input.receipts.filter((receipt) => quotaCosts([receipt], input.scope).length === 1).map((receipt) => `${receipt.benchmarkId}/${receipt.variant}`))
+    ].sort(),
     sampleCount: costs.length,
     p75UsedPercentPerAcceptedTask: cost,
     spendableRemainingPercent: spendable,
@@ -2458,7 +2719,7 @@ var init_workload_coverage = __esm({
 });
 
 // packages/core/dist/src/domain/mixed-workload.js
-function reason2(code, summary) {
+function reason3(code, summary) {
   return { code, summary };
 }
 function validDemand(demand) {
@@ -2579,7 +2840,7 @@ function allocateMixedWorkload(input) {
       currentUsage: usageReport(input.current.harnessId, input.current.capacities, zero),
       candidateUsage: usageReport(input.candidate.harnessId, input.candidate.capacities, zero),
       reasons: [
-        reason2("mixed-workload-invalid", "mixed workload must contain unique task classes with positive whole-number counts")
+        reason3("mixed-workload-invalid", "mixed workload must contain unique task classes with positive whole-number counts")
       ]
     };
   }
@@ -2591,7 +2852,7 @@ function allocateMixedWorkload(input) {
       currentUsage: usageReport(input.current.harnessId, input.current.capacities, zero),
       candidateUsage: usageReport(input.candidate.harnessId, input.candidate.capacities, zero),
       reasons: [
-        reason2("mixed-workload-same-harness", "mixed workload allocation requires two distinct harnesses")
+        reason3("mixed-workload-same-harness", "mixed workload allocation requires two distinct harnesses")
       ]
     };
   }
@@ -2654,20 +2915,20 @@ function allocateMixedWorkload(input) {
     const unknownClasses = allocationRows.filter((row2) => row2.unallocated > 0 && evidenceUnknown.has(row2.taskClass)).map((row2) => row2.taskClass);
     if (unknownClasses.length > 0) {
       decision = "insufficient-evidence";
-      reasons.push(reason2("mixed-workload-capacity-unproven", `Could not allocate ${String(unallocated)} task(s); evidence is incomplete for ${unknownClasses.join(", ")}`));
+      reasons.push(reason3("mixed-workload-capacity-unproven", `Could not allocate ${String(unallocated)} task(s); evidence is incomplete for ${unknownClasses.join(", ")}`));
     } else {
       decision = "shortfall";
-      reasons.push(reason2("mixed-workload-capacity-shortfall", `Conservative five-hour/weekly capacity leaves ${String(unallocated)} of ${String(requestedTasks)} requested task(s) unallocated`));
+      reasons.push(reason3("mixed-workload-capacity-shortfall", `Conservative five-hour/weekly capacity leaves ${String(unallocated)} of ${String(requestedTasks)} requested task(s) unallocated`));
     }
   } else if (candidateTasks === 0) {
     decision = "stay";
-    reasons.push(reason2("mixed-workload-current-covers", "The current harness can cover the full evidenced workload"));
+    reasons.push(reason3("mixed-workload-current-covers", "The current harness can cover the full evidenced workload"));
   } else if (currentTasks === 0) {
     decision = "switch";
-    reasons.push(reason2("mixed-workload-candidate-covers", "The candidate harness can cover the full evidenced workload with quality-gated capacity"));
+    reasons.push(reason3("mixed-workload-candidate-covers", "The candidate harness can cover the full evidenced workload with quality-gated capacity"));
   } else {
     decision = "split";
-    reasons.push(reason2("mixed-workload-split", `A conservative split covers all ${String(requestedTasks)} task(s): ${String(currentTasks)} current and ${String(candidateTasks)} candidate`));
+    reasons.push(reason3("mixed-workload-split", `A conservative split covers all ${String(requestedTasks)} task(s): ${String(currentTasks)} current and ${String(candidateTasks)} candidate`));
   }
   return {
     ...base,
@@ -3200,6 +3461,8 @@ function truncateUtf8(value3, maxBytes) {
     else
       high = middle - 1;
   }
+  if (low > 0 && /[\uD800-\uDBFF]/.test(value3[low - 1]) && /[\uDC00-\uDFFF]/.test(value3[low] ?? ""))
+    low--;
   return `${value3.slice(0, low).trimEnd()}${suffix}`;
 }
 function renderList(title2, values, omitted) {
@@ -3212,16 +3475,21 @@ function renderList(title2, values, omitted) {
     lines.push(`- \u2026 ${omitted} more omitted`);
   return lines;
 }
-function render(objective, nextAction2, lists, omitted) {
+function render(objective, nextAction2, lists, omitted, compactOmissions = false) {
+  const section = (title2, key) => renderList(title2, lists[key], compactOmissions ? 0 : omitted[key]);
+  const omittedTotal = Object.values(omitted).reduce((sum, count) => sum + count, 0);
   const sections = [
     ["# Compact handoff", "", "## Objective", objective],
-    renderList("Decisions", lists.decisions, omitted.decisions),
-    renderList("Changed files", lists.changedFiles, omitted.changedFiles),
-    renderList("Validation", lists.validation, omitted.validation),
-    renderList("Unresolved", lists.unresolved, omitted.unresolved),
+    section("Acceptance criteria", "acceptanceCriteria"),
+    section("Costly facts", "costlyFacts"),
+    section("Decisions", "decisions"),
+    section("Changed files", "changedFiles"),
+    section("Validation", "validation"),
+    section("Unresolved", "unresolved"),
+    compactOmissions && omittedTotal > 0 ? [`\u2026 ${omittedTotal} optional items omitted`] : [],
     ["## Next action", nextAction2]
-  ].filter((section) => section.length > 0);
-  return sections.map((section) => section.join("\n")).join("\n\n");
+  ].filter((section2) => section2.length > 0);
+  return sections.map((section2) => section2.join("\n")).join("\n\n");
 }
 function largestOptionalList(lists) {
   const entries = Object.keys(lists).filter((key) => lists[key].length > 0).map((key) => ({ key, bytes: lists[key].reduce((sum, item) => sum + byteLength(item), 0) })).sort((left, right) => right.bytes - left.bytes || left.key.localeCompare(right.key));
@@ -3238,12 +3506,16 @@ function buildCompactHandoff(input) {
   if (!nextAction2)
     throw new Error("nextAction must not be empty");
   const lists = {
+    acceptanceCriteria: uniqueClean(input.acceptanceCriteria),
+    costlyFacts: uniqueClean(input.costlyFacts),
     decisions: uniqueClean(input.decisions),
     changedFiles: uniqueClean(input.changedFiles),
     validation: uniqueClean(input.validation),
     unresolved: uniqueClean(input.unresolved)
   };
   const omitted = {
+    acceptanceCriteria: 0,
+    costlyFacts: 0,
     decisions: 0,
     changedFiles: 0,
     validation: 0,
@@ -3260,15 +3532,18 @@ function buildCompactHandoff(input) {
     truncated = true;
     markdown = render(objective, nextAction2, lists, omitted);
   }
+  const compactOmissions = byteLength(render("", "", lists, omitted)) + 32 > input.maxBytes;
+  if (compactOmissions)
+    markdown = render(objective, nextAction2, lists, omitted, true);
   if (byteLength(markdown) > input.maxBytes) {
-    const skeleton = render("", "", lists, omitted);
+    const skeleton = render("", "", lists, omitted, compactOmissions);
     const available = Math.max(32, input.maxBytes - byteLength(skeleton));
     const objectiveBudget = Math.floor(available * 0.6);
     const nextBudget = available - objectiveBudget;
     objective = truncateUtf8(objective, objectiveBudget);
     nextAction2 = truncateUtf8(nextAction2, nextBudget);
     truncated = true;
-    markdown = render(objective, nextAction2, lists, omitted);
+    markdown = render(objective, nextAction2, lists, omitted, compactOmissions);
   }
   if (byteLength(markdown) > input.maxBytes) {
     markdown = truncateUtf8(markdown, input.maxBytes);
@@ -5774,14 +6049,14 @@ function providerList(events) {
   }
   return providers;
 }
-function incomparable(events, reason3) {
+function incomparable(events, reason4) {
   const pipelineIds = new Set(events.map((event) => event.context.pipelineId));
   const operationIds = new Set(events.map((event) => event.context.operationId));
   return {
     status: "incomparable",
     pipelineId: pipelineIds.size === 1 ? events[0]?.context.pipelineId ?? null : null,
     operationId: operationIds.size === 1 ? events[0]?.context.operationId ?? null : null,
-    reason: reason3,
+    reason: reason4,
     providers: providerList(events),
     stages: events.length
   };
@@ -9862,7 +10137,7 @@ var TOOL_VERSION;
 var init_version2 = __esm({
   "apps/cli/dist/src/version.js"() {
     "use strict";
-    TOOL_VERSION = "0.1.27";
+    TOOL_VERSION = "0.1.28";
   }
 });
 
@@ -9885,6 +10160,8 @@ function parseValue(argv2, index) {
 }
 function parseArgs(argv2) {
   const args = {
+    acceptanceCriteria: [],
+    costlyFacts: [],
     objective: null,
     decisions: [],
     changedFiles: [],
@@ -9923,6 +10200,8 @@ function parseArgs(argv2) {
       continue;
     }
     const valueFlags = /* @__PURE__ */ new Set([
+      "--acceptance",
+      "--fact",
       "--objective",
       "--decision",
       "--changed-file",
@@ -9952,6 +10231,12 @@ function parseArgs(argv2) {
     }
     index += parsed.consumed;
     switch (name2) {
+      case "--acceptance":
+        args.acceptanceCriteria.push(parsed.value);
+        break;
+      case "--fact":
+        args.costlyFacts.push(parsed.value);
+        break;
       case "--objective":
         args.objective = parsed.value;
         break;
@@ -10067,6 +10352,8 @@ async function handoffMain(argv2, streams) {
     return EXIT_CODES["usage-error"];
   }
   const handoff = buildCompactHandoff({
+    acceptanceCriteria: parsed.args.acceptanceCriteria,
+    costlyFacts: parsed.args.costlyFacts,
     objective: parsed.args.objective,
     decisions: parsed.args.decisions,
     changedFiles: parsed.args.changedFiles,
@@ -10097,6 +10384,8 @@ Usage
   token-harness handoff --objective <text> --next-action <text> [flags]
 
 Flags
+  --acceptance <text>     Repeatable acceptance criterion to preserve
+  --fact <text>           Repeatable costly path/symbol/config fact to preserve
   --decision <text>       Repeatable decision to preserve
   --changed-file <path>   Repeatable changed file to preserve
   --validation <text>     Repeatable validation result to preserve
@@ -10190,7 +10479,7 @@ function render2(report) {
     `Basis: ${a.basis}`,
     `Handoff: ${String(a.handoffBytes)} / ${String(a.maxHandoffBytes)} bytes`,
     "Reasons:",
-    ...a.reasons.map((reason3) => `- ${reason3}`),
+    ...a.reasons.map((reason4) => `- ${reason4}`),
     ""
   ].join("\n");
 }
@@ -11993,7 +12282,7 @@ function boundedCapture(limit) {
   };
   return capture;
 }
-function failureOutcome(base, reason3, message, durationMs) {
+function failureOutcome(base, reason4, message, durationMs) {
   return {
     ...base,
     exitCode: null,
@@ -12003,8 +12292,8 @@ function failureOutcome(base, reason3, message, durationMs) {
     stdoutTruncated: false,
     stderrTruncated: false,
     durationMs,
-    timedOut: reason3 === "timed-out",
-    failure: { reason: reason3, message }
+    timedOut: reason4 === "timed-out",
+    failure: { reason: reason4, message }
   };
 }
 function spawnFailureReason(code) {
@@ -13938,10 +14227,10 @@ async function readClaudeNativeEffort(context) {
     files: [],
     environment
   };
-  const block = (code, reason3) => {
+  const block = (code, reason4) => {
     if (observation.writeBlock === null) {
       observation.writeBlock = code;
-      observation.reason = reason3;
+      observation.reason = reason4;
     }
   };
   if (version3 === void 0) {
@@ -15502,7 +15791,7 @@ async function observeUsageViaCclimits(context, observedAt, nativeDiagnostic) {
     maxOutputBytes: 512 * 1024
   });
   if (outcome2.failure !== null || outcome2.exitCode !== 0 || outcome2.stdoutTruncated) {
-    const reason3 = outcome2.failure !== null ? outcome2.failure.message : outcome2.stdoutTruncated ? "output exceeded the bounded capture" : `exited ${String(outcome2.exitCode)}`;
+    const reason4 = outcome2.failure !== null ? outcome2.failure.message : outcome2.stdoutTruncated ? "output exceeded the bounded capture" : `exited ${String(outcome2.exitCode)}`;
     return {
       harnessId: CODEX2,
       state: "unavailable",
@@ -15516,7 +15805,7 @@ async function observeUsageViaCclimits(context, observedAt, nativeDiagnostic) {
           severity: outcome2.failure?.reason === "executable-not-found" ? "info" : "warning",
           code: "cclimits-codex-usage-unavailable",
           subject: CODEX2,
-          message: "Optional cclimits Codex quota fallback was unavailable: " + reason3,
+          message: "Optional cclimits Codex quota fallback was unavailable: " + reason4,
           remediation: "Install a cclimits build with cacheless Codex JSON support, or treat Codex quota as unknown"
         })
       ]
@@ -16792,7 +17081,7 @@ function nativePromptRoutingVersionSupported(harness, version3) {
   const parsed = version3 === null ? null : parseSemanticVersion(version3);
   if (parsed === null || parsed.prerelease !== null)
     return false;
-  return harness === "codex" ? parsed.major === 0 && (parsed.minor === 159 && parsed.patch <= 1 || parsed.minor === 160 && parsed.patch === 0) : harness === "claude" && parsed.major === 2 && parsed.minor === 1 && parsed.patch >= 274 && parsed.patch <= 288;
+  return harness === "codex" ? parsed.major === 0 && (parsed.minor === 146 && parsed.patch === 0 || parsed.minor === 159 && parsed.patch <= 1 || parsed.minor === 160 && parsed.patch === 0) : harness === "claude" && parsed.major === 2 && parsed.minor === 1 && parsed.patch >= 274 && parsed.patch <= 288;
 }
 function nativePromptRoutingHookEntries(harness, executable = "token-harness", platform = "linux") {
   return NATIVE_PROMPT_ROUTING_EVENTS.map(({ eventName, commandEvent }) => {
@@ -17460,6 +17749,30 @@ async function verify6(context) {
   const configured = await configuredHarnessesForHarnessTrim(context, currentCapabilities?.capabilities ?? null);
   const runtimeConfigured = harnessesWiredToHarnessTrim(context.harnessConfigs);
   const skillsOnly = configured.filter((harness) => !runtimeConfigured.includes(harness));
+  if (context.facts.os === "windows" && !context.facts.isWsl) {
+    for (const config of context.harnessConfigs) {
+      for (const hook of config.hookCommands ?? []) {
+        const binary = windowsHookExecutable(hook.command);
+        if (binary === null || (await context.fs.stat(binary))?.kind === "file")
+          continue;
+        checks.push({
+          id: `hook-executable-${config.harnessId}-${digestText(hook.commandPointer).slice(7, 15)}`,
+          status: "fail",
+          summary: `${config.harnessId} HarnessTrim hook executable is missing or not a file`,
+          achievedTier: null,
+          evidence: [
+            evidence3({
+              kind: "config-entry",
+              source: "HarnessTrim hook",
+              path: config.configPath,
+              detail: `${hook.commandPointer}: ${binary}`
+            })
+          ],
+          remediation: "Preview a HarnessTrim setup repair; custom commands require manual review."
+        });
+      }
+    }
+  }
   checks.push({
     id: "integration-configured",
     status: runtimeConfigured.length > 0 ? "pass" : skillsOnly.length > 0 ? "info" : "not-exercised",
@@ -17881,6 +18194,42 @@ async function plan(context, request) {
     const command = `harnesstrim hook ${harness.id} --metrics ${metricsPath}`;
     const existing = context.harnessConfigs.filter((config) => config.harnessId === harness.id && config.configPath === target.configPath && config.interceptionPoints.includes(target.scopeId)).flatMap((config) => config.hookCommands ?? []).filter((entry) => entry.eventName === target.eventName && entry.matcher !== null && matcherCoversFamily2(entry.matcher, target.toolFamily) && isHarnessTrimHookFor(entry.command, harness.id));
     const correctlyMonitored = existing.some((entry) => commandHasMetricsPath(entry.command, metricsPath));
+    const missingExecutables = [];
+    if (context.facts.os === "windows" && !context.facts.isWsl) {
+      for (const entry of existing) {
+        const binary = windowsHookExecutable(entry.command);
+        if (binary !== null && (await context.fs.stat(binary))?.kind !== "file")
+          missingExecutables.push(entry);
+      }
+    }
+    if (existing.length === 1 && missingExecutables.length === 1) {
+      const entry = missingExecutables[0];
+      const binary = windowsHookExecutable(entry.command);
+      const standardTail = entry.command.trim().slice(entry.command.indexOf(" hook ") + 1);
+      if (binary !== null && (standardTail === `hook ${harness.id}` || standardTail === `hook ${harness.id} --metrics ${metricsPath}`)) {
+        actions.push(replaceHookCommandAction({
+          target,
+          commandPointer: entry.commandPointer,
+          currentCommand: entry.command,
+          nextCommand: command,
+          actionId: `harnesstrim-${harness.id}-executable-${digestText(target.configPath).slice(7, 15)}`,
+          explanation: `Repair the missing HarnessTrim hook executable on ${harness.displayName}`
+        }));
+        plannedHarnesses.push(harness.id);
+        continue;
+      }
+    }
+    if (missingExecutables.length > 0) {
+      diagnostics.push(diagnostic({
+        severity: "warning",
+        code: "harnesstrim-hook-executable-needs-review",
+        subject: harness.id,
+        path: target.configPath,
+        message: "An absolute HarnessTrim hook executable is missing; its custom or ambiguous command was left unchanged",
+        remediation: "Review the executable and arguments before replacing this hook."
+      }));
+      continue;
+    }
     if (correctlyMonitored) {
       plannedHarnesses.push(harness.id);
       continue;
@@ -17927,6 +18276,11 @@ async function plan(context, request) {
     targetHarnesses: [...new Set(plannedHarnesses)]
   };
 }
+function windowsHookExecutable(command) {
+  const match = /^(?:"([a-z]:[\\/][^"\r\n]+)"|([a-z]:[\\/][^\s"\r\n]+))\s+hook\s+(?:claude|codex)(?:\s|$)/i.exec(command.trim());
+  const binary = match?.[1] ?? match?.[2];
+  return binary !== void 0 && /[\\/]harnesstrim(?:\.cmd|\.exe)?$/i.test(binary) ? binary : null;
+}
 function isHarnessTrimHookFor(command, harness) {
   const match = HARNESSTRIM_HOOK_COMMAND.exec(command.trim());
   return match?.[1]?.toLowerCase() === harness;
@@ -17964,7 +18318,7 @@ function replaceHookCommandAction(input) {
       `${input.commandPointer} records HarnessTrim reductions to .harnesstrim/metrics.jsonl`
     ],
     rollbackData: "file-snapshot",
-    explanation: `Enable per-harness HarnessTrim telemetry for ${input.target.harness.displayName}${codexActivationNote(input.target.harnessId)}`,
+    explanation: `${input.explanation ?? `Enable per-harness HarnessTrim telemetry for ${input.target.harness.displayName}`}${codexActivationNote(input.target.harnessId)}`,
     path: input.target.configPath,
     ownedPointers: [input.commandPointer],
     operations: [
@@ -20185,7 +20539,7 @@ ${wrapOutcome.stderr}`) : { claude: false, codex: false };
     };
   }
   if (version3 !== HEADROOM_REVIEWED_BENCHMARK_VERSION) {
-    const reason3 = headroomVersionAtLeast(version3, HEADROOM_REVIEWED_BENCHMARK_VERSION) ? `Headroom ${version3} is newer than the reviewed ${HEADROOM_REVIEWED_BENCHMARK_VERSION} benchmark build; review it before benchmarking` : `Headroom ${version3} predates the reviewed ${HEADROOM_REVIEWED_BENCHMARK_VERSION} benchmark build`;
+    const reason4 = headroomVersionAtLeast(version3, HEADROOM_REVIEWED_BENCHMARK_VERSION) ? `Headroom ${version3} is newer than the reviewed ${HEADROOM_REVIEWED_BENCHMARK_VERSION} benchmark build; review it before benchmarking` : `Headroom ${version3} predates the reviewed ${HEADROOM_REVIEWED_BENCHMARK_VERSION} benchmark build`;
     return {
       state: "unsupported-version",
       version: version3,
@@ -20193,7 +20547,7 @@ ${wrapOutcome.stderr}`) : { claude: false, codex: false };
       supportsClaudeWrap: targets.claude,
       supportsCodexWrap: targets.codex,
       minimumBenchmarkVersion: HEADROOM_MINIMUM_BENCHMARK_VERSION,
-      reasons: [reason3]
+      reasons: [reason4]
     };
   }
   if (!targets.claude || !targets.codex) {
@@ -24960,7 +25314,7 @@ function providerContext3(context) {
 function headroomDiagnostics(observation) {
   const version3 = observation.version === null ? "" : ` ${observation.version}`;
   const baseline = observation.minimumBenchmarkVersion;
-  const reason3 = observation.reasons[0] ?? "Keep the candidate disabled until it is proven safe";
+  const reason4 = observation.reasons[0] ?? "Keep the candidate disabled until it is proven safe";
   if (observation.state === "absent") {
     return [
       diagnostic({
@@ -24990,7 +25344,7 @@ function headroomDiagnostics(observation) {
         code: "context-owner-candidate-installed",
         subject: "headroom",
         message: `Headroom${version3} is installed but is not benchmark-ready`,
-        remediation: reason3
+        remediation: reason4
       })
     ];
   }
@@ -25007,7 +25361,7 @@ function headroomDiagnostics(observation) {
 function mcptoonDiagnostics(observation) {
   const version3 = observation.version === null ? "" : ` ${observation.version}`;
   const baseline = observation.minimumBenchmarkVersion;
-  const reason3 = observation.reasons[0] ?? "Keep mcptoon disabled until benchmark evidence is available";
+  const reason4 = observation.reasons[0] ?? "Keep mcptoon disabled until benchmark evidence is available";
   if (observation.state === "absent") {
     return [
       diagnostic({
@@ -25037,7 +25391,7 @@ function mcptoonDiagnostics(observation) {
         code: "context-optimizer-mcptoon-installed",
         subject: "mcptoon",
         message: `mcptoon${version3} is installed but is not benchmark-ready`,
-        remediation: reason3
+        remediation: reason4
       })
     ];
   }
@@ -25053,7 +25407,7 @@ function mcptoonDiagnostics(observation) {
 }
 function gitNexusDiagnostics(observation) {
   const version3 = observation.version === null ? "" : ` ${observation.version}`;
-  const reason3 = observation.reasons[0] ?? "Keep GitNexus disabled until paired repository-exploration evidence is available";
+  const reason4 = observation.reasons[0] ?? "Keep GitNexus disabled until paired repository-exploration evidence is available";
   if (observation.state === "absent") {
     return [
       diagnostic({
@@ -25083,7 +25437,7 @@ function gitNexusDiagnostics(observation) {
         code: "context-optimizer-gitnexus-installed",
         subject: "gitnexus",
         message: `GitNexus${version3} is installed but is not benchmark-ready`,
-        remediation: reason3
+        remediation: reason4
       })
     ];
   }
@@ -25405,7 +25759,7 @@ async function runContext(context) {
     const usesMostOfCodexBudget = harness.projectDocMaxBytes !== null && harness.projectDocMaxBytes > 0 && knownLoadedProjectBytes / harness.projectDocMaxBytes >= 0.75;
     const largeSingleCandidate = projectFiles.length === 1 && largestProjectFileBytes !== null && largestProjectFileBytes >= 32 * 1024;
     const monolithicProjectInstructions = projectFiles.length === 1 && (usesMostOfCodexBudget || largeSingleCandidate);
-    const reason3 = monolithicProjectInstructions ? usesMostOfCodexBudget ? "one project instruction file consumes at least 75% of the harness project-doc byte budget" : "one project instruction candidate is at least 32 KiB" : null;
+    const reason4 = monolithicProjectInstructions ? usesMostOfCodexBudget ? "one project instruction file consumes at least 75% of the harness project-doc byte budget" : "one project instruction candidate is at least 32 KiB" : null;
     report.instructionHierarchy.push({
       harnessId: harness.harnessId,
       projectFileCount: projectFiles.length,
@@ -25414,7 +25768,7 @@ async function runContext(context) {
       nestedProjectHierarchy: projectDirectories.size > 1,
       largestProjectFileBytes,
       monolithicProjectInstructions,
-      reason: reason3
+      reason: reason4
     });
     if (monolithicProjectInstructions) {
       hierarchyDiagnostics.push(diagnostic({
@@ -26457,7 +26811,8 @@ async function runOptimize(context) {
     profile,
     reservePercent,
     tasksRemaining: context.tasksRemaining ?? null,
-    harnesses: []
+    harnesses: [],
+    efficiencyDecisions: []
   };
   if (contextReport === null || budgetReport === null) {
     return commandResult({
@@ -26502,6 +26857,35 @@ async function runOptimize(context) {
       ...contextGovernor === void 0 ? {} : { contextGovernor }
     }));
   }
+  for (const advice of report.harnesses) {
+    if (advice.harnessId !== "claude" && advice.harnessId !== "codex")
+      continue;
+    const snapshotObservation = contextReport.harnesses.find((item) => item.harnessId === contextSnapshot?.harnessId);
+    const input = {
+      currentHarness: advice.harnessId === "claude" ? "claude" : "codex",
+      taskClass,
+      optimization: report.harnesses,
+      scheduler: context.efficiencyScheduler ?? null,
+      contextGovernor: contextSnapshot === null || snapshotObservation === void 0 ? null : {
+        ...contextSnapshot,
+        pressure: contextEvidence(contextReport, snapshotObservation).pressure
+      }
+    };
+    const selected = decideEfficiency(input);
+    const capacity = outcomeHistory.receipts === null ? null : estimateAcceptedTaskCapacityForPolicy({
+      report: budgetReport,
+      receipts: outcomeHistory.receipts,
+      harnessId: harnessId(selected.harness),
+      taskClass,
+      reservePercent,
+      policy: {
+        model: selected.model,
+        reasoningEffort: selected.reasoningEffort,
+        verbosity: selected.verbosity
+      }
+    });
+    report.efficiencyDecisions.push(decideEfficiency({ ...input, capacities: capacity === null ? [] : [capacity] }));
+  }
   return commandResult({
     command: "optimize",
     exitCode: EXIT_CODES.ok,
@@ -32533,8 +32917,8 @@ function renderBenchmarkReport(report, _context) {
   if (comparison.reasons.length > 0) {
     lines.push("");
     lines.push("Why");
-    for (const reason3 of comparison.reasons)
-      lines.push(...wrap(reason3, 2));
+    for (const reason4 of comparison.reasons)
+      lines.push(...wrap(reason4, 2));
   }
   lines.push("", ...wrap("Context reduction is reported separately and is not converted into Claude/Codex subscription quota.", 0));
   return document(lines);
@@ -32684,8 +33068,8 @@ function renderCampaign(lines, campaign) {
   const assessment2 = campaign.assessment;
   lines.push("", "  Selection assessment");
   lines.push(...wrap(`Signal: ${assessment2.signal}; ${assessment2.decisionReady ? "decision-ready" : "not decision-ready"}. Evidence ${String(assessment2.evidencePairs)}/${String(assessment2.minimumEvidencePairs)} minimum; task classes ${String(assessment2.coveredTaskClasses.length)}/${String(assessment2.minimumTaskClasses)} minimum.`, 4));
-  for (const reason3 of assessment2.reasons)
-    lines.push(...wrap(`Reason: ${reason3}.`, 4));
+  for (const reason4 of assessment2.reasons)
+    lines.push(...wrap(`Reason: ${reason4}.`, 4));
   lines.push(...wrap(`Promotion: blocked. ${assessment2.promotionBlockers.join("; ")}.`, 4));
   lines.push(...wrap("Campaign evidence stays separate by evidence class. The selection signal is not a composite score, and promotion remains a separate lifecycle decision.", 2));
 }
@@ -33444,6 +33828,31 @@ var init_metrics2 = __esm({
   }
 });
 
+// apps/cli/dist/src/render/efficiency.js
+function efficiencyDecisionLines(decision, verbose = false) {
+  const value3 = (input) => input === null ? "unknown" : String(input);
+  const percent5 = (input) => input === null ? "unknown" : String(input) + "%";
+  const lines = [
+    ...wrap(`${decision.harness}/${decision.taskClass}: context ${decision.contextAction}`, 2),
+    ...wrap(`model=${value3(decision.model)} effort=${value3(decision.reasoningEffort)} verbosity=${value3(decision.verbosity)}`, 4),
+    ...wrap(`Task allowance: five-hour ${percent5(decision.allowanceBudget.fiveHourPercent)}; weekly ${percent5(decision.allowanceBudget.weeklyPercent)}`, 4),
+    ...wrap(`Attempts=${value3(decision.maxAttempts)}; premium escalations=${value3(decision.premiumEscalationBudget)}`, 4)
+  ];
+  if (verbose) {
+    for (const item of decision.evidence)
+      lines.push(...wrap(`[${item.source}/${item.code}] ${item.summary}`, 4));
+    for (const item of decision.reasons)
+      lines.push(...wrap(`[${item.code}] ${item.summary}`, 4));
+  }
+  return lines.map((line) => truncate(line, 78));
+}
+var init_efficiency = __esm({
+  "apps/cli/dist/src/render/efficiency.js"() {
+    "use strict";
+    init_layout();
+  }
+});
+
 // apps/cli/dist/src/render/optimize.js
 function value2(input) {
   return input ?? "-";
@@ -33474,6 +33883,11 @@ function renderOptimizeReport(report, _context) {
       [harness.contextPressure, 0]
     ]), 78));
   }
+  if (report.efficiencyDecisions?.length) {
+    lines.push("", "EFFICIENCY DECISION (advisory)");
+    for (const decision of report.efficiencyDecisions)
+      lines.push(...efficiencyDecisionLines(decision, true));
+  }
   lines.push("", "PACE");
   let paceRows = 0;
   for (const harness of report.harnesses) {
@@ -33540,6 +33954,7 @@ var init_optimize2 = __esm({
   "apps/cli/dist/src/render/optimize.js"() {
     "use strict";
     init_layout();
+    init_efficiency();
     HARNESS_WIDTH5 = 9;
     STATE_WIDTH4 = 9;
     MODEL_WIDTH2 = 18;
@@ -34130,6 +34545,11 @@ function renderSimpleOptimize(report) {
     if (governor !== void 0)
       lines.push(truncate(`    Context governor: ${governor.action}; ${governor.actionableBytes}B actionable local bytes`, MAX_WIDTH));
   }
+  if (report.efficiencyDecisions?.length) {
+    lines.push("", "EFFICIENCY DECISION (advisory)");
+    for (const decision of report.efficiencyDecisions)
+      lines.push(...efficiencyDecisionLines(decision));
+  }
   lines.push(...changeLine(false));
   const candidate = advice.find((item) => item.recommendedEffort !== item.currentEffort || item.recommendedVerbosity !== item.currentVerbosity);
   const canPlan = candidate !== void 0;
@@ -34267,6 +34687,7 @@ var init_simple = __esm({
     "use strict";
     init_src();
     init_layout();
+    init_efficiency();
   }
 });
 
@@ -34994,6 +35415,7 @@ async function run(options) {
     reservePercent: invocation.options.reservePercent,
     tasksRemaining: invocation.options.tasksLeft,
     contextSnapshotPath: invocation.options.contextSnapshot,
+    efficiencyScheduler: options.efficiencyScheduler ?? null,
     nativePolicy: invocation.options.nativePolicy,
     env: options.env ?? {},
     agentSkill: invocation.options.agentSkill,
@@ -36086,6 +36508,8 @@ var init_guided = __esm({
       loading = null;
       readSequence = 0;
       busy = false;
+      operationSequence = 0;
+      backgroundUpdates = null;
       restartVersion = null;
       restartApplication;
       lastApplied = null;
@@ -36327,6 +36751,7 @@ var init_guided = __esm({
         if (this.busy)
           throw new GuideError(409, "Another operation is running. No second change was started.");
         this.busy = true;
+        this.operationSequence++;
         try {
           if (this.reading !== null)
             await this.reading;
@@ -36963,12 +37388,29 @@ var init_guided = __esm({
           return { url };
         });
       }
-      async checkUpdates() {
-        return this.exclusive(async () => {
-          this.approval = null;
+      async checkUpdates(background = false) {
+        if (background && this.backgroundUpdates !== null)
+          return this.backgroundUpdates;
+        const sequence = this.operationSequence;
+        const startedDuringOperation = this.busy;
+        const operation = async () => {
+          if (!background)
+            this.approval = null;
           this.record("Checking Token Harness and optimizer update channels without changing software.", "working");
           const updateResult = await this.call(["update"]);
           const inventory = await this.call(["doctor"]);
+          if (background && (startedDuringOperation || sequence !== this.operationSequence)) {
+            this.record("Background update evidence discarded after another operation started.", "attention");
+            return {
+              ok: false,
+              title: "Update check needs refreshing",
+              messages: [
+                "Another action started during the update check. Check updates again for current versions."
+              ],
+              appliedPlans: 0,
+              ticket: null
+            };
+          }
           if (inventory.data === null) {
             this.updates = null;
             const message = "The current optimizer versions could not be re-read, so update evidence was not attached to the stack. No software changed.";
@@ -37048,7 +37490,7 @@ var init_guided = __esm({
           const upgradableCount = available.length + (applicationUpgradable ? 1 : 0);
           if (upgradableCount > updateTargets.length) {
             messages.push("An update channel reported an update without a concrete target version. No install approval was created.");
-          } else if (updateTargets.length > 0) {
+          } else if (updateTargets.length > 0 && !background) {
             ticket = this.random();
             const expires = this.now() + 10 * 6e4;
             this.approval = {
@@ -37076,9 +37518,18 @@ var init_guided = __esm({
             messages,
             appliedPlans: 0,
             stack,
-            ticket
+            ticket,
+            ...background ? { updatesAvailable: updateTargets.length > 0 } : {}
           };
-        });
+        };
+        if (!background)
+          return this.exclusive(operation);
+        this.backgroundUpdates = operation();
+        try {
+          return await this.backgroundUpdates;
+        } finally {
+          this.backgroundUpdates = null;
+        }
       }
       async verify() {
         return this.exclusive(() => this.verifyIntegrations());
@@ -39107,11 +39558,100 @@ var init_guided_modal_guard_client = __esm({
   }
 });
 
+// apps/cli/dist/src/guided-optimizer-info.js
+var GUIDE_OPTIMIZER_INFO;
+var init_guided_optimizer_info = __esm({
+  "apps/cli/dist/src/guided-optimizer-info.js"() {
+    "use strict";
+    GUIDE_OPTIMIZER_INFO = {
+      rtk: {
+        name: "RTK",
+        role: "Keeps test, build and Git output short so your agent spends less context on noise.",
+        project: "https://github.com/rtk-ai/rtk",
+        managed: true,
+        useful: "A good baseline when your agent runs many shell commands, especially verbose tests, builds and repository searches.",
+        mechanism: "A command proxy filters supported CLI output before the agent reads it, keeping the useful summary and errors.",
+        limitation: "Only supported command output is affected. Prompts, conversation history and model responses are outside this figure; total-session impact depends on your workload.",
+        claim: {
+          headline: "Up to 90% less",
+          scope: "Supported shell-command output",
+          context: "The project headline compares raw and filtered Bash output. Absolute token counts use bytes \xF7 4 estimates; the headline is not a fixed-suite result or a whole-session saving.",
+          source: "https://github.com/rtk-ai/rtk#how-savings-work"
+        }
+      },
+      harnesstrim: {
+        name: "HarnessTrim",
+        role: "Trims repetitive logs and adds guidance that helps agents keep context lean.",
+        project: "https://github.com/giuliastro/HarnessTrim",
+        managed: true,
+        useful: "Useful for long test logs, lint warnings, large diffs, JSON and file listings, with agent guidance across supported coding apps.",
+        mechanism: "Deterministic reducers remove repetitive output while retaining required signals. Harness integrations and skills help agents use those reducers.",
+        limitation: "Only output sent through a reducer is shortened. The reviewed integration can use instructions or hooks depending on the app and version; setup does not prove every tool is intercepted.",
+        claim: {
+          headline: "75.8% less",
+          scope: "Output tokens \xB7 10 fixed fixtures",
+          context: "The published suite goes from 7,747 to 1,876 cl100k_base tokens, retaining 48/48 required signals. Fixture signal retention does not establish live coding-task quality.",
+          source: "https://github.com/giuliastro/HarnessTrim#measured-evidence-with-boundaries"
+        }
+      },
+      mcptoon: {
+        name: "mcptoon",
+        role: "Loads MCP tool definitions on demand instead of keeping the full catalog in context.",
+        project: "https://github.com/activeing123/mcptoon",
+        managed: true,
+        optional: true,
+        useful: "Consider it when many MCP tools make discovery expensive. Compare it with your app\u2019s native deferred tool loading first; small catalogs may gain little.",
+        mechanism: "A compact tool-name index supports discovery; the agent retrieves detailed schemas when needed. Actual tool calls remain JSON.",
+        limitation: "The headline measures a name index, not full schemas or tool results. On-demand schema reads add context; native tool search and your current stack change the marginal benefit.",
+        claim: {
+          headline: "99.2% less",
+          scope: "Discovery index \xB7 255 tools",
+          context: "Published Sample B: 71,929 full-schema tokens \u2192 581 name-index tokens. The richer SLIM schema format is 8,282 tokens (88.5% less), measured with tiktoken.",
+          source: "https://github.com/activeing123/mcptoon/blob/main/docs/tiktoken-benchmarks.md"
+        }
+      },
+      gitnexus: {
+        name: "GitNexus",
+        role: "Maps code relationships so your agent can find symbols, dependencies and affected code.",
+        project: "https://github.com/abhigyanpatwari/GitNexus",
+        managed: true,
+        optional: true,
+        useful: "Consider it for unfamiliar or large repositories, call-chain tracing and change-impact analysis where repeated searches miss relationships.",
+        mechanism: "Builds a local code knowledge graph and exposes focused repository queries through MCP.",
+        limitation: "Needs an up-to-date repository index; Token Harness registers the integration but does not create or refresh that index. The reviewed version has PolyForm Noncommercial terms: check that they fit your use.",
+        claim: {
+          headline: "No published %",
+          scope: "Repository exploration",
+          context: "The project describes more focused code navigation but publishes no comparable token-reduction benchmark in the reviewed README. Evaluate indexing cost and task quality on your repository.",
+          source: "https://github.com/abhigyanpatwari/GitNexus#why-a-knowledge-graph"
+        }
+      },
+      headroom: {
+        name: "Headroom",
+        role: "Compresses large tool payloads and retrieves relevant context through local MCP tools.",
+        project: "https://github.com/headroomlabs-ai/headroom",
+        managed: true,
+        optional: true,
+        useful: "Consider it for large, repetitive JSON, search results or logs. Compact prose and already-trimmed outputs offer less room for improvement.",
+        mechanism: "Compression and retrieval tools help keep bulky payloads out of context. Token Harness manages the local MCP integration.",
+        limitation: "The managed MCP path does not enable the project\u2019s broader proxy features. Library benchmarks do not establish savings from this integration or added value on top of existing reducers.",
+        claim: {
+          headline: "21\u201357% less",
+          scope: "Input tokens \xB7 4 offline scenarios",
+          context: "Published seeded compress() scenarios report 21%, 57%, 42% and 30% reductions. Codebase exploration goes from 58,801 to 33,895 provider-tokenizer tokens; results depend on payload repetition.",
+          source: "https://github.com/headroomlabs-ai/headroom#proof"
+        }
+      }
+    };
+  }
+});
+
 // apps/cli/dist/src/guided-product-client.js
 var GUIDE_PRODUCT_JS;
 var init_guided_product_client = __esm({
   "apps/cli/dist/src/guided-product-client.js"() {
     "use strict";
+    init_guided_optimizer_info();
     GUIDE_PRODUCT_JS = String.raw`
 'use strict';
 (() => {
@@ -39128,36 +39668,7 @@ var init_guided_product_client = __esm({
     dashboard: ['Overview', 'Your setup, results and next steps.'],
     results: ['Results', 'See what changed and the evidence behind it.'],
   };
-  const TOOL_INFO = {
-    rtk: {
-      name: 'RTK',
-      role: 'Reduces noisy command output before it reaches the model.',
-      managed: true,
-    },
-    harnesstrim: {
-      name: 'HarnessTrim',
-      role: 'Adds version-aware instructions that help coding agents keep tool output and context lean.',
-      managed: true,
-    },
-    mcptoon: {
-      name: 'mcptoon',
-      role: 'Provides compact MCP discovery integration and verifies the resulting setup.',
-      managed: true,
-      optional: true,
-    },
-    gitnexus: {
-      name: 'GitNexus',
-      role: 'Registers GitNexus as a narrow MCP integration for Claude Code and Codex and verifies the result.',
-      managed: true,
-      optional: true,
-    },
-    headroom: {
-      name: 'Headroom',
-      role: 'Provides local MCP compression and retrieval through the installed Headroom server.',
-      managed: true,
-      optional: true,
-    },
-  };
+  const TOOL_INFO = ${JSON.stringify(GUIDE_OPTIMIZER_INFO)};
   const EXPERIMENTAL = [];
   const CATEGORY = {
     'command-output-reduction': 'Command output',
@@ -39176,8 +39687,8 @@ var init_guided_product_client = __esm({
   let modalRun = 0;
   let pendingTicket = null;
   let updateCheckStarted = false;
-  let latestUpdateCheck = null;
   const periodCache = new Map();
+  const openExplanations = new Set();
 
   async function request(path, body) {
     const options = { cache: 'no-store', signal: AbortSignal.timeout(120000) };
@@ -39321,6 +39832,58 @@ var init_guided_product_client = __esm({
     return box;
   }
 
+  function projectLink(label, url, accessibleLabel) {
+    const link = node('a', label, 'project-link');
+    link.href = url;
+    link.target = '_blank';
+    link.rel = 'noopener noreferrer';
+    link.setAttribute('aria-label', accessibleLabel + ' (opens in a new tab)');
+    const icon = node('span', '↗', 'external-link-icon');
+    icon.setAttribute('aria-hidden', 'true');
+    link.append(icon);
+    return link;
+  }
+
+  function explanation(key, label, cls = '') {
+    const details = node('details', undefined, 'feature-explanation ' + cls);
+    details.dataset.key = key;
+    details.open = openExplanations.has(key);
+    details.append(node('summary', label));
+    details.addEventListener('toggle', () => {
+      if (details.open) openExplanations.add(key);
+      else openExplanations.delete(key);
+    });
+    return details;
+  }
+
+  function optimizerExplanation(id, info) {
+    const details = explanation('optimizer:' + id, 'When is ' + info.name + ' useful?', 'optimizer-explanation');
+    const body = node('div', undefined, 'explanation-grid');
+    body.append(
+      messageBox('When to consider it', info.useful || info.role),
+      messageBox('How it works', info.mechanism || 'Review the project documentation for this optimizer’s mechanism.'),
+      messageBox('Before you install', info.limitation || 'Check compatibility and measure the benefit on your own workload.'),
+    );
+    const claim = messageBox('What the project reports', info.claim?.context || 'No published benchmark is included for this optimizer.');
+    if (info.claim?.source)
+      claim.append(projectLink('Benchmark & methodology', info.claim.source, info.name + ' benchmark and methodology'));
+    body.append(claim);
+    details.append(body);
+    return details;
+  }
+
+  function routingExplanation(agentId) {
+    const details = explanation('routing:' + agentId, 'How routing works', 'routing-explanation');
+    const model = agentId === 'codex' ? 'gpt-6-luna' : 'Haiku';
+    details.append(
+      messageBox('One prompt, a focused helper', 'On each submitted prompt, a local hook asks your coding agent to consider one native subagent for a substantial, independent piece of work. For example, the helper can research a module while the main agent implements the change.'),
+      messageBox('The main agent stays in charge', 'The policy requests ' + model + ' when available. Your main model reviews and integrates the result. Trivial edits, tightly coupled work, architecture, security and release decisions stay with the main agent.'),
+      messageBox('When it helps', 'Useful when a bounded task can run independently. Delegation can also add overhead and increase total usage; a cheaper helper alone does not prove token or subscription savings.'),
+      messageBox('How to verify it', (agentId === 'codex' ? 'After enabling, review and trust the hook in Codex /hooks. ' : 'After enabling, start a new session so the hook is loaded. ') + 'A callback proves the hook ran; it does not prove delegation or savings. Results credit savings only from paired runs that pass the quality gate.'),
+    );
+    return details;
+  }
+
   function activeAgents() {
     return current?.agents || [];
   }
@@ -39668,6 +40231,7 @@ var init_guided_product_client = __esm({
       );
       routingCard.append(
         routingHead,
+        node('p', 'Lets your agent delegate suitable work to a smaller native helper while your main model stays in charge.', 'caption'),
         node(
           'p',
           routing?.detail || (routing?.enablement === 'untrusted'
@@ -39682,6 +40246,7 @@ var init_guided_product_client = __esm({
           'caption',
         ),
       );
+      routingCard.append(routingExplanation(agent.id));
       const routingActions = node('div', undefined, 'inline-actions');
       if (routing?.needsRepair) {
         routingActions.append(actionButton('Repair routing', () => reviewPromptRouting(agent.id, true), 'secondary'));
@@ -40025,8 +40590,7 @@ var init_guided_product_client = __esm({
     const agents = activeAgents();
     const ids = optimizerIds();
     if (!agents.length) {
-      root.append(sectionEmpty('Optimizer setup will appear when a supported coding app is detected.'));
-      return;
+      root.append(sectionEmpty('Explore the optimizers below. Connections become available when a supported coding app is detected.'));
     }
 
     const summary = node('div', undefined, 'connection-summary');
@@ -40042,12 +40606,14 @@ var init_guided_product_client = __esm({
     if (baselineActionable)
       summary.append(actionButton('Set up recommended stack', () => reviewSetup(), ''));
     root.append(summary);
+    root.append(node('p', 'Project-reported figures describe different workloads, not expected savings on your machine. Your measured results stay in Results.', 'caption optimizer-claims-note'));
 
     const scroll = node('div', undefined, 'connection-scroll');
     const table = node('div', undefined, 'connection-table');
-    table.style.setProperty('--connection-columns', String(agents.length));
+    table.style.setProperty('--connection-template', 'minmax(240px,1.5fr) minmax(165px,1fr) ' + agents.map(() => 'minmax(110px,.7fr)').join(' ') + ' minmax(150px,.9fr)');
     const header = node('div', undefined, 'connection-row connection-head');
     header.append(node('strong', 'Optimizer', 'connection-name'));
+    header.append(node('strong', 'Project-reported impact', 'optimizer-claim'));
     for (const agent of agents) header.append(node('strong', agent.name, 'connection-cell'));
     header.append(node('strong', 'Action', 'connection-action'));
     table.append(header);
@@ -40055,15 +40621,28 @@ var init_guided_product_client = __esm({
     for (const id of ids) {
       const info = optimizerInfo(id);
       const component = managedComponent(id);
+      const item = node('article', undefined, 'connection-item');
+      item.dataset.optimizer = id;
+      item.setAttribute('aria-label', info.name);
       const row = node('div', undefined, 'connection-row');
       const nameCell = node('div', undefined, 'connection-name');
+      const identity = node('div', undefined, 'optimizer-identity');
+      identity.append(node('strong', info.name));
+      if (info.project) identity.append(projectLink('Source project', info.project, info.name + ' source project'));
       nameCell.append(
-        node('strong', info.name),
+        identity,
         node('span', info.optional ? 'Optional optimizer' : 'Recommended baseline', 'caption'),
         node('span', info.role, 'caption connection-role'),
         node('span', component?.version ? 'v' + component.version : 'Not installed', 'caption'),
       );
       row.append(nameCell);
+      const claimCell = node('div', undefined, 'optimizer-claim');
+      claimCell.append(
+        node('span', 'Project-reported impact', 'connection-app-label'),
+        node('strong', info.claim?.headline || 'No published KPI'),
+        node('span', info.claim?.scope || 'No comparable benchmark available', 'caption'),
+      );
+      row.append(claimCell);
       let actionable = false;
       for (const agent of agents) {
         const target = setupTarget(agent.id, id);
@@ -40094,7 +40673,8 @@ var init_guided_product_client = __esm({
       }
       if (!action.children.length) action.append(node('span', 'No action', 'caption'));
       row.append(action);
-      table.append(row);
+      item.append(row, optimizerExplanation(id, info));
+      table.append(item);
     }
     scroll.append(table);
     root.append(scroll);
@@ -40759,16 +41339,6 @@ var init_guided_product_client = __esm({
     }
   }
 
-  function reviewUpdate(result) {
-    if (!result?.ticket || busy) return;
-    modal('Review Token Harness update');
-    $('modal-content').append(
-      messageBox('Update available', (result.messages || []).join(' ') || result.title || 'A reviewed Token Harness update is ready.'),
-      messageBox('Health re-check', 'After installation, Token Harness will re-check optimizer health automatically.'),
-    );
-    $('modal-actions').append(modalClose('Cancel'), actionButton('Install updates', () => applyTicket(result.ticket)));
-  }
-
   async function checkUpdatesOnStartup() {
     if (updateCheckStarted) return;
     if ($('modal').open) {
@@ -40782,14 +41352,13 @@ var init_guided_product_client = __esm({
     updateCheckStarted = true;
     try {
       await ensureSession();
-      const result = await request('/api/update-check', { period: $('period').value });
+      const result = await request('/api/update-check', { period: $('period').value, background: true });
       if (busy || reading || $('modal').open) {
         updateCheckStarted = false;
         if ($('modal').open) $('modal').addEventListener('close', checkUpdatesOnStartup, { once: true });
         else setTimeout(checkUpdatesOnStartup, 1000);
         return;
       }
-      latestUpdateCheck = result;
       if (result.stack && current) {
         current = { ...current, stack: result.stack };
         renderDashboard();
@@ -40798,13 +41367,13 @@ var init_guided_product_client = __esm({
       }
       const root = $('update-notice');
       root.replaceChildren();
-      if (!result.ticket) {
+      if (!result.updatesAvailable) {
         root.hidden = true;
         return;
       }
       const copy = node('div');
       copy.append(node('strong', result.title || 'Token Harness update available'), node('p', (result.messages || []).join(' ') || 'Review and install the available update.', 'caption'));
-      root.append(copy, actionButton('Review update', () => reviewUpdate(latestUpdateCheck), 'secondary'));
+      root.append(copy, actionButton('Review update', () => readOnlyOperation('update-check'), 'secondary'));
       root.hidden = false;
     } catch {
       // The startup version check is supplementary; Refresh and Health and updates remain available.
@@ -40983,11 +41552,11 @@ var init_guided_product_styles = __esm({
 .connection-summary{display:flex;align-items:center;justify-content:space-between;gap:1rem;background:var(--panel);border:1px solid var(--line);border-radius:var(--radius);padding:1rem}
 .connection-summary p{margin:.15rem 0 0}
 .connection-scroll{overflow-x:auto;border:1px solid var(--line);border-radius:var(--radius);background:var(--panel)}
-.connection-table{min-width:max(720px,100%)}
-.connection-row{display:grid;grid-template-columns:minmax(170px,1.25fr) repeat(var(--connection-columns),minmax(130px,1fr)) minmax(155px,.8fr);align-items:center;gap:.6rem;padding:.72rem .8rem;border-bottom:1px solid var(--line)}
+.connection-table{min-width:100%}
+.connection-row{display:grid;grid-template-columns:var(--connection-template);align-items:center;gap:.8rem;padding:1rem;border-bottom:1px solid var(--line)}
 .connection-row:last-child{border-bottom:0}
 .connection-head{background:var(--panel-soft);color:var(--muted);font-size:.8rem}
-.connection-name{display:grid;gap:.12rem}
+.connection-name{display:grid;gap:.25rem;min-width:0}
 .connection-cell,.connection-action{min-width:0}
 .connection-action{display:flex;justify-content:flex-end}
 .tool-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:.8rem}
@@ -41001,7 +41570,29 @@ var init_guided_product_styles = __esm({
 .tool-facts{display:grid;grid-template-columns:auto 1fr;gap:.3rem .75rem;border-top:1px solid var(--line);border-bottom:1px solid var(--line);padding:.65rem 0;margin:.65rem 0}
 .tool-facts span{color:var(--muted);font-size:.8rem}
 .tool-facts strong{font-size:.85rem}
-.connection-role{max-width:28ch}
+.connection-role{max-width:45ch;line-height:1.5}
+.connection-item{border-bottom:1px solid var(--line)}
+.connection-item:last-child{border-bottom:0}
+.connection-item>.connection-row{border:0}
+.optimizer-identity{display:flex;align-items:center;gap:.6rem;flex-wrap:wrap}
+.optimizer-identity>strong{font-size:.95rem}
+.project-link{display:inline-flex;align-items:center;gap:.3rem;min-height:32px;color:var(--accent);font-size:.78rem;font-weight:600;text-decoration:underline;text-underline-offset:3px;border-radius:4px}
+.project-link:hover{color:var(--text)}
+.external-link-icon{font-size:.9rem;text-decoration:none}
+.optimizer-claim{display:grid;gap:.3rem;min-width:0;align-content:start}
+.optimizer-claim>strong{font-size:1.05rem;font-variant-numeric:tabular-nums}
+.connection-head .optimizer-claim{font-size:inherit}
+.optimizer-claims-note{margin:0 .15rem;max-width:90ch;line-height:1.55}
+.feature-explanation>summary{min-height:44px;align-content:center;font-size:.8rem;color:var(--accent);border-radius:6px}
+.feature-explanation>summary:hover{color:var(--text)}
+.feature-explanation[open]>summary{color:var(--text)}
+.optimizer-explanation{padding:0 1rem .35rem}
+.explanation-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:.75rem;padding:.25rem 0 .8rem}
+.explanation-grid>.explain-box{margin:0;min-width:0}
+.feature-explanation .explain-box{font-size:.85rem;line-height:1.6}
+.feature-explanation .explain-box>strong{font-size:.82rem}
+.routing-explanation{border-top:1px solid var(--line);margin-top:.6rem}
+.routing-explanation .explain-box{background:var(--panel)}
 .setup-choice-list{display:grid;gap:.55rem;margin:.9rem 0}
 .setup-choice-list h3{margin:.25rem 0 0}
 .setup-choice{display:grid;grid-template-columns:auto 1fr;align-items:start;gap:.7rem;padding:.8rem;border:1px solid var(--line);border-radius:12px;background:var(--panel);cursor:pointer}
@@ -41130,16 +41721,22 @@ main,.setup-step{scroll-margin-top:7rem}
 @media(max-width:800px){.evidence-summary{grid-template-columns:minmax(130px,.8fr) minmax(0,1.4fr);gap:1rem}
 .evidence-cue{grid-column:2}
 .evidence-controls{grid-template-columns:repeat(2,minmax(0,1fr))}
-.evidence-search{grid-column:1/-1}
+.evidence-search{grid-column:1/-1}}
+@media(max-width:1000px){
 .connection-scroll{overflow:visible;border:0;background:transparent}
 .connection-table{min-width:0;display:grid;gap:.75rem}
-.connection-row{display:flex;flex-wrap:wrap;gap:.75rem;border:1px solid var(--line);border-radius:12px;background:var(--panel);padding:1rem}
+.connection-item{border:1px solid var(--line);border-radius:12px;background:var(--panel)}
+.connection-item:last-child{border-bottom:1px solid var(--line)}
+.connection-row{display:flex;flex-wrap:wrap;gap:.85rem;padding:1rem}
 .connection-head{display:none}
 .connection-name{width:100%;gap:.25rem}
 .connection-role{max-width:none}
 .connection-cell{display:flex;align-items:center;gap:.5rem}
 .connection-app-label{display:inline;color:var(--muted);font-size:.8rem}
-.connection-action{width:100%;justify-content:flex-start;padding-top:.65rem;border-top:1px solid var(--line)}}
+.connection-action{width:100%;justify-content:flex-start;padding-top:.65rem;border-top:1px solid var(--line)}
+.optimizer-claim{width:100%;background:var(--panel-soft);border:1px solid var(--line);border-radius:10px;padding:.75rem}
+.optimizer-claim .connection-app-label{font-size:.72rem}
+.optimizer-explanation{padding-top:0}}
 @media(max-width:640px){.evidence-summary{grid-template-columns:1fr auto;gap:.85rem;padding:1rem}
 .evidence-identity{grid-column:1}
 .evidence-cue{grid-column:2;grid-row:1;align-self:start}
@@ -41149,6 +41746,7 @@ main,.setup-step{scroll-margin-top:7rem}
 .evidence-controls{gap:.65rem;padding:.85rem}
 .evidence-controls input,.evidence-controls select{font-size:.85rem}
 .maintenance-list{grid-template-columns:1fr}
+.explanation-grid{grid-template-columns:1fr}
 .dashboard-status{align-items:flex-start}
 .brand small{display:none}
 .section-title{align-items:center}
@@ -42126,9 +42724,9 @@ function createGuideHandler(input) {
         if (body === null || typeof body !== "object" || Array.isArray(body))
           throw new GuideError(400, "Only an optional reporting period is accepted.");
         const data = body;
-        if (Object.keys(data).some((key) => key !== "period") || data["period"] !== void 0 && !["all", "7d", "30d"].includes(String(data["period"])))
+        if (Object.keys(data).some((key) => key !== "period" && key !== "background") || data["background"] !== void 0 && typeof data["background"] !== "boolean" || data["period"] !== void 0 && !["all", "7d", "30d"].includes(String(data["period"])))
           throw new GuideError(400, "Only an optional reporting period is accepted.");
-        const result6 = await input.service.checkUpdates();
+        const result6 = await input.service.checkUpdates(data["background"] === true);
         const requested = data["period"];
         let responseResult = result6;
         if (result6.stack !== void 0 && requested !== void 0) {
@@ -42209,6 +42807,10 @@ function shellQuote(value3) {
 function powershellQuote(value3) {
   return `'${value3.replace(/'/g, "''")}'`;
 }
+function windowsLauncher(entryScript, rtkExecutable) {
+  const paths = Buffer.from(JSON.stringify({ entryScript, rtkExecutable })).toString("base64");
+  return `node.exe --eval "const p=JSON.parse(Buffer.from('${paths}','base64').toString());process.argv.splice(1,0,p.entryScript,'__internal-rtk-run','codex','--rtk-executable',p.rtkExecutable);import(require('node:url').pathToFileURL(p.entryScript).href)" --`;
+}
 function toolNameFromInput(input, harness) {
   try {
     const parsed = JSON.parse(input);
@@ -42233,7 +42835,7 @@ function withDatabaseEnvironment(command, databasePath, toolName) {
   }
   return null;
 }
-function attributeRtkHookResponse(stdout, input, databasePath, harness) {
+function attributeRtkHookResponse(stdout, input, databasePath, harness, os, launcher) {
   let response;
   try {
     response = JSON.parse(stdout.trim());
@@ -42248,7 +42850,8 @@ function attributeRtkHookResponse(stdout, input, databasePath, harness) {
   const updatedInput = hookOutput["updatedInput"];
   if (!isRecord5(updatedInput) || typeof updatedInput["command"] !== "string")
     return stdout;
-  const attributed = withDatabaseEnvironment(updatedInput["command"], databasePath, toolNameFromInput(input, harness));
+  const command = updatedInput["command"];
+  const attributed = harness === "codex" && os === "windows" ? launcher !== void 0 && /^\s*rtk(?:\.exe)?(?:\s|$)/i.test(command) ? command.replace(/^\s*rtk(?:\.exe)?/i, windowsLauncher(launcher.entryScript, launcher.rtkExecutable)) : null : withDatabaseEnvironment(updatedInput["command"], databasePath, toolNameFromInput(input, harness));
   if (attributed === null)
     return stdout;
   return `${JSON.stringify({
@@ -42278,10 +42881,20 @@ async function runRtkHookProxy(input) {
     };
   }
   return {
-    stdout: attributeRtkHookResponse(outcome2.stdout, input.stdin, input.databasePath, input.harness),
+    stdout: attributeRtkHookResponse(outcome2.stdout, input.stdin, input.databasePath, input.harness, input.os, input.entryScript !== void 0 && outcome2.executablePath !== null ? { entryScript: input.entryScript, rtkExecutable: outcome2.executablePath } : void 0),
     stderr: outcome2.stderr
   };
 }
+function runAttributedRtkCommand(input) {
+  return input.runner.run({
+    executable: input.executable ?? "rtk",
+    args: [...input.args],
+    cwd: input.cwd,
+    env: { RTK_DB_PATH: input.databasePath },
+    timeoutMs: 0,
+    maxOutputBytes: 32 * 1024 * 1024
+  });
+}
 var MAX_HOOK_OUTPUT_BYTES, HOOK_TIMEOUT_MS;
 var init_rtk_hook_proxy = __esm({
   "apps/cli/dist/src/commands/rtk-hook-proxy.js"() {
@@ -42475,7 +43088,9 @@ Run token-harness ui --help for usage.
       cwd: process5.cwd(),
       harness: harnessId(selected),
       databasePath: fs.join(resolution.environment.paths.state, `rtk-${selected}.db`),
-      stdin: input
+      stdin: input,
+      os: resolution.environment.facts.os,
+      ...process5.argv[1] !== void 0 && (await fs.stat(process5.argv[1]))?.kind === "file" ? { entryScript: process5.argv[1] } : {}
     });
     if (result6.stdout.length > 0)
       process5.stdout.write(result6.stdout);
@@ -42484,6 +43099,28 @@ Run token-harness ui --help for usage.
     process5.exitCode = 0;
     return;
   }
+  if (argv2[0] === "__internal-rtk-run") {
+    const pinnedExecutable = argv2[2] === "--rtk-executable" ? argv2[3] ?? null : null;
+    const commandArgs = argv2.slice(pinnedExecutable === null ? 2 : 4);
+    if (argv2[1] !== "codex" || commandArgs.length === 0 || !resolution.ok || fs === null || attribution.salt === null || pinnedExecutable !== null && (await fs.stat(pinnedExecutable))?.kind !== "file") {
+      process5.stderr.write("[Token Harness] Cannot prepare attributed RTK execution.\n");
+      process5.exitCode = 1;
+      return;
+    }
+    const result6 = await runAttributedRtkCommand({
+      runner: resolution.environment.runner,
+      cwd: process5.cwd(),
+      databasePath: fs.join(resolution.environment.paths.state, "rtk-codex.db"),
+      args: commandArgs,
+      ...pinnedExecutable === null ? {} : { executable: pinnedExecutable }
+    });
+    process5.stdout.write(result6.stdout);
+    process5.stderr.write(result6.stderr);
+    if (result6.stdoutTruncated || result6.stderrTruncated)
+      process5.stderr.write("[Token Harness] RTK output exceeded the 32 MiB capture limit.\n");
+    process5.exitCode = result6.failure !== null || result6.stdoutTruncated || result6.stderrTruncated ? 1 : result6.exitCode ?? 1;
+    return;
+  }
   if (uiInvocation?.ok === true) {
     process5.exitCode = readOnly || uiInvocation.options.json ? await runUi(uiInvocation.options, baseOptions) : await runGuidedUi(uiInvocation.options, baseOptions);
     return;