@dsh-cc/advisor-watchdog 0.8.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm check:readme --write
+README.md: dab52f2bf8ac3d0df036fd9a4b6a416790fdd121
+README.zh.md: 59d1ff422b97e5916a41453f3119bfb3a25e11dc

package/README.md

@@ -0,0 +1,36 @@
+# @dsh-cc/advisor-watchdog
+
+English | [中文](README.zh.md)
+
+Advisor watchdog: an opt-in **second model** that reviews every completed turn. A passive read-only `llm/stream` listener keeps, per session, the newest qualifying conversation request's message array; at each `agent/turn-stopping`, the plugin extracts the window since its per-session cursor (≈ the last completed turn), renders it as `[role] content` lines (tool-call blocks as `[assistant tool_use <name>] <args>`), and fire-and-forget asks a cheap lane (default alias `haiku`) via `@dsh-cc/side-query`'s one-shot `runSideQuery` — with `onUnrouted: 'skip'` (a hard no-inherit rule: an unconfigured alias can never silently run on the main route) and `rejectToolCalls: true` (no tool loop can exist). The reply is parsed against a strict JSON contract (`nit | concern | blocker`, ≤ 16 notes, ≤ 500 chars, empty allowed) and surviving notes are delivered by one resolve-time `agent.inject()` with source kind `advisor` — never mid-tool-batch, never waking an idle session. **Default off** (`cc-advisor.enabled: false`).
+
+## How it works
+
+Plain plugin (no Service, no isolate key) registering two listeners:
+
+- **`llm/stream`** (read-only, observe-and-passthrough, `{ global: true, prepend: true }` — the cache-health seam): keeps the newest qualifying request's message array per session. A request qualifies iff the loop stamped `sessionId` and no `purpose` is set — so the advisor's own hand-built one-shot calls never enter the snapshots (self-observation excluded by construction), and compaction/session-title auxiliary lanes are skipped. Zero settings/IO work: one array reference, `next()` immediately.
+- **`agent/turn-stopping`** (the trigger; synchronous up to capture, never throwing): gates — settings `enabled` (raw dual-half read), the `subagents` gate unless top-level, session-disabled, inFlight (a stop during flight captures nothing and leaves the cursor alone, so the window accumulates into the next stop) — then the cursor protocol over the snapshot: first observation (init) and rewritten history (compaction/rewind reset) are skipped without a run; the candidate window drops every injected source kind (the advisor's own output is invisible to itself, so a re-opened advisory tail turn never spawns anything); an empty-after-filter window or a window without a genuine user message advances the cursor and skips. On review, the cursor advances immediately (eligibility, not completion), the run is spawned detached, and the turn counter increments after capture; at resolve time notes are dropped as stale unless `turnCounter - capturedTurn <= 1`.
+
+Emission guard (ported from oh-my-pi, plan Appendix A), in fixed order: severity filter → normalized exact-set denylist (37 verbatim omp phrases; "Stop." matches, a genuine blocker mentioning "Stop:" does not) → quarantine scan against `@dsh-cc/permission-rules`' `DEFAULT_DANGEROUS_PATTERNS` → flat dedupe LRU (4096 fingerprints) → immune window (fresh `concern` notes suppressed for `immune-turns` after a delivered concern/blocker) → per-run budget (2 non-blockers, blockers exempt). A session cap (24 delivered notes) silences the advisor for the session.
+
+Journals one JSON line per attempted run to `$DSH_HOME/advisor/<sessionId>.jsonl` (fields: ts, turn, alias, model, inheritedRoute, ok, reason, durationMs, deltaMessages, deltaBytes, notesIn, notesOut, drops, `usage: null` — token metering is N/A until `SideQueryResult` surfaces usage, plan §7). Dogfood plan + jq scoreboard: [`docs/dogfood/advisor-watchdog.md`](../../../docs/dogfood/advisor-watchdog.md).
+
+Cross-package obligation: the `advisor` injected kind is added to the denylists in `@dsh-cc/turn-rules` (matcher) and `@dsh-cc/memory` (recall) — the advisor can never feed on its own or other plugins' injected text, and nothing downstream feeds on advisories.
+
+## Settings (user layer only)
+
+Key `cc-advisor` in the **user-layer** `settings.json` (the harness-home file). Project scope is **never read** — invisible, not refused.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | Master flag. Ship-dark. |
+| `alias` | `"haiku"` | Cheap-lane alias resolved through `ccModelRoutes`. |
+| `budget` | `2` | Max non-blocker notes per run (1–8); blockers exempt. |
+| `immune-turns` | `3` | Turns after a delivered concern/blocker during which fresh concerns are suppressed. |
+| `session-cap` | `24` | Delivered notes per session; reaching it disables the advisor for the session. |
+| `severities` | all three | Which severities survive the first filter. |
+| `subagents` | `"off"` | Global subagent gate (settings-level only, §4.7): `off` reviews top-level sessions only; `on` reviews subagent sessions with the session alias; an alias string reviews them with that alias. |
+
+## Shape
+
+Plain cordis plugin (no Service, no isolate key). Mounted by `packages/preset/cc` in the cc-services group at the group tail, after turn-rules — turn-rules' prompt matcher must see the un-advised prompt (advisor text is denylisted from the matcher's candidate either way). All failure modes fail soft: a listener can never block a step, throw into a waterfall, or wake an idle driver.

