feat(consult): bind the skill method into the prompt instead of re-activating it every turn

Activating the skill answered with the entrypoint plus a flat listing of every
file in the package, and nothing carried over between requests: the agent is
rebuilt per request, no thread memory is configured, and the replayed history is
plain question/answer text. So the model re-activated on every turn and paid for
that listing every time, twice more whenever a retry opened a fresh model loop.

The method is now read from the hash-verified package and bound into the
instructions, and the activation tools are withdrawn while skill_read stays. The
agents also stopped loading from the working-tree view, whose reference listing
no hash covered - only SKILL.md was compared - so what the model sees is finally
what the registry pinned.

Withdrawing an activation the model could forget also removes the failure it
mostly produced: the contract no longer waits on a model action for method, and
the no-birth-time path has no contract left to repair.

Measured against this package: activation 118,352 bytes, bound method 47,289.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/BUG_HISTORY.md

@@ -4243,8 +4243,25 @@
 - 根因：技能激活的载荷结构使「按需读取」在这个包上不可能发生。实测 `skill()` 单次返回 129,651 字节，其中 SKILL.md 方法论正文 30,507 字节，`## References` 清单 59,584 字节（827 条路径），`## Scripts` 清单约 39,300 字节（760 条路径）——**77% 是 1,592 条不带任何说明的文件名**。Mastra 的 `formatSkillActivation()` 就是 instructions 加上包内全部文件的平铺列举（`#discoverFilesInSubdir` 递归收集，只跳过符号链接目录），本身没有筛选机制。SKILL.md 第 220 行那句「凡是用户询问事业、婚恋、财务、应期……必须先读取 `references/strict-workflow-router.md`」是这 30KB 里的一行，后面紧跟 1,592 个无从分辨的候选；而 Agent 指令另一侧明确要求「调 run-jyotish-consultation 再作答」。模型于是执行了那条可执行的，`skill_read` 一次未发。这不是模型偷懒：给定这份载荷，正确的文件无法被可靠地挑出来。Mastra 自己也在警告 `Instructions have 717 lines (recommended: <500)`。
 - 修复：路由已在服务端定好，skill 又已经声明了每条路由必读哪份清单，所以这个选择根本不需要占用模型的一个回合。新增 `consultationMethodologyForDomains()`：按本轮实际执行的域，从**哈希锁定版**技能包（`versions/6.9.14`，registry 里 sha256 内容寻址）取出 `strict-workflow-router.md` 的共享基线段与该路由的 strict 段、`event_judgment_skeleton.md` 以及该域的 `event_judgment_<domain>.md`，按标题文本定段（路由文件重新编号不会失配），单段上限 6,000 字符、整块上限 24,000 字符，随工具结果的 `methodology` 字段与证据一起交付。实测单域 4 段约 9KB、最宽的四域计划 9 段 21KB，均未触上限。`further_reading` 不是硬编码，而是扫 SKILL.md 自己写出的 `references/...` 路径并剔除包内不存在的，得到 19 条可按需 `skill_read` 的索引——取代原来那 1,592 条。路由未声明 strict 清单的域（annual/general/health/education/migration/family——`full-reading-strict` 只出现在路由表里，文件中没有对应段落）如实列进 `domains_without_strict_checklist`，不拿别的路由顶替。Agent 指令新增一段：把 `methodology` 当作本次作答的方法而非背景，逐条对着证据走，遵守其输出纪律（事业路由要求把「机会接触 / 结构性机会 / 结果显现」三层分开写，不得合并成一个模糊的事业机会窗口——`1797cc73` 那轮恰好就是合并的），且这些段落已交付、不要再花回合重读。
 - 验证：新增 `frontend/tests/consultation-methodology.test.ts` 8 项：事业路由的 strict 段确实带着 `D10` 与 `Opportunity contact` 到位；无 strict 清单的域如实上报且不被顶替；多域计划每条清单只出现一次；十个域逐个与最宽计划都在体积预算内；`further_reading` 只含包内存在的 `references/` 路径且远少于包体清单；交付内容来自锁定版本号；按标题定段在下一个 `##` 处停止。`consultation-agentic-runtime.test.ts` 45 项通过，新增一项钉住回执把「服务端交付了几段」与「模型主动读了几篇」分开报。`tsc --noEmit` 与 `eslint` 清洁（5 条既有 warning 不在改动文件内）。未做的验证：没有在 staging 上比对同一问题在交付方法论前后的回答差异。
-- 待跟进：那 99KB 的文件名清单仍然每次请求都发一遍，只是不再是模型唯一的导航入口。要真正省掉它，需要把技能包的 `references` 从「软链到全部」改成只含 SKILL.md 点名的那一小批（约 20 个文件的目录视图），代价是 `skill_read` 触及范围收窄，且锁定版的 sha256 不再覆盖模型实际看到的内容——另开一轮评估。`referenceReads` 预期仍会经常为 0，这本身不再是缺陷，但它和 `methodologySections` 要一起读。
+- 待跟进：那 99KB 的文件名清单仍然每次请求都发一遍，只是不再是模型唯一的导航入口——已由 BUG-285 收掉（不是收窄清单，而是撤掉激活本身）。`referenceReads` 预期仍会经常为 0，这本身不再是缺陷，但它和 `methodologySections` 要一起读。
 - 防复发：「渐进式披露」只在候选集可判别时成立。把 1,592 个文件平铺给模型，等于既没有给方法也没有给索引，而 `loaded: true` 会让这件事看起来是好的——技能加载成功与方法论被采用之间没有任何因果关系，必须分别度量。另一条：当某个选择在服务端已经确定（这里是 route），就不要把它变成模型的一次工具调用；确定的事交付，不确定的事才询问。