package/README.zh.md

@@ -0,0 +1,38 @@
+# @dsh-cc/advisor-watchdog
+
+English | [中文](README.zh.md)
+
+（中文说明，与英文版实质等价。）
+
+Advisor watchdog：可选开启的**第二模型**，审查每一个已完成的轮次。一个只读被动的 `llm/stream` 监听器按会话保存最新的符合条件的对话请求消息数组；在每个 `agent/turn-stopping`，插件提取自其每会话游标以来的窗口（≈ 上一个已完成轮次），渲染为 `[role] content` 行（tool-call 块渲染为 `[assistant tool_use <name>] <args>`），并通过 `@dsh-cc/side-query` 的一次性 `runSideQuery` 以发后即忘的方式询问廉价通道（默认别名 `haiku`）——携带 `onUnrouted: 'skip'`（硬性禁继承规则：未配置的别名绝不可能静默跑在主路由上）和 `rejectToolCalls: true`（不可能存在工具循环）。回复按严格 JSON 契约解析（`nit | concern | blocker`，≤ 16 条，≤ 500 字符，允许为空），幸存的注记在解析时经一次 `agent.inject()` 投递、来源标记 `advisor`——绝不插入工具批次中段，绝不唤醒空闲会话。**默认关闭**（`cc-advisor.enabled: false`）。
+
+## 工作方式
+
+普通插件（无 Service、无 isolate key），注册两个监听器：
+
+- **`llm/stream`**（只读、观察直通、`{ global: true, prepend: true }`——cache-health 同一接缝）：按会话保存最新的符合条件的请求消息数组。请求符合条件当且仅当循环已盖 `sessionId` 戳且未设 `purpose`——因此 advisor 自己手工构建的一次性调用从不进入快照（自我观察在构造上被排除），压缩/会话标题等辅助通道也被跳过。零设置/IO 开销：仅持一个数组引用，立即 `next()`。
+- **`agent/turn-stopping`**（触发器；捕获前全程同步、从不抛出）：闸门——设置 `enabled`（原始双半读取）、非顶层会话受 `subagents` 闸门约束、会话已禁用、inFlight（运行期间的轮次停止既不捕获也不推进游标，窗口累积到下一次停止）——随后对快照执行游标协议：首次观察（init）与被重写的历史（压缩/回退 reset）直接跳过不计费；候选窗口剔除所有注入来源类型（advisor 自己的输出对自身不可见，因此被重开的 advisory 尾轮不会触发任何新调用）；过滤后为空或无真实用户消息的窗口推进游标并跳过。命中审查时游标立即推进（标记资格而非完成），分离地派发运行，并在捕获之后递增轮次计数器；解析时仅当 `turnCounter - capturedTurn <= 1` 才投递，否则按过期丢弃。
+
+发射守卫（自 oh-my-pi 移植，计划附录 A），按固定顺序：严重度过滤 → 归一化精确集合拒绝列表（37 条 omp 原文短语；"Stop." 匹配，而真正提及 "Stop:" 的 blocker 不匹配）→ 以 `@dsh-cc/permission-rules` 的 `DEFAULT_DANGEROUS_PATTERNS` 做隔离扫描 → 扁平去重 LRU（4096 个指纹）→ 免疫窗口（投递过 concern/blocker 之后的 `immune-turns` 个轮次内，新的 `concern` 被抑制）→ 每次运行预算（2 条非 blocker，blocker 豁免）。会话总量上限（24 条已投递注记）到达后对该会话静默。
+
+每次尝试的运行向 `$DSH_HOME/advisor/<sessionId>.jsonl` 追加一行 JSON（字段：ts、turn、alias、model、inheritedRoute、ok、reason、durationMs、deltaMessages、deltaBytes、notesIn、notesOut、drops、`usage: null`——在 `SideQueryResult` 暴露用量之前不计量成本，计划 §7）。Dogfood 计划与 jq 记分板：[`docs/dogfood/advisor-watchdog.md`](../../../docs/dogfood/advisor-watchdog.md)。
+
+跨包义务：注入类型 `advisor` 已加入 `@dsh-cc/turn-rules`（matcher）与 `@dsh-cc/memory`（recall）的拒绝列表——advisor 永不以自己或其他插件的注入文本为食，下游也永不以 advisory 构建查询。
+
+## 配置（仅用户层）
+
+用户层 `settings.json`（harness-home 文件）中的 `cc-advisor` 键。**永不读取**项目作用域——结构上不可见，并非"被拒绝"。
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `enabled` | `false` | 总开关。默认黑暗。 |
+| `alias` | `"haiku"` | 经 `ccModelRoutes` 解析的廉价通道别名。 |
+| `budget` | `2` | 每次运行的非 blocker 注记上限（1–8）；blocker 豁免。 |
+| `immune-turns` | `3` | 投递过 concern/blocker 后的新 concern 抑制轮数。 |
+| `session-cap` | `24` | 每会话已投递注记上限；到达即对该会话禁用。 |
+| `severities` | 三者全开 | 通过第一道过滤的严重级别。 |
+| `subagents` | `"off"` | 子代理全局闸门（仅设置层，§4.7）：`off` 仅审查顶层会话；`on` 以会话别名审查子代理会话；别名字符串则以该别名审查。 |
+
+## 形态
+
+普通 cordis 插件（无 Service、无 isolate key）。由 `packages/preset/cc` 挂载在 cc-services 组尾、turn-rules 之后——turn-rules 的提示匹配器必须看到未被建议的提示（无论怎样，advisor 文本都被排除在匹配候选之外）。所有故障均向软侧失效：监听器绝不能阻塞步骤、向瀑布抛错或唤醒空闲驱动。