-- 相关记录：BUG-268（把 `referenceReads` 暴露出来，这个问题才可见）、BUG-278（同为「skill 说的和 schema 收的不是一套词汇」）、BUG-279（同为服务端已算出的东西没送到模型手上）
+- 相关记录：BUG-268（把 `referenceReads` 暴露出来，这个问题才可见）、BUG-278（同为「skill 说的和 schema 收的不是一套词汇」）、BUG-279（同为服务端已算出的东西没送到模型手上）、BUG-285（撤掉激活，并补上激活内容从未被哈希覆盖这个洞）
+- 复发自：无
+- 修复版本：待提交
+
+## BUG-285 | 技能激活逐轮重发 129KB，且模型看到的包内容从未被任何哈希覆盖
+
+- 状态：resolved（本地修复，待提交与发布）
+- 首次发现：2026-08-18
+- 最近更新：2026-08-18
+- 影响面：`frontend/src/mastra/skill-binding.ts`（新增）、`frontend/src/mastra/index.ts` 的四个 Agent 与指令、`frontend/src/mastra/consultation-tools.ts` 的运行时状态与钩子、`frontend/src/lib/stream-agent-response.ts` 的契约门与事件映射、`frontend/src/app/api/consult/route.ts` 的回执与重试。个人盘咨询、无出生分钟的通用问答、首页日签的 general 路径、引导问题生成——四条路径全部。
+- 用户现象：没有直接的报错现象，这是一笔一直在付、但从没有人看见账单的开销。用户在 BUG-284 之后追问了两件事：模型在同一个会话里每问一次是不是就要重新调一次 skill；以及那 129,651 字节里 77% 是文件名这件事该怎么处理。
+- 触发条件：任何一次对话的任何一轮。
+- 根因：两件事叠在一起。（一）激活的开销是逐轮的：咨询路径没有配 Mastra memory，也没有 `threadId`/`resourceId`；Agent 每次请求新建（`id` 里含 `requestId`，不进缓存）；回放的 `history` 只有 `{role, text}` 纯文本，不含任何工具调用或工具结果。所以模型每一轮都必须重新激活一次技能，那份载荷逐轮重发；更糟的是一次请求内的 `retry`（契约不完整）与 `retryForAnswer`（空回答）都是 `agent.stream([...baseMessages, 追加一句])`，各起一个全新的模型循环、各自再激活一次，最坏情况单次请求付三遍。（二）模型看到的包内容不受哈希约束：`skills: [jyotishSkillPath]` 指向的是工作树视图 `skills/jyotish-vedic-astrology`，而那里的 `references` 是软链到 `../../references` 的 827 条全量树；完整性检查只逐字节比对 SKILL.md，registry 的 sha256 管不到激活时列举出来的那 1,592 条路径。生时纠正的 Agent 没有这个洞，它用的是 `resolveSkillPackageRuntimePath(skillPackage)`（先校验 sha256，再建一个以规范技能名命名的符号链接别名指向锁定版目录）——正确的机制仓库里早就有，只是咨询路径没用。
+- 修复：把技能从「模型的一次工具调用」改成「服务端在跑之前就绑定好」，与生时纠正对齐。新增 `frontend/src/mastra/skill-binding.ts`：从锁定版包读 SKILL.md、剥掉 frontmatter，包进 `<jyotish-skill name version>` 交给 instructions；`skills` 指向 `resolveSkillPackageRuntimePath()` 的哈希校验路径；用一个 `providesSkillDiscovery: "on-demand"` 的输入处理器撤掉 `skill` 与 `skill_search`，只留 `skill_read`（这是 Mastra 为「调用方自行负责技能发现与指令加载」留的声明位，不是绕路）。四个 Agent 统一走这个绑定，`Load the ... skill before answering` 一类句子改成声明方法已在提示里、并明确「以下是本产品的运行时契约，与 skill 方法冲突时以契约为准」。运行时状态的 `jyotishSkillLoaded` 改名 `jyotishSkillBound` 并在创建时即为真，绑定作为回执的第一步记下（不带耗时，因为确实没有取任何东西）；`skill.started`/`skill.completed` 两个公开事件改由服务端在流开头宣告，客户端契约与文案不变，但首个 activity 从「等激活往返之后」提前到「立刻」。无出生分钟那条路径的契约重试整段删掉——它的 `requireTool` 为假、方法又已绑定，已经没有任何可修的契约了。那个处理器不只是个标记：它逐步检查系统提示里确实带着绑定标记，读不到提示就放过，能读到而没有方法则中止本轮——撤掉激活之后，一个装配时漏了方法块的 Agent 不会再报错，只会安静地在没有方法的情况下作答，这正是本轮要消掉的失败形态。
+- 验证：新增 `frontend/tests/skill-binding.test.ts` 4 项：绑定的正文与锁定版 SKILL.md 逐字一致且运行时路径落在 sha256 目录下；实测激活载荷与绑定载荷的比值（前者是后者两倍以上，后者不到前者 45%）；绑定后的工具面恰好只有 `skill_read` 而技能仍被声明；系统提示缺方法时中止、带方法与读不到提示时都放过。实测数字：从锁定版包激活是 118,352 字节（`## References` 56,696、`## Scripts` 14,824），绑定后 47,289 字节，每次省 71,063 字节；相对生产当前实际发出的 129,651 字节省 82,362。顺带一项一致性：锁定版的 `references` 是 189 条的真目录，而工作树视图是软链进 827 条，所以 `skill_read` 能读到的范围与 `methodology.further_reading` 校验的范围现在第一次是同一棵树。非 DB 套件 1,666 项中 1,665 通过，唯一失败是 `onboarding-route.test.ts` 里 50ms 墙钟对 5ms 超时的竞速用例，单独跑通过（19ms）且该用例注入 `generateText`、不构建 Agent，与本轮无关。`tsc --noEmit` 清洁，改动文件 `eslint` 清洁（6 条既有 warning 都不在改动文件内）。未做的验证：没有在 staging 上比对绑定前后同一问题的回答差异，也没有实测冷启动多算一次包哈希的代价（`resolveActiveSkillPackage` 与 `resolveSkillPackageRuntimePath` 各算一次）。评审中被自己的测试抓到一个真 bug：守卫最初用 `JSON.stringify(system).includes(标记)`，而标记里带双引号、序列化后会被转义，那样每一轮都会误判「方法没绑上」并中止全部请求；改成按形状递归收集字符串。
+- 待跟进：`instructions` 现在 717+ 行，Mastra 仍在警告建议 <500。SKILL.md 里有相当一部分是仓库开发规范（`scripts/`、`references/`、`skills/` 该补成熟度而非重写之类），对回答一个用户的盘没有作用，但它是哈希锁定且本地 Agent 共用的产物，要瘦得重新发版——另开一轮。另外 general 与 onboarding 两条路径也各被绑了 47KB 的解盘方法，而它们一个不能做任何本命盘声明、一个只产四条建议问题；本轮为了不改行为先统一绑定，后续可以逐条裁。
+- 防复发：一次「模型可以忘记」的必要步骤，等于一条必然会出现的失败路径加一条修它的重试；当那一步的内容在服务端已经完全确定时，绑定比请求便宜，也比请求诚实。另一条：完整性检查必须覆盖模型实际看到的东西，而不只是入口文件——只比对 SKILL.md 的字节，会让人以为整个包都被钉住了。
+- 相关记录：BUG-284（同一条链路的上半段：先把方法按路由交付，本轮再撤掉激活）、BUG-282（生时纠正侧的服务端绑定与 `skill.bound`，本轮对齐的先例）、BUG-214（`runtime_contract_incomplete` 的门，本轮去掉了它对模型加载动作的依赖）
 - 复发自：无
 - 修复版本：待提交

frontend/src/app/api/consult/route.ts