package/lib/advise.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The cheap-lane envelope and output contract (plan
+ * docs/plans/2026-09-23-advisor-watchdog.md §4.2/§4.3): one-shot
+ * `runSideQuery` with `onUnrouted: 'skip'` (THE no-inherit switch) and
+ * `rejectToolCalls: true` (one-shot — no tool loop can exist), plus the
+ * deterministic zod parse of the note list.
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { runSideQuery } from '@dsh-cc/side-query';
+import type { Severity } from './settings.ts';
+import type { AdvisorNote } from './guard.ts';
+/** The advisor system prompt (§4.3): role, input format, taxonomy, empty contract. */
+export declare const ADVISOR_SYSTEM_PROMPT: string;
+/** Parse failure result (§4.3 step 3): deliver nothing. */
+export type ParseOutcome = {
+    ok: true;
+    notes: AdvisorNote[];
+} | {
+    ok: false;
+};
+/**
+ * Deterministic parse (§4.3): strip at most one surrounding fence, then
+ * validate against the zod schema. Any failure ⇒ malformed.
+ */
+export declare function parseAdvisorNotes(raw: string): ParseOutcome;
+/** Options for the one-shot advisor call (§4.2 exact shape). */
+export interface AdviseOptions {
+    agent: Agent;
+    alias: string;
+    renderedDelta: string;
+}
+/**
+ * Run the one-shot advisor side query. Never throws (runSideQuery collapses
+ * every failure). No caller signal: disposal is preset remount.
+ */
+export declare function runAdvisor(ctx: Context, opts: {
+    agent: Agent;
+    alias: string;
+    renderedDelta: string;
+}): ReturnType<typeof runSideQuery>;
+/** Re-export for the severity type consumer. */
+export type { Severity };
+//# sourceMappingURL=advise.d.ts.map