@@ -575,7 +575,7 @@ export async function POST(request: Request) {
             ...(skillStep?.durationMs === undefined
               ? {}
               : { durationMs: Math.max(0, Math.trunc(skillStep.durationMs)) }),
-            status: state.jyotishSkillLoaded ? "completed" : "failed",
+            status: state.jyotishSkillBound ? "completed" : "failed",
           },
           {
             phase: "answer.first_activity",
@@ -668,14 +668,8 @@ export async function POST(request: Request) {
       const agent = getGeneralJyotishAgent(selectedModel);
       const result = await agent.stream(baseMessages, streamOptions);
       usages.push(result.totalUsage);
-      const retry = async () => {
-        const retried = await agent.stream([
-          ...baseMessages,
-          { role: "user" as const, content: "运行合同不完整：请先调用 skill({ name: \"jyotish-vedic-astrology\" }) 加载方法，再回答问题。" },
-        ], streamOptions);
-        usages.push(retried.totalUsage);
-        return retried.fullStream;
-      };
+      // This mode has no calculation to require and its method is bound before
+      // the run starts, so there is no longer a contract for a retry to repair.
       const retryForAnswer = async () => {
         const retried = await agent.stream([
           ...baseMessages,
@@ -689,7 +683,7 @@ export async function POST(request: Request) {
         runtime: "mastra-agentic",
         skill: {
           name: "jyotish-vedic-astrology",
-          loaded: state.jyotishSkillLoaded,
+          loaded: state.jyotishSkillBound,
           referenceReads: state.skillReferenceReadCount,
           methodologySections: state.methodologySectionCount,
         },
@@ -704,7 +698,6 @@ export async function POST(request: Request) {
         state,
         stream: result.fullStream,
         requireTool: false,
-        retry,
         retryForAnswer,
         continueAfterDisconnect: true,
         transformText: createBirthTimeModeOutputGuard(consultationMode, false),
@@ -748,7 +741,7 @@ export async function POST(request: Request) {
         ...baseMessages,
         {
           role: "user" as const,
-          content: "运行合同不完整：请先加载 jyotish-vedic-astrology Skill，再调用 run-jyotish-consultation 完成服务器计算；不要在工具参数中添加出生资料。",
+          content: "运行合同不完整：本次尚未取得服务器计算结果。请调用 run-jyotish-consultation 完成计算，再据此回答；不要在工具参数中添加出生资料。",
         },
       ], streamOptions);
       usages.push(retried.totalUsage);
@@ -773,7 +766,7 @@ export async function POST(request: Request) {
       runtime: "mastra-agentic",
       skill: {
         name: "jyotish-vedic-astrology",
-        loaded: state.jyotishSkillLoaded,
+        loaded: state.jyotishSkillBound,
         referenceReads: state.skillReferenceReadCount,
         methodologySections: state.methodologySectionCount,
       },

frontend/src/lib/stream-agent-response.ts

@@ -126,11 +126,22 @@ function recordUnrecordedToolFailure(
   });
 }
 
+/**
+ * The two events that used to report the model activating the skill. The server
+ * binds the method into the instructions now, so they are announced once at the
+ * start of a run instead of being read off a tool call that no longer happens.
+ * They stay in the public stream because they are what tells a waiting client
+ * that method is in hand, and the first of them is a run's first activity.
+ */
+const skillBoundEvents: readonly ConsultationAgentPublicEvent[] = [
+  { type: "skill.started", name: "jyotish-vedic-astrology" },
+  { type: "skill.completed", name: "jyotish-vedic-astrology" },
+];
+
 function mapChunk(
   chunk: Chunk,
   options: EventOptions,
   startedAt: Map<string, number>,
-  jyotishSkillCallIds: Set<string>,
   toolErrors: { seen: number },
 ): ConsultationAgentPublicEvent[] {
   const payload = chunk.payload ?? {};
@@ -141,10 +152,6 @@ function mapChunk(
   if (chunk.type === "tool-call") {
     const toolName = payload.toolName;
     const callId = typeof payload.toolCallId === "string" ? payload.toolCallId : "tool";
-    if (toolName === "skill" && (payload.args as { name?: unknown } | undefined)?.name === "jyotish-vedic-astrology") {
-      jyotishSkillCallIds.add(callId);
-      return [{ type: "skill.started", name: "jyotish-vedic-astrology" }];
-    }
     if (toolName === "run-jyotish-consultation") {
       startedAt.set(callId, Date.now());
       return [{ type: "tool.started", callId, tool: "run-jyotish-consultation", label: "正在计算个人星盘" }];
@@ -153,9 +160,6 @@ function mapChunk(
   if (chunk.type === "tool-result") {
     const toolName = payload.toolName;
     const callId = typeof payload.toolCallId === "string" ? payload.toolCallId : "tool";
-    if (toolName === "skill" && jyotishSkillCallIds.delete(callId)) {
-      return [{ type: "skill.completed", name: "jyotish-vedic-astrology" }];
-    }
     if (toolName === "run-jyotish-consultation") {
       const durationMs = Math.max(0, Date.now() - (startedAt.get(callId) ?? Date.now()));
       if (isToolInputRejection(payload.result)) {
@@ -193,12 +197,14 @@ function mapChunk(
 }
 
 export async function collectAgentPublicEvents(stream: ChunkStream | Iterable<Chunk>, options: EventOptions) {
-  const events: ConsultationAgentPublicEvent[] = [{ type: "run.started", runId: options.runId, requestId: options.requestId }];
+  const events: ConsultationAgentPublicEvent[] = [
+    { type: "run.started", runId: options.runId, requestId: options.requestId },
+    ...skillBoundEvents,
+  ];
   const startedAt = new Map<string, number>();
-  const jyotishSkillCallIds = new Set<string>();
   const toolErrors = { seen: 0 };
   for await (const chunk of stream instanceof ReadableStream || Symbol.asyncIterator in stream ? readChunks(stream as ChunkStream) : stream) {
-    events.push(...mapChunk(chunk, options, startedAt, jyotishSkillCallIds, toolErrors));
+    events.push(...mapChunk(chunk, options, startedAt, toolErrors));
     if (chunk.type === "text-delta" && typeof chunk.payload?.text === "string") {
       events.push({ type: "answer.delta", text: chunk.payload.text });
     }
@@ -228,7 +234,7 @@ type StreamAgentResponseOptions = EventOptions & {
 // the single-calculation boundary. Gating on total attempts would make any
 // transient failure permanently unrecoverable.
 function contractReady(options: StreamAgentResponseOptions) {
-  return options.state.jyotishSkillLoaded
+  return options.state.jyotishSkillBound
     && (!options.requireTool || (options.state.consultationToolCompleted && options.state.consultationToolSuccessCount === 1));
 }
 
@@ -242,7 +248,6 @@ export function streamAgentResponse(options: StreamAgentResponseOptions) {
   let firstOutput = false;
   let fullOutput = "";
   const startedAt = new Map<string, number>();
-  const jyotishSkillCallIds = new Set<string>();
   // A retry reuses these counters so a failure in either attempt is recorded once.
   const toolErrors = { seen: 0 };
   const send = (controller: ReadableStreamDefaultController<Uint8Array> | undefined, event: ConsultationAgentPublicEvent) => {
@@ -283,7 +288,7 @@ export function streamAgentResponse(options: StreamAgentResponseOptions) {
     // total accumulates while the finish reason describes the latest attempt.
     const stepCountBeforeAttempt = options.state.modelStepCount;
     for await (const chunk of readChunks(stream)) {
-      for (const event of mapChunk(chunk, options, startedAt, jyotishSkillCallIds, toolErrors)) send(controller, event);
+      for (const event of mapChunk(chunk, options, startedAt, toolErrors)) send(controller, event);
       if (chunk.type === "step-finish") options.state.modelStepCount += 1;
       if (chunk.type === "finish") {
         const finish = finishTelemetry(chunk);
@@ -301,6 +306,7 @@ export function streamAgentResponse(options: StreamAgentResponseOptions) {
     start(controller) {
       void (async () => {
         send(controller, { type: "run.started", runId: options.runId, requestId: options.requestId });
+        for (const event of skillBoundEvents) send(controller, event);
         try {
           await consumeAttempt(controller, options.stream);
           if (!contractReady(options) && options.retry) {

frontend/src/mastra/consultation-tools.ts

@@ -89,7 +89,14 @@ export type ConsultationRuntimeStep = {
 };
 
 export type ConsultationRuntimeState = {
-  jyotishSkillLoaded: boolean;
+  /**
+   * The server binds the skill method into the agent's instructions before the
+   * model runs, so this is true for the whole run. It was a model action once,
+   * which meant a run could reach the answer with no method loaded and had to be
+   * retried into the contract; the field is kept so that anything downstream
+   * still has to state which method a receipt describes.
+   */
+  jyotishSkillBound: boolean;
   skillReferenceReadCount: number;
   methodologySectionCount: number;
   consultationToolStarted: boolean;
@@ -111,8 +118,8 @@ export type ConsultationRuntimeState = {
 export function createConsultationRuntimeState(options: { plannedSteps?: number; reservedValidationSteps?: number } = {}): ConsultationRuntimeState {
   const reservedValidation = Math.max(0, Math.min(MAX_RECORDED_STEPS - 1, Math.floor(options.reservedValidationSteps ?? 2)));
   const planned = Math.max(1, Math.min(MAX_RECORDED_STEPS - reservedValidation, Math.floor(options.plannedSteps ?? 6)));
-  return {
-    jyotishSkillLoaded: false,
+  const state: ConsultationRuntimeState = {
+    jyotishSkillBound: true,
     skillReferenceReadCount: 0,
     methodologySectionCount: 0,
     consultationToolStarted: false,
@@ -124,6 +131,15 @@ export function createConsultationRuntimeState(options: { plannedSteps?: number;
     stepsTruncated: false,
     modelStepCount: 0,
   };
+  // Binding is the run's first step and it costs no model step, so it is
+  // recorded here rather than observed from the stream. It carries no duration
+  // because nothing is fetched: the method is already in the instructions.
+  appendConsultationRuntimeStep(state, {
+    kind: "skill",
+    name: "jyotish-vedic-astrology",
+    status: "completed",
+  });
+  return state;
 }
 
 /**
@@ -582,24 +598,15 @@ export function createConsultationTools(ctx: ConsultationAgentContext) {
   return { "run-jyotish-consultation": consultationTool };
 }
 
+/**
+ * Activation is no longer a model action, so nothing here watches for it: the
+ * method is bound before the run starts and recorded with the state. What is
+ * left to observe is the opposite direction — whether the model went past the
+ * method it was given and opened a reference of its own.
+ */
 export function createConsultationRuntimeHooks(state: ConsultationRuntimeState) {
-  let skillStartedAt = 0;
-  const isJyotishLoad = (toolName: string, input: unknown) => {
-    if (!input || typeof input !== "object") return false;
-    const value = input as { name?: unknown; skillName?: unknown };
-    return (toolName === "skill" && value.name === "jyotish-vedic-astrology")
-      || (toolName === "load_skill" && value.skillName === "jyotish-vedic-astrology");
-  };
   return {
-    beforeToolCall({ toolName, input }: { toolName: string; input: unknown }) {
-      if (isJyotishLoad(toolName, input)) skillStartedAt = Date.now();
-    },
-    afterToolCall({ toolName, input, error }: { toolName: string; input: unknown; error?: unknown }) {
-      if (isJyotishLoad(toolName, input)) {
-        const durationMs = Date.now() - (skillStartedAt || Date.now());
-        if (!error) state.jyotishSkillLoaded = true;
-        appendConsultationRuntimeStep(state, { kind: "skill", name: "jyotish-vedic-astrology", status: error ? "failed" : "completed", durationMs });
-      }
+    afterToolCall({ toolName, error }: { toolName: string; error?: unknown }) {
       if ((toolName === "skill_read" || toolName === "read_file") && !error) state.skillReferenceReadCount += 1;
     },
   };

frontend/src/mastra/index.ts

@@ -8,13 +8,14 @@ import { evidenceDraftModelOutputSchema } from "../lib/birth-time-guide-agent.ts
 import type { ResolvedLanguageModel } from "./model";
 import { productConversationVoice } from "./product-voice";
 import {
-  resolveActiveSkillPackage,
-} from "../lib/skill-package-registry.ts";
+  jyotishSkillBinding,
+  jyotishSkillMethodBlock,
+  jyotishSkillPackage,
+} from "./skill-binding.ts";
 
 export { consultationInputSchema, consultationWorkflowReceipt, consultationWorkflowResponseSchema, runConsultationWorkflow, toAgentConsultationContext, toModelOutput } from "./consultation-workflow.ts";
 export type { ConsultationInput } from "./consultation-workflow.ts";
 
-const jyotishSkillPackage = resolveActiveSkillPackage("jyotish-vedic-astrology");
 const jyotishSkillVersionsPath = dirname(jyotishSkillPackage.resolvedPath);
 const jyotishSkillPath = dirname(jyotishSkillVersionsPath);
 if (
@@ -24,6 +25,10 @@ if (
 ) {
   throw new Error("Active Jyotish Skill package is not in the canonical versioned layout");
 }
+// Agents read method from the hash-verified package, not from this working-tree
+// view. The view is still checked against it so that editing the canonical
+// entrypoint without publishing a version fails the build instead of quietly
+// leaving the repository and the running product on different method.
 if (
   !readFileSync(resolve(jyotishSkillPath, "SKILL.md")).equals(
     readFileSync(resolve(jyotishSkillPackage.resolvedPath, "SKILL.md")),
@@ -35,10 +40,11 @@ if (
 const jyotishInstructions = `You are the guide for a conversational Vedic astrology product.
 ${productConversationVoice}
 Write in concise Simplified Chinese as a natural conversation, not a report or fixed template. Use Markdown only when it improves scanning; tables are allowed only for genuinely comparative information.
-For Vedic astrology questions, load the jyotish-vedic-astrology skill before deciding which calculation tool or workflow to use. Follow the skill's method and truth boundaries, but use run-jyotish-consultation for actual chart calculations instead of inventing results. Visible chat format is owned by VISIBLE VOICE above, never by the skill's report template.
+${jyotishSkillMethodBlock}
+Everything below is this product's runtime contract and overrides the skill method wherever the two differ. Use run-jyotish-consultation for actual chart calculations instead of inventing results, and let VISIBLE VOICE above own the visible chat format rather than the skill's report template.
 For questions that require a new chart claim, call run-jyotish-consultation before answering. Simple conversational follow-ups may use the existing context.
 Select consultation domains only through the single ordered domains array of run-jyotish-consultation, whether the question covers one domain or several; omit it to accept the domain the server already selected. At most ${MAX_CONSULTATION_DOMAINS} domains may be requested in one run, because they are calculated one after another inside a fixed time budget: list them in priority order and prefer the smallest plan that answers the question, since every extra domain takes time away from writing the answer. The server canonicalizes aliases, rejects unsupported/product domains, executes each accepted domain, and returns the actual domains in the tool context and receipt. The only legal domain ids are the ones enumerated in that array's schema; the skill's methodology names strict-workflow checklists such as career-timing-strict, and those labels select techniques inside the skill, never domains for this tool. A rejected domain plan is final for this run: correct the domains once, and never re-send the same call with extra parameters.
-The tool result's methodology field is the skill's own strict checklist for the routes that actually ran, quoted from the pinned skill version. Treat it as the method for this answer, not as background: work through its mandatory modules against the evidence you were given, and obey its output discipline, including any instruction to separate kinds of claim rather than merge them into one vague statement. Those sections are already delivered, so never spend a turn re-reading them; methodology.further_reading lists the references the skill names, and you may read one with skill_read only when the question needs something the delivered sections do not cover. When methodology.domains_without_strict_checklist names a domain, the skill declares no strict checklist for it: use the shared baseline and do not imply a strict route was followed. When methodology is absent, follow the skill instructions you already loaded.
+The tool result's methodology field is the skill's own strict checklist for the routes that actually ran, quoted from the pinned skill version. Treat it as the method for this answer, not as background: work through its mandatory modules against the evidence you were given, and obey its output discipline, including any instruction to separate kinds of claim rather than merge them into one vague statement. Those sections are already delivered, so never spend a turn re-reading them; methodology.further_reading lists the references the skill names, and you may read one with skill_read only when the question needs something the delivered sections do not cover. When methodology.domains_without_strict_checklist names a domain, the skill declares no strict checklist for it: use the shared baseline and do not imply a strict route was followed. When methodology is absent, follow the bound skill method above.
 The tool result always carries one top-level answer contract—status, evidence_contract, claim_cards, rectification—even when several domains ran. For a multi-domain plan that top level is the most restrictive merge of the executed domains, so obey it exactly as written and read consultations only for per-domain detail. Never treat an absent top-level field as permission to answer without a contract.
 When omitted_domains is non-empty, do not answer those domains and never present the reply as covering the whole plan. Stay with what was calculated. Do not announce a skipped-domain inventory or say this round was incomplete unless the user asked about coverage.
 Activity, progress, tool status, and execution receipts are server-owned. Never imitate data-jyotish-activity, activity events, tool-started/tool-completed messages, or receipts in the answer text.
@@ -76,7 +82,7 @@ export function getJyotishAgent(model: ResolvedLanguageModel, context: Consultat
     name: "Jyotish Guide",
     model: model.model,
     instructions: jyotishInstructions,
-    skills: [jyotishSkillPath],
+    ...jyotishSkillBinding(),
     tools: createConsultationTools(context),
   });
 }
@@ -92,14 +98,15 @@ The server-computed Jyotish workflow below is the only source for this chart cla
 <server-computed-jyotish-workflow>
 ${JSON.stringify(toAgentConsultationContext(workflowContext))}
 </server-computed-jyotish-workflow>`,
-    skills: [jyotishSkillPath],
+    ...jyotishSkillBinding(),
     tools: {},
   });
 }
 
 const generalJyotishInstructions = `You are the guide for a conversational Vedic astrology product.
 ${productConversationVoice}
-Load the jyotish-vedic-astrology skill before answering. This request explicitly has no usable birth minute. Never calculate, infer, or claim a personal birth chart, ascendant, house, divisional chart, dasha, transit timing, or personal prediction. You have no chart tools for this mode.
+${jyotishSkillMethodBlock}
+Everything below overrides that method wherever the two differ. This request explicitly has no usable birth minute. Never calculate, infer, or claim a personal birth chart, ascendant, house, divisional chart, dasha, transit timing, or personal prediction. You have no chart tools for this mode.
 Answer general educational questions that do not depend on the user's natal chart. A homepage daily request may also include a server-owned <public-daily-panchanga> block. In that one case, explain the public calendar trend, suitable actions, cautions, and one practical next step from that block only. State concisely that it is a public-day reference rather than a personal natal forecast; do not reject the whole request merely because the birth minute is unavailable.
 If a request asks for a personal chart conclusion, personal timing, compatibility, or forecast without that public daily evidence, clearly say that this mode cannot answer it and offer exactly two safe next steps: ask a general-knowledge question, or complete birth-time rectification. Do not invent 00:00, a period midpoint, or any other substitute minute.
 Never turn public Panchanga into claims about the user's ascendant, houses, dasha, natal transits, guaranteed outcomes, or exact event timing. Do not invent or alter Panchanga fields that the server did not provide.
@@ -116,7 +123,7 @@ export function getGeneralJyotishAgent(model: ResolvedLanguageModel) {
     name: "Jyotisha General Guide",
     model: model.model,
     instructions: generalJyotishInstructions,
-    skills: [jyotishSkillPath],
+    ...jyotishSkillBinding(),
   });
   generalJyotishAgents.set(model.id, agent);
   return agent;
@@ -124,7 +131,8 @@ export function getGeneralJyotishAgent(model: ResolvedLanguageModel) {
 
 
 const onboardingInstructions = `You create the first conversational turn for Jyotisha, a Vedic astrology chat product.
-Load and follow the jyotish-vedic-astrology skill so the suggested questions respect its scope and truth boundaries.
+${jyotishSkillMethodBlock}
+Follow that method's scope and truth boundaries when suggesting questions; everything below overrides it wherever the two differ.
 This is onboarding, not a chart reading: do not calculate, infer, or claim placements, timing windows, personality traits, relationship outcomes, or career conclusions.
 Return valid JSON only. Do not use Markdown fences, commentary, or hidden fields.
 The JSON shape must be:
@@ -145,7 +153,7 @@ export function getOnboardingAgent(model: ResolvedLanguageModel) {
     name: "Jyotisha Onboarding Guide",
     model: model.model,
     instructions: onboardingInstructions,
-    skills: [jyotishSkillPath],
+    ...jyotishSkillBinding(),
   });
   onboardingAgents.set(model.id, agent);
   return agent;

frontend/src/mastra/skill-binding.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Processor } from "@mastra/core/processors";
+import {
+  resolveActiveSkillPackage,
+  resolveSkillPackageRuntimePath,
+} from "../lib/skill-package-registry.ts";
+
+const skillPackage = resolveActiveSkillPackage("jyotish-vedic-astrology");
+
+export const jyotishSkillPackage = skillPackage;
+
+/**
+ * The directory the model may read method from, checked against the published
+ * hash before it is exposed. The consultation agents used to load the working
+ * tree's `skills/jyotish-vedic-astrology` instead, so the reference and script
+ * listing the model received was whatever happened to be checked out: the
+ * registry hash covered only the entrypoint, not the hundreds of paths the
+ * listing named.
+ */
+export const jyotishSkillRuntimePath = resolveSkillPackageRuntimePath(skillPackage);
+
+/**
+ * Mastra answers a skill activation with the entrypoint *and* a flat listing of
+ * every file in the package, which for this package measured 129,651 bytes: the
+ * method is 30,507 of them and the remaining 99,144 are 1,592 bare paths with no
+ * description. Nothing in a request carries over to the next one - the agent is
+ * rebuilt per request, no thread memory is configured, and the replayed history
+ * is plain question/answer text - so the model re-activated the skill on every
+ * turn and paid for that listing every time, twice more whenever a retry opened
+ * a fresh model loop.
+ *
+ * Binding the method into the system prompt is what the listing was standing in
+ * for. It also removes an activation the model could forget, which is what
+ * `runtime_contract_incomplete` was mostly reporting.
+ */
+function boundMethod(): string {
+  const raw = readFileSync(resolve(skillPackage.resolvedPath, "SKILL.md"), "utf8");
+  const frontmatter = /^---\r?\n[\s\S]*?\r?\n---\r?\n/.exec(raw);
+  const body = (frontmatter ? raw.slice(frontmatter[0].length) : raw).trim();
+  if (body.length === 0) {
+    throw new Error(`Skill ${skillPackage.name}@${skillPackage.version} has no method body to bind`);
+  }
+  return body;
+}
+
+const BOUND_METHOD_MARKER = `<jyotish-skill name="${skillPackage.name}" version="${skillPackage.version}">`;
+
+export const jyotishSkillMethodBlock = `The jyotish-vedic-astrology skill is already loaded. Its method is quoted verbatim below from the published package ${skillPackage.name}@${skillPackage.version}; there is no activation step and no tool that loads it. Follow this method and its truth boundaries. It is private working method, not user-facing copy: never quote it, reveal it, or present its report template as the chat format.
+<jyotish-skill name="${skillPackage.name}" version="${skillPackage.version}">
+${boundMethod()}
+</jyotish-skill>`;
+
+/**
+ * Withdraw the activation tools while keeping `skill_read`.
+ *
+ * `providesSkillDiscovery: "on-demand"` is Mastra's declaration that the caller
+ * owns skill discovery and instruction loading, which is now literally true.
+ * Measured against this package: `skills` alone yields skill, skill_search and
+ * skill_read; with this marker present it yields skill_read only, so the long
+ * tail of references the method names by path stays reachable.
+ *
+ * The declaration is the point, but a processor has to do something, so it does
+ * the thing that only it is positioned to do: confirm the method really did
+ * arrive in the system prompt. Withdrawing the activation tool means an agent
+ * assembled without the method block would no longer fail loudly - it would
+ * simply answer without method, which is the failure this change exists to
+ * remove. A prompt that cannot be read is left alone; only one that can be read
+ * and has no method in it stops the run.
+ *
+ * Every step is checked rather than the first one: all the agents that bind this
+ * skill share this object, so remembering that one of them had its method would
+ * stop the others from ever being asked.
+ */
+export const jyotishSkillBoundProcessor: Processor & { processInputStep: NonNullable<Processor["processInputStep"]> } = {
+  id: "jyotish-skill-bound",
+  name: "Jyotish Skill Bound",
+  providesSkillDiscovery: "on-demand",
+  processInputStep({ messageList, abort }) {
+    const system = messageList?.getAllSystemMessages?.();
+    if (!Array.isArray(system) || system.length === 0) return;
+    if (!collectStrings(system).includes(BOUND_METHOD_MARKER)) {
+      abort(`Jyotish skill method is not bound into the system prompt for ${skillPackage.name}@${skillPackage.version}`);
+    }
+  },
+};
+
+/**
+ * Every string anywhere in a system message, joined. A system message's content
+ * is a string in some shapes and a list of parts in others, and serialising the
+ * whole thing instead would escape the quotes in the marker and never match it.
+ */
+function collectStrings(value: unknown, found: string[] = []): string {
+  if (typeof value === "string") found.push(value);
+  else if (Array.isArray(value)) for (const item of value) collectStrings(item, found);
+  else if (value && typeof value === "object") for (const item of Object.values(value)) collectStrings(item, found);
+  return found.join("\n");
+}
+
+/** Every agent that follows the skill binds it the same way. Fresh arrays per
+ * agent, because the loader takes ownership of the ones it is handed. */
+export function jyotishSkillBinding() {
+  return {
+    skills: [jyotishSkillRuntimePath],
+    inputProcessors: [jyotishSkillBoundProcessor],
+  };
+}

frontend/tests/application-billing-contract.test.ts

@@ -61,9 +61,11 @@ test("standard consultation awaits real usage before durable response settlement
   assert.match(consultRoute, /const actualUsage = await usagePayload\(usage\);[\s\S]*p_actual_usage: actualUsage/);
   assert.match(consultRoute, /function mergeUsage\(usages: Promise<Usage>\[\]\): Promise<Usage> \{[\s\S]*Promise\.all\(usages\)/);
   assert.equal(consultRoute.match(/usages\.push\(result\.totalUsage\)/g)?.length, 2);
-  // Two agentic paths, each with a contract retry and an answer retry: every one
-  // of those four model calls spends tokens and must be metered.
-  assert.equal(consultRoute.match(/usages\.push\(retried\.totalUsage\)/g)?.length, 4);
+  // Two agentic paths with an answer retry each, plus a contract retry on the one
+  // path that requires a calculation: every one of those three model calls spends
+  // tokens and must be metered. The no-birth-time path has no contract left to
+  // repair now that its method is bound before the run starts.
+  assert.equal(consultRoute.match(/usages\.push\(retried\.totalUsage\)/g)?.length, 3);
   assert.equal(consultRoute.match(/const retryForAnswer = async \(\) => \{/g)?.length, 2);
 });
 

frontend/tests/consultation-agentic-runtime.test.ts

@@ -396,7 +396,7 @@ test("a plan larger than the cap cannot be expressed and never starts a calculat
   assert.equal(calls, 0);
   assert.equal("domains" in refused, false);
   assert.equal(state.consultationToolStarted, false);
-  assert.deepEqual(state.steps, []);
+  assert.deepEqual(runSteps(state), []);
 });
 
 test("a plan that runs long stops early and discloses the domains it dropped", async () => {
@@ -538,7 +538,7 @@ test("domain plan enforces the raw plan upper bound and one input mode", async (
   assert.equal("domains" in refused, false);
   assert.equal(rejectedState.consultationToolStarted, false);
   assert.equal(rejectedState.consultationToolCallCount, 0);
-  assert.deepEqual(rejectedState.steps, []);
+  assert.deepEqual(runSteps(rejectedState), []);
 });
 
 test("the single-value domain form stays available to callers without the model schema", () => {
@@ -671,8 +671,6 @@ test("a call rejected before the tool body runs still appears in the receipt", a
   // strict input schema, so `execute` never ran. The client saw tool.failed
   // while the receipt showed no failed step and the budget counted no call.
   const state = createConsultationRuntimeState();
-  state.jyotishSkillLoaded = true;
-  appendConsultationRuntimeStep(state, { kind: "skill", name: "jyotish-vedic-astrology", status: "completed", durationMs: 370 });
   async function* chunks() {
     yield { type: "tool-call", payload: { toolCallId: "call-1", toolName: "run-jyotish-consultation" } };
     yield { type: "tool-error", payload: { toolCallId: "call-1", toolName: "run-jyotish-consultation", error: new Error("bad arguments") } };
@@ -703,7 +701,6 @@ test("a failure the tool already recorded is not recorded twice", async () => {
   // The tool records what it can see, with the duration and cause it alone
   // knows. The stream must only fill the gap, never double-count.
   const state = createConsultationRuntimeState();
-  state.jyotishSkillLoaded = true;
   appendConsultationRuntimeStep(state, {
     kind: "tool", name: "run-jyotish-consultation", status: "failed", durationMs: 20936, failureCode: "workflow_queue_full",
   });
@@ -719,8 +716,9 @@ test("a failure the tool already recorded is not recorded twice", async () => {
   });
   await response.text();
 
-  assert.equal(state.steps.filter((step) => step.status === "failed").length, 1);
-  assert.equal(state.steps[0]?.failureCode, "workflow_queue_full");
+  const failed = state.steps.filter((step) => step.status === "failed");
+  assert.equal(failed.length, 1);
+  assert.equal(failed[0]?.failureCode, "workflow_queue_full");
 });
 
 test("the public receipt never carries the internal failure classification", () => {
@@ -728,11 +726,10 @@ test("the public receipt never carries the internal failure classification", ()
   appendConsultationRuntimeStep(state, {
     kind: "tool", name: "run-jyotish-consultation", status: "failed", durationMs: 12, failureCode: "workflow_server_error",
   });
-  appendConsultationRuntimeStep(state, { kind: "skill", name: "jyotish-vedic-astrology", status: "completed" });
 
   const steps = publicConsultationRuntimeSteps(state);
   assert.equal(steps.every((step) => !("failureCode" in step)), true);
-  assert.equal(state.steps[0]?.failureCode, "workflow_server_error");
+  assert.equal(state.steps.find((step) => step.kind === "tool")?.failureCode, "workflow_server_error");
 
   // A strict receipt schema would reject the internal field, so this also
   // guards the run from failing while building a successful response.
@@ -788,18 +785,16 @@ test("the public receipt never carries the model step budget diagnostics", () =>
 test("the receipt reports how many reference documents the model opened", () => {
   const state = createConsultationRuntimeState();
   const hooks = createConsultationRuntimeHooks(state);
-  const load = { toolName: "skill", input: { name: "jyotish-vedic-astrology" } };
 
-  hooks.beforeToolCall(load);
-  hooks.afterToolCall(load);
-  // Loading the skill supplies its instructions plus a listing of reference filenames. Opening a
-  // listed document is a separate call, so a loaded skill says nothing about method being consulted.
-  assert.equal(state.jyotishSkillLoaded, true);
+  // The method is bound before the model runs, so a run starts with it in hand and
+  // with nothing read. Having the method says nothing about the model having gone
+  // past it to a reference of its own, which is the number this counts.
+  assert.equal(state.jyotishSkillBound, true);
   assert.equal(state.skillReferenceReadCount, 0);
 
-  hooks.afterToolCall({ toolName: "skill_read", input: { skillName: "jyotish-vedic-astrology", path: "references/a.md" } });
-  hooks.afterToolCall({ toolName: "read_file", input: { path: "references/b.md" } });
-  hooks.afterToolCall({ toolName: "skill_read", input: { skillName: "jyotish-vedic-astrology", path: "references/c.md" }, error: new Error("denied") });
+  hooks.afterToolCall({ toolName: "skill_read" });
+  hooks.afterToolCall({ toolName: "read_file" });
+  hooks.afterToolCall({ toolName: "skill_read", error: new Error("denied") });
 
   assert.equal(state.skillReferenceReadCount, 2);
   // Reference reads are not runtime steps, so the step list cannot answer this on its own.
@@ -829,7 +824,12 @@ test("personal Agent exposes the Jyotish Skill and named server tool", async ()
   const skills = await agent.listSkills();
   const toolNames = Object.keys(await agent.getToolsForExecution({ runId: "r" }));
   assert.equal(skills.some((skill) => skill.name === "jyotish-vedic-astrology"), true);
-  assert.equal(toolNames.includes("skill"), true);
+  // Activation is withdrawn: answering an activation meant resending the whole
+  // package listing every turn, and the method is bound into the instructions
+  // instead. Reading a named reference is still the model's own to do.
+  assert.equal(toolNames.includes("skill"), false);
+  assert.equal(toolNames.includes("skill_search"), false);
+  assert.equal(toolNames.includes("skill_read"), true);
   assert.equal(toolNames.includes("run-jyotish-consultation"), true);
   assert.equal(toolNames.includes("consultationTool"), false);
 });
@@ -892,7 +892,8 @@ test("incremental NDJSON parser handles arbitrary chunk boundaries", () => {
 test("uses a bounded dynamic step budget and reports truncation", () => {
   const state = createConsultationRuntimeState({ plannedSteps: 1, reservedValidationSteps: 1 });
   assert.deepEqual(state.stepBudget, { planned: 1, reservedValidation: 1, total: 2 });
-  assert.equal(appendConsultationRuntimeStep(state, { kind: "skill", name: "jyotish-vedic-astrology", status: "completed" }), true);
+  // Binding the method is the run's first recorded step and is already present.
+  assert.deepEqual(state.steps.map((step) => step.kind), ["skill"]);
   assert.equal(appendConsultationRuntimeStep(state, { kind: "validation", name: "ensure-final-response", status: "completed" }), true);
   assert.equal(appendConsultationRuntimeStep(state, { kind: "tool", name: "unexpected-extra-step", status: "completed" }), false);
   assert.equal(state.steps.length, 2);
@@ -900,13 +901,22 @@ test("uses a bounded dynamic step budget and reports truncation", () => {
   assert.deepEqual(consultationStepBudgetReceipt(state), { planned: 2, used: 2, remaining: 0, truncated: true });
 });
 
+/**
+ * The steps a run took, without the method binding every run starts with. The
+ * binding is recorded when the state is created, so a test asking whether a run
+ * advanced has to say which steps it means.
+ */
+function runSteps(state: ReturnType<typeof createConsultationRuntimeState>) {
+  return state.steps.filter((step) => step.kind !== "skill");
+}
+
 function receipt(state: ReturnType<typeof createConsultationRuntimeState>) {
   return {
     runId: "run",
     runtime: "mastra-agentic" as const,
     skill: {
       name: "jyotish-vedic-astrology" as const,
-      loaded: state.jyotishSkillLoaded,
+      loaded: state.jyotishSkillBound,
       referenceReads: state.skillReferenceReadCount,
       methodologySections: state.methodologySectionCount,
     },
@@ -926,7 +936,7 @@ test("text written before the contract completes is dropped, not released later"
     // itself and never answering the question.
     yield { type: "text-delta", payload: { text: "域名单有误，我改为不指定域。" } };
     yield { type: "tool-call", payload: { toolCallId: "skill-1", toolName: "skill", args: { name: "jyotish-vedic-astrology" } } };
-    state.jyotishSkillLoaded = true;
+    state.jyotishSkillBound = true;
     yield { type: "tool-result", payload: { toolCallId: "skill-1", toolName: "skill", result: {} } };
     yield { type: "tool-call", payload: { toolCallId: "tool-1", toolName: "run-jyotish-consultation", args: {} } };
     state.consultationToolCallCount = 1;
@@ -959,7 +969,7 @@ test("a run that only narrated its failures is not delivered or billed as an ans
   let completed = 0;
   async function* chunks() {
     yield { type: "tool-call", payload: { toolCallId: "skill-1", toolName: "skill", args: { name: "jyotish-vedic-astrology" } } };
-    state.jyotishSkillLoaded = true;
+    state.jyotishSkillBound = true;
     yield { type: "tool-result", payload: { toolCallId: "skill-1", toolName: "skill", result: {} } };
     yield { type: "text-delta", payload: { text: "两次域名单都不被服务端接受，我改为不指定域。" } };
     yield { type: "tool-call", payload: { toolCallId: "tool-1", toolName: "run-jyotish-consultation", args: {} } };
@@ -990,10 +1000,6 @@ test("a run that only narrated its failures is not delivered or billed as an ans
 test("a call Mastra rejected against the input schema is not reported as completed", async () => {
   const state = createConsultationRuntimeState({ plannedSteps: 8 });
   async function* chunks() {
-    yield { type: "tool-call", payload: { toolCallId: "skill-1", toolName: "skill", args: { name: "jyotish-vedic-astrology" } } };
-    state.jyotishSkillLoaded = true;
-    appendConsultationRuntimeStep(state, { kind: "skill", name: "jyotish-vedic-astrology", status: "completed", durationMs: 300 });
-    yield { type: "tool-result", payload: { toolCallId: "skill-1", toolName: "skill", result: {} } };
     yield { type: "tool-call", payload: { toolCallId: "tool-1", toolName: "run-jyotish-consultation", args: { domains: ["event-timing-strict"] } } };
     // Mastra resolves rather than throws when arguments fail inputSchema, so the
     // tool body never runs and cannot record anything. Reported as completed this
@@ -1023,7 +1029,7 @@ test("a call Mastra rejected against the input schema is not reported as complet
     state.steps.map((step) => `${step.kind}:${step.status}`),
     ["skill:completed", "tool:failed"],
   );
-  assert.equal(state.steps[1].failureCode, "tool_call_rejected");
+  assert.equal(runSteps(state)[0]?.failureCode, "tool_call_rejected");
   // The rejection reason is a server-side diagnostic; the client sees only that a step failed.
   assert.doesNotMatch(JSON.stringify(events), /tool_call_rejected|validationErrors/);
 });
@@ -1033,7 +1039,7 @@ test("a calculation that succeeds only after failed attempts still satisfies the
   let completed = 0;
   async function* chunks() {
     yield { type: "tool-call", payload: { toolCallId: "skill-1", toolName: "skill", args: { name: "jyotish-vedic-astrology" } } };
-    state.jyotishSkillLoaded = true;
+    state.jyotishSkillBound = true;
     yield { type: "tool-result", payload: { toolCallId: "skill-1", toolName: "skill", result: {} } };
     // Two transient workflow failures, then one success, as observed in production.
     state.consultationToolCallCount = 3;
@@ -1062,7 +1068,7 @@ test("a second successful calculation still fails the single-calculation boundar
   let failed = 0;
   async function* chunks() {
     yield { type: "tool-call", payload: { toolCallId: "skill-1", toolName: "skill", args: { name: "jyotish-vedic-astrology" } } };
-    state.jyotishSkillLoaded = true;
+    state.jyotishSkillBound = true;
     yield { type: "tool-result", payload: { toolCallId: "skill-1", toolName: "skill", result: {} } };
     state.consultationToolCallCount = 2;
     state.consultationToolSuccessCount = 2;
@@ -1107,7 +1113,7 @@ test("incomplete runtime contract fails without saving a successful answer", asy
 
 function toolOnlyRunState() {
   const state = createConsultationRuntimeState();
-  state.jyotishSkillLoaded = true;
+  state.jyotishSkillBound = true;
   state.consultationToolCallCount = 1;
   state.consultationToolSuccessCount = 1;
   state.consultationToolCompleted = true;
@@ -1172,7 +1178,7 @@ test("a calculation still unanswered after the retry fails the run rather than b
 
 test("a completed run records the finish reason and the authoritative step count", async () => {
   const state = createConsultationRuntimeState();
-  state.jyotishSkillLoaded = true;
+  state.jyotishSkillBound = true;
   state.consultationToolCallCount = 1;
   state.consultationToolSuccessCount = 1;
   state.consultationToolCompleted = true;
@@ -1197,7 +1203,7 @@ test("a completed run records the finish reason and the authoritative step count
 
 test("a run that stops while still wanting tools records the exhausted step budget", async () => {
   const state = createConsultationRuntimeState({ plannedSteps: 8 });
-  state.jyotishSkillLoaded = true;
+  state.jyotishSkillBound = true;
   state.consultationToolCallCount = 1;
   state.consultationToolSuccessCount = 1;
   state.consultationToolCompleted = true;
@@ -1234,7 +1240,7 @@ test("a retry accumulates model steps and reports the latest finish reason", asy
     yield { type: "finish", payload: { stepResult: { reason: "tool-calls" }, output: { usage: {} } } };
   }
   async function* retriedAttempt() {
-    state.jyotishSkillLoaded = true;
+    state.jyotishSkillBound = true;
     state.consultationToolCallCount = 1;
     state.consultationToolSuccessCount = 1;
     state.consultationToolCompleted = true;
@@ -1256,10 +1262,8 @@ test("a retry accumulates model steps and reports the latest finish reason", asy
 
 test("a failed run reports the same allowlisted receipt a completed run does", async () => {
   const state = createConsultationRuntimeState({ plannedSteps: 8 });
-  state.jyotishSkillLoaded = true;
   state.modelFinishReason = "tool-calls";
   state.modelStepCount = 8;
-  appendConsultationRuntimeStep(state, { kind: "skill", name: "jyotish-vedic-astrology", status: "completed", durationMs: 900 });
   appendConsultationRuntimeStep(state, {
     kind: "tool", name: "run-jyotish-consultation", status: "failed", durationMs: 20936, failureCode: "workflow_queue_full",
   });
@@ -1283,7 +1287,9 @@ test("a failed run reports the same allowlisted receipt a completed run does", a
   assert.equal(failed.code, "runtime_contract_incomplete");
   // Without this the caller learned only the code: no step durations, no budget,
   // exactly when the run needed explaining most.
-  assert.deepEqual(failed.receipt?.steps.map((step) => step.durationMs), [900, 20936]);
+  // Binding costs no time, so it reports no duration where the old activation
+  // reported a round trip.
+  assert.deepEqual(failed.receipt?.steps.map((step) => step.durationMs), [undefined, 20936]);
   assert.equal(failed.receipt?.stepBudget?.used, 2);
   // The internal classification and the model loop diagnostics stay server-side.
   assert.doesNotMatch(JSON.stringify(failed), /workflow_queue_full|modelFinishReason|modelStepCount|tool-calls/);
@@ -1311,7 +1317,7 @@ test("a receipt that cannot be built still leaves a failure event", async () =>
 
 test("persistence failure emits run.failed instead of run.completed", async () => {
   const state = createConsultationRuntimeState();
-  state.jyotishSkillLoaded = true;
+  state.jyotishSkillBound = true;
   state.consultationToolCallCount = 1;
   state.consultationToolSuccessCount = 1;
   state.consultationToolCompleted = true;

frontend/tests/consultation-birth-time-mode.test.ts

@@ -90,7 +90,8 @@ test("general agent runtime has the Jyotish skill but no personal chart tool", a
   const toolNames = Object.keys(await agent.getToolsForExecution({ runId: "general-zero-tool-probe" }));
 
   assert.equal(skills.some((skill) => skill.name === "jyotish-vedic-astrology"), true);
-  assert.equal(toolNames.includes("skill"), true);
+  // The method is bound into the instructions, so there is no activation to call.
+  assert.equal(toolNames.includes("skill"), false);
   assert.equal(toolNames.includes("run-jyotish-consultation"), false);
 
   const mastra = readFileSync(new URL("../src/mastra/index.ts", import.meta.url), "utf8");
@@ -98,7 +99,7 @@ test("general agent runtime has the Jyotish skill but no personal chart tool", a
     mastra.indexOf("export function getGeneralJyotishAgent"),
     mastra.indexOf("const onboardingInstructions"),
   );
-  assert.match(generalFactory, /skills: \[jyotishSkillPath\]/);
+  assert.match(generalFactory, /\.\.\.jyotishSkillBinding\(\)/);
   assert.doesNotMatch(generalFactory, /run-jyotish-consultation|createConsultationTools/);
 });
 
@@ -119,7 +120,7 @@ test("consult route validates mode before billing and general mode uses no chart
     mastra.indexOf("export function getGeneralJyotishAgent"),
     mastra.indexOf("const onboardingInstructions"),
   );
-  assert.match(generalFactory, /skills: \[jyotishSkillPath\]/);
+  assert.match(generalFactory, /\.\.\.jyotishSkillBinding\(\)/);
   assert.doesNotMatch(generalFactory, /run-jyotish-consultation|createConsultationTools/);
 });
 

frontend/tests/consultation-voice-contract.test.ts

@@ -5,6 +5,7 @@ import test from "node:test";
 const voice = readFileSync(new URL("../src/mastra/product-voice.ts", import.meta.url), "utf8");
 const mastra = readFileSync(new URL("../src/mastra/index.ts", import.meta.url), "utf8");
 const route = readFileSync(new URL("../src/app/api/consult/route.ts", import.meta.url), "utf8");
+const binding = readFileSync(new URL("../src/mastra/skill-binding.ts", import.meta.url), "utf8");
 
 test("product voice overrides skill report format without relaxing truth boundaries", () => {
   assert.match(voice, /VISIBLE VOICE \(overrides skill report format\)/);
@@ -15,9 +16,14 @@ test("product voice overrides skill report format without relaxing truth boundar
   assert.match(voice, /你更适合把已经积累的专业能力做成长期事业/);
 
   assert.match(mastra, /productConversationVoice/);
-  assert.match(mastra, /Visible chat format is owned by VISIBLE VOICE above/);
+  assert.match(mastra, /let VISIBLE VOICE above own the visible chat format/);
   assert.match(mastra, /private working notes, not user-facing copy/);
-  assert.match(mastra, /Follow the skill's method and truth boundaries/);
+  // The method now arrives bound into the prompt rather than fetched by the
+  // model, so both halves of the precedence have to keep being stated: follow the
+  // method, and let this product's contract win where the two disagree.
+  assert.match(binding, /Follow this method and its truth boundaries/);
+  assert.match(binding, /never quote it, reveal it, or present its report template as the chat format/);
+  assert.match(mastra, /overrides the skill method wherever the two differ/);
   assert.match(mastra, /Do not use a restricted technique/);
   assert.match(mastra, /Do not announce a skipped-domain inventory/);
   assert.doesNotMatch(mastra, /Name the domains you did cover, say plainly that the remaining ones were not calculated/);

frontend/tests/consultation-workflow-contract.test.ts

@@ -100,7 +100,7 @@ test("personal Agent owns the Skill and context-bound calculation tool", () => {
     mastra.indexOf("export function getLegacyJyotishAgent"),
   );
   assert.match(personalFactory, /getJyotishAgent\(model: ResolvedLanguageModel, context: ConsultationAgentContext\)/);
-  assert.match(personalFactory, /skills: \[jyotishSkillPath\]/);
+  assert.match(personalFactory, /\.\.\.jyotishSkillBinding\(\)/);
   assert.match(personalFactory, /tools: createConsultationTools\(context\)/);
   assert.doesNotMatch(personalFactory, /server-computed-jyotish-workflow/);
 });

frontend/tests/skill-binding.test.ts

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import test from "node:test";
+import { Agent } from "@mastra/core/agent";
+import {
+  jyotishSkillBinding,
+  jyotishSkillBoundProcessor,
+  jyotishSkillMethodBlock,
+  jyotishSkillPackage,
+  jyotishSkillRuntimePath,
+} from "../src/mastra/skill-binding.ts";
+
+const model = { specificationVersion: "v2", provider: "probe", modelId: "probe" } as never;
+
+function probeAgent(options: Record<string, unknown>) {
+  return new Agent({ id: "skill-binding-probe", name: "Probe", model, instructions: "x", ...options } as never);
+}
+
+test("the method the model follows is the published one, not the working tree's", () => {
+  const published = readFileSync(resolve(jyotishSkillPackage.resolvedPath, "SKILL.md"), "utf8");
+  const body = published.slice(published.indexOf("---", 3) + 4).trim();
+
+  assert.ok(jyotishSkillMethodBlock.includes(body));
+  assert.match(jyotishSkillMethodBlock, new RegExp(`version="${jyotishSkillPackage.version}"`));
+  // The route into the loader is the hash-checked package, so the reference and
+  // script listing the model can reach is the one the registry hash covers.
+  assert.ok(jyotishSkillRuntimePath.includes(jyotishSkillPackage.sha256));
+  assert.ok(jyotishSkillRuntimePath.endsWith(jyotishSkillPackage.name));
+});
+
+test("binding the method costs a fraction of activating the skill", async () => {
+  // What activation would have sent, measured rather than assumed: Mastra answers
+  // it with the entrypoint plus a flat listing of every file in the package, and
+  // that listing is the majority of the bytes. Nothing carries over between
+  // requests, so it was resent on every turn of every conversation.
+  const activation = probeAgent({ skills: [jyotishSkillRuntimePath] });
+  const skillTool = (await activation.getToolsForExecution({ runId: "probe" })).skill as {
+    execute: (input: unknown, context: unknown) => Promise<unknown>;
+  };
+  const activated = await skillTool.execute(
+    { name: jyotishSkillPackage.name },
+    { runId: "probe" } as never,
+  );
+  const activationBytes = Buffer.byteLength(
+    typeof activated === "string" ? activated : JSON.stringify(activated),
+    "utf8",
+  );
+  const boundBytes = Buffer.byteLength(jyotishSkillMethodBlock, "utf8");
+
+  assert.ok(activationBytes > boundBytes * 2, `${activationBytes} vs ${boundBytes}`);
+  assert.ok(boundBytes < activationBytes * 0.45, `${boundBytes} of ${activationBytes}`);
+});
+
+test("agents that bind the method are not given a tool to load it", async () => {
+  const bound = probeAgent(jyotishSkillBinding());
+  const toolNames = Object.keys(await bound.getToolsForExecution({ runId: "probe" }));
+
+  assert.deepEqual(toolNames, ["skill_read"]);
+  // The skill is still declared, so the references the method names by path stay
+  // reachable for the one question the delivered sections do not cover.
+  assert.equal(
+    (await bound.listSkills()).some((skill) => skill.name === jyotishSkillPackage.name),
+    true,
+  );
+});
+
+test("a prompt assembled without the method stops the run instead of answering", () => {
+  const abortReasons: string[] = [];
+  const abort = ((reason?: string) => {
+    abortReasons.push(reason ?? "");
+    throw new Error("aborted");
+  }) as never;
+  const step = (system: unknown[]) => jyotishSkillBoundProcessor.processInputStep({
+    messageList: { getAllSystemMessages: () => system },
+    abort,
+  } as never);
+
+  assert.throws(() => step([{ role: "system", content: "you are a guide" }]), /aborted/);
+  assert.match(abortReasons[0], /not bound into the system prompt/);
+
+  // A prompt that does carry the method, and a prompt that cannot be read at all,
+  // both pass: this guard exists to catch a missing method, not to become a new
+  // way for a run to fail.
+  assert.doesNotThrow(() => step([{ role: "system", content: jyotishSkillMethodBlock }]));
+  assert.doesNotThrow(() => step([]));
+});