package/lib/advise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advise.d.ts","sourceRoot":"","sources":["../src/advise.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,QAStB,CAAA;AAUZ,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,EAAE,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAA;AAEjB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAiB3D;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC3D,UAAU,CAAC,OAAO,YAAY,CAAC,CAWjC;AAED,gDAAgD;AAChD,YAAY,EAAE,QAAQ,EAAE,CAAA"}

package/lib/advise.js

@@ -0,0 +1,71 @@
+/**
+ * The cheap-lane envelope and output contract (plan
+ * docs/plans/2026-09-23-advisor-watchdog.md §4.2/§4.3): one-shot
+ * `runSideQuery` with `onUnrouted: 'skip'` (THE no-inherit switch) and
+ * `rejectToolCalls: true` (one-shot — no tool loop can exist), plus the
+ * deterministic zod parse of the note list.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { runSideQuery } from '@dsh-cc/side-query';
+/** The advisor system prompt (§4.3): role, input format, taxonomy, empty contract. */
+export const ADVISOR_SYSTEM_PROMPT = [
+    'You are a read-only reviewer of one completed turn of a coding session.',
+    'Input: transcript delta lines of the form `[role] content`, oldest first.',
+    'Emit notes at exactly one of three severities:',
+    '- "nit": minor or stylistic.',
+    '- "concern": a likely problem worth one mention.',
+    '- "blocker": user-visible harm in progress, e.g. ignoring an explicit instruction or a destructive command about to run.',
+    'Output ONLY raw JSON: {"notes": [{"severity": "nit|concern|blocker", "text": "<= 500 chars"}]}, at most 16 notes.',
+    'When nothing is worth saying, answer {"notes": []} — empty is the common case.',
+].join('\n');
+/** The exact output contract (§4.3 step 2). */
+const NotesSchema = z.object({
+    notes: z.array(z.object({
+        severity: z.enum(['nit', 'concern', 'blocker']),
+        text: z.string().min(1).max(500),
+    })).max(16),
+});
+/**
+ * Deterministic parse (§4.3): strip at most one surrounding fence, then
+ * validate against the zod schema. Any failure ⇒ malformed.
+ */
+export function parseAdvisorNotes(raw) {
+    let text = raw.trim();
+    if (text.startsWith('```')) {
+        // Strip at most one surrounding fence (with optional language tag). The
+        // closing fence is optional — an assembler may deliver only the opener.
+        const firstNewline = text.indexOf('\n');
+        if (firstNewline === -1)
+            return { ok: false };
+        text = text.slice(firstNewline + 1);
+        const closing = text.lastIndexOf('```');
+        if (closing !== -1)
+            text = text.slice(0, closing).trim();
+    }
+    try {
+        const parsed = NotesSchema.parse(JSON.parse(text));
+        return { ok: true, notes: parsed.notes };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Run the one-shot advisor side query. Never throws (runSideQuery collapses
+ * every failure). No caller signal: disposal is preset remount.
+ */
+export function runAdvisor(ctx, opts) {
+    return runSideQuery(ctx, {
+        agent: opts.agent,
+        alias: opts.alias,
+        system: ADVISOR_SYSTEM_PROMPT,
+        prompt: opts.renderedDelta,
+        maxTokens: 512,
+        timeoutMs: 10_000,
+        onUnrouted: 'skip',
+        rejectToolCalls: true,
+    });
+}
+//# sourceMappingURL=advise.js.map

package/lib/advise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advise.js","sourceRoot":"","sources":["../src/advise.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAIjD,sFAAsF;AACtF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,yEAAyE;IACzE,2EAA2E;IAC3E,gDAAgD;IAChD,8BAA8B;IAC9B,kDAAkD;IAClD,0HAA0H;IAC1H,mHAAmH;IACnH,gFAAgF;CACjF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,+CAA+C;AAC/C,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QACtB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;KACjC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;CACZ,CAAC,CAAA;AAOF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IACrB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,wEAAwE;QACxE,wEAAwE;QACxE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,YAAY,KAAK,CAAC,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAA;QAC7C,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAA;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;QACvC,IAAI,OAAO,KAAK,CAAC,CAAC;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1D,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;QAClD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAA;IACtB,CAAC;AACH,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,GAAY,EACZ,IAA4D;IAE5D,OAAO,YAAY,CAAC,GAAG,EAAE;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,qBAAqB;QAC7B,MAAM,EAAE,IAAI,CAAC,aAAa;QAC1B,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,MAAM;QACjB,UAAU,EAAE,MAAM;QAClB,eAAe,EAAE,IAAI;KACtB,CAAC,CAAA;AACJ,CAAC"}

package/lib/delta.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure delta extraction (plan docs/plans/2026-09-23-advisor-watchdog.md
+ * §4.1): snapshot-window decision over the passive `llm/stream` snapshot,
+ * injected-kind filtering, cursor state, and the newest-tailed ≤ 32 KiB
+ * render. No I/O, no state.
+ *
+ * @module
+ */
+/** The advisory-notes render cap (§4.1). */
+export declare const MAX_DELTA_BYTES = 32768;
+/** Tool-call JSON args render cap (§4.1 render rule). */
+export declare const MAX_TOOL_ARGS_BYTES = 2000;
+/**
+ * Injected source kinds whose messages NEVER enter a review delta (§4.1
+ * step 3). Mirrors the recall.ts / turn-rules matcher denylists rather than
+ * importing them (no shared export exists across those packages).
+ * KNOW YOUR INJECTOR: any new injected message source kind must be added to
+ * ALL THREE copies (recall.ts, turn-rules/matcher.ts, here) or a
+ * self-feeding phantom loop re-opens.
+ */
+export declare const INJECTED_SOURCE_DENYLIST: readonly string[];
+/** This plugin's own injected source kind (MessageSourceMap augmentation in wiring.ts). */
+export declare const ADVISOR_SOURCE_KIND = "advisor";
+/** Cursor over the reviewed prefix of the snapshot messages. */
+export interface Cursor {
+    /** Number of snapshot messages already reviewed (or deliberately skipped). */
+    count: number;
+    /** `JSON.stringify` of the message at `count - 1` (compaction anchor). */
+    tail: string;
+}
+/** Structural content-block subset of a `llm/stream` request message. */
+export interface DeltaBlock {
+    type: string;
+    text?: string;
+    /** `tool-call` blocks: the invoked tool name. */
+    name?: string;
+    /** `tool-call` blocks: raw JSON arguments string. */
+    arguments?: string;
+    /** `tool-result` blocks: nested content. */
+    content?: readonly DeltaBlock[];
+}
+/** Structural message subset read off the `llm/stream` request snapshot. */
+export interface DeltaMessage {
+    role?: string;
+    content: readonly DeltaBlock[];
+    source?: {
+        kind?: string;
+    };
+}
+/** The per-trigger snapshot review decision (§4.1 steps 3-4). */
+export type ReviewWindow = {
+    action: 'init';
+} | {
+    action: 'reset';
+} | {
+    action: 'skip';
+    reason: 'empty-window' | 'no-genuine-user';
+} | {
+    action: 'review';
+    window: readonly DeltaMessage[];
+};
+/** True when the message is genuine user input (source-less OR kind 'user') with ≥1 non-empty text block. */
+export declare function isGenuineUser(message: DeltaMessage): boolean;
+/** The cursor for a full snapshot (first observation / reset / advance). */
+export declare function fullCursor(messages: readonly DeltaMessage[]): Cursor;
+/**
+ * The snapshot-window decision (§4.1 steps 3-4), in order:
+ * init → reset-and-skip → filter → empty-window skip → no-genuine-user skip
+ * → review. The caller advances the cursor to `fullCursor(snapshot)` on
+ * `init`, `reset`, and `skip` — and immediately (before the async call) on
+ * `review` — so a failed cheap-lane call loses its window rather than
+ * double-billing the next one.
+ */
+export declare function reviewWindow(snapshot: readonly DeltaMessage[], cursor: Cursor | undefined): ReviewWindow;
+/**
+ * Render the delta newest-tailed (§4.1): over the byte cap, drop from the
+ * OLDEST end and prepend `[truncated N older bytes]`.
+ */
+export declare function renderDelta(window: readonly DeltaMessage[]): string;
+//# sourceMappingURL=delta.d.ts.map

package/lib/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../src/delta.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,eAAe,QAAS,CAAA;AAErC,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,OAAQ,CAAA;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAOrD,CAAA;AAED,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB,YAAY,CAAA;AAE5C,gEAAgE;AAChE,MAAM,WAAW,MAAM;IACrB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAA;CACb;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;CAChC;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IAC9B,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC3B;AAED,iEAAiE;AACjE,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,iBAAiB,CAAA;CAAE,GAC9D;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,CAAA;AAEzD,6GAA6G;AAC7G,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAG5D;AAOD,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAKpE;AAOD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,YAAY,CAcd;AA2CD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAcnE"}

package/lib/delta.js

@@ -0,0 +1,140 @@
+/**
+ * Pure delta extraction (plan docs/plans/2026-09-23-advisor-watchdog.md
+ * §4.1): snapshot-window decision over the passive `llm/stream` snapshot,
+ * injected-kind filtering, cursor state, and the newest-tailed ≤ 32 KiB
+ * render. No I/O, no state.
+ *
+ * @module
+ */
+/** The advisory-notes render cap (§4.1). */
+export const MAX_DELTA_BYTES = 32_768;
+/** Tool-call JSON args render cap (§4.1 render rule). */
+export const MAX_TOOL_ARGS_BYTES = 2_000;
+/**
+ * Injected source kinds whose messages NEVER enter a review delta (§4.1
+ * step 3). Mirrors the recall.ts / turn-rules matcher denylists rather than
+ * importing them (no shared export exists across those packages).
+ * KNOW YOUR INJECTOR: any new injected message source kind must be added to
+ * ALL THREE copies (recall.ts, turn-rules/matcher.ts, here) or a
+ * self-feeding phantom loop re-opens.
+ */
+export const INJECTED_SOURCE_DENYLIST = [
+    'memory',
+    'cc-subagent-children',
+    'cc-workflow-completion',
+    'turn-rules',
+    'plugin',
+    'advisor',
+];
+/** This plugin's own injected source kind (MessageSourceMap augmentation in wiring.ts). */
+export const ADVISOR_SOURCE_KIND = 'advisor';
+/** True when the message is genuine user input (source-less OR kind 'user') with ≥1 non-empty text block. */
+export function isGenuineUser(message) {
+    if (message.source !== undefined && message.source.kind !== 'user')
+        return false;
+    return message.content.some(block => block.type === 'text' && (block.text ?? '').length > 0);
+}
+/** Injected kinds are invisible to the advisor (§4.1 step 3). */
+function isInjected(message) {
+    return message.source !== undefined && INJECTED_SOURCE_DENYLIST.includes(message.source.kind ?? '');
+}
+/** The cursor for a full snapshot (first observation / reset / advance). */
+export function fullCursor(messages) {
+    return {
+        count: messages.length,
+        tail: messages.length > 0 ? JSON.stringify(messages[messages.length - 1]) : '',
+    };
+}
+/** The tail anchor for the message at `count - 1`, or '' when count is 0. */
+function tailAt(messages, count) {
+    return count > 0 ? JSON.stringify(messages[count - 1] ?? '') : '';
+}
+/**
+ * The snapshot-window decision (§4.1 steps 3-4), in order:
+ * init → reset-and-skip → filter → empty-window skip → no-genuine-user skip
+ * → review. The caller advances the cursor to `fullCursor(snapshot)` on
+ * `init`, `reset`, and `skip` — and immediately (before the async call) on
+ * `review` — so a failed cheap-lane call loses its window rather than
+ * double-billing the next one.
+ */
+export function reviewWindow(snapshot, cursor) {
+    // First observation: cold/resumed history is never review-billed.
+    if (cursor === undefined)
+        return { action: 'init' };
+    // History rewritten (compaction/rewind) → reset+skip.
+    if (snapshot.length < cursor.count || tailAt(snapshot, cursor.count) !== cursor.tail) {
+        return { action: 'reset' };
+    }
+    // Candidate window, filtered to drop injected kinds.
+    const window = snapshot.slice(cursor.count).filter(message => !isInjected(message));
+    // Empty window after filtering ⇒ advance cursor, skip.
+    if (window.length === 0)
+        return { action: 'skip', reason: 'empty-window' };
+    // No genuine user message ⇒ advance cursor, skip (spend guard + wake-loop break).
+    if (!window.some(isGenuineUser))
+        return { action: 'skip', reason: 'no-genuine-user' };
+    return { action: 'review', window };
+}
+/** Args blob truncated at 2000 bytes (§4.1 render rule). */
+function truncateArgs(args) {
+    return Buffer.byteLength(args, 'utf8') > MAX_TOOL_ARGS_BYTES
+        ? `${Buffer.from(args, 'utf8').subarray(0, MAX_TOOL_ARGS_BYTES).toString('utf8')}…`
+        : args;
+}
+/** Render one content block (§4.1 render rule). */
+function renderBlock(block) {
+    if (block.type === 'tool-call') {
+        return `[assistant tool_use ${block.name ?? 'unknown'}] ${truncateArgs(block.arguments ?? '')}`;
+    }
+    if (block.type === 'tool-result') {
+        return (block.content ?? [])
+            .filter(nested => nested.type === 'text')
+            .map(nested => nested.text ?? '')
+            .join('\n');
+    }
+    return block.text ?? '';
+}
+/** `[role] content` lines for one message: text blocks joined, tool blocks rendered. */
+function renderMessage(message) {
+    const role = message.role ?? 'user';
+    const textParts = [];
+    const toolLines = [];
+    for (const block of message.content) {
+        if (block.type === 'tool-call' || block.type === 'tool-result') {
+            const line = renderBlock(block);
+            if (line.length > 0)
+                toolLines.push(line);
+        }
+        else if (block.type === 'text') {
+            textParts.push(block.text ?? '');
+        }
+    }
+    const lines = [];
+    const text = textParts.join('\n');
+    if (text.length > 0)
+        lines.push(`[${role}] ${text}`);
+    lines.push(...toolLines);
+    return lines.join('\n');
+}
+/**
+ * Render the delta newest-tailed (§4.1): over the byte cap, drop from the
+ * OLDEST end and prepend `[truncated N older bytes]`.
+ */
+export function renderDelta(window) {
+    const lines = window.flatMap(renderMessage).filter(line => line.length > 0);
+    const total = Buffer.byteLength(lines.join('\n'), 'utf8');
+    if (total <= MAX_DELTA_BYTES)
+        return lines.join('\n');
+    let truncatedBytes = 0;
+    let start = 0;
+    // Drop whole oldest lines until the remainder fits under the cap.
+    while (start < lines.length) {
+        truncatedBytes += Buffer.byteLength(lines[start] ?? '', 'utf8') + 1;
+        start += 1;
+        if (total - truncatedBytes <= MAX_DELTA_BYTES)
+            break;
+    }
+    const marker = `[truncated ${truncatedBytes} older bytes]`;
+    return [marker, ...lines.slice(start)].join('\n');
+}
+//# sourceMappingURL=delta.js.map