dsh-jenkins-plugin 0.1.1 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # dsh-jenkins-plugin
 
+[![check](https://img.shields.io/github/actions/workflow/status/Endless-zby/dsh-jenkins-plugin/ci.yml?branch=main&label=check)](https://github.com/Endless-zby/dsh-jenkins-plugin/actions/workflows/ci.yml)
+
 Jenkins integration for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): **a live build-progress panel in the Web GUI's right sidebar**, plus a set of model-facing Jenkins tools.
 
 Once installed you stop switching to the Jenkins page to watch a build: the jobs you follow become cards in the sidebar with a live progress bar, a notice when a build finishes, and — when a build fails — one button that hands the failure to the model for a diagnosis.
@@ -77,6 +79,8 @@ Jobs on `denyJobs` are refused whatever the switches say, and **not a single req
 
 **Completion notices**: a followed job's finished build is announced once through the platform's own background-job mechanism; the same build is never announced twice.
 
+**Failure wake** (`notifyWakeOnFailure`, off by default): when a *followed* job fails, the conversation it was followed from gets the failure handed to it — the same log tail, stage and commits the button sends — so the model can explain it without anyone watching the build list. The favorite remembers which session followed it, so the answer lands where the person is. Only a real failure wakes anyone (`unstable` and `aborted` do not), each build wakes at most once, and a session that has closed is skipped silently. `allowAnalyze: false` turns it off too, since it sends the same log.
+
 ## Permissions and risks
 
 Please take these as read before installing:
@@ -90,7 +94,7 @@ Please take these as read before installing:
 
 ## Compatibility
 
-- **Harness**: built and verified against `0.1.6-alpha.2` (both `engines.dsh` and the peer dependencies pin that version).
+- **Harness**: built and verified against `0.2.1-rc.3`. `engines.dsh` accepts the `0.2.1-rc.3` line and later `0.2.x` releases (`>=0.2.1-rc.3 <0.3.0-0`), and the `@deepseek-ai/dsh-*` peer dependencies use `^0.2.1-rc.3`. Older harness lines (`0.1.x`) are **not** supported: the plugin uses harness APIs that changed between them.
 - **Node**: matches the harness, `^22.19.0 || >=24.0.0`.
 - **Surface**: the panel is a Web GUI surface (`dsh web`), verified on the Web composition.
 - **Jenkins**: verified against a real **Jenkins 2.176.2** (FreeStyle and Maven jobs, an instance with 777 jobs). Several honest degradations:
@@ -98,7 +102,7 @@ Please take these as read before installing:
   - **Workspace reads** need the Jenkins Workspace API plugin; without it `jenkins_workspace` says so instead of pretending.
   - **Maven versions** come from `mavenArtifacts/api/json`, which only Maven jobs answer — and on a real 2.176.2 it is usually produced when the build *ends*, so a running Maven build's card may have no version. When there is none, nothing is shown; a version is never guessed.
   - **Artifacts carry no size**: Jenkins' `tree` query cannot fetch artifact sizes.
-- **Not finished yet**: `notifyWakeOnFailure` (wake the model when a build fails) and `uiAutoOpenOnTrigger` (open the panel on trigger) are accepted but **not active**; `maxTrackedBuilds` is advisory only — the followed list is the user's own choice, so nothing is hard-capped.
+- **Not finished yet**: `uiAutoOpenOnTrigger` (open the panel on trigger) is accepted but **not active**; `maxTrackedBuilds` is advisory only — the followed list is the user's own choice, so nothing is hard-capped.
 
 ## Configuration
 
@@ -142,7 +146,7 @@ Static configuration is only the **fallback layer**: instances configured in the
 | `maxWorkspaceEntries` | `500` | entry cap on one workspace directory listing |
 | `maxReadFileBytes` | `1048576` | byte cap on one workspace file read |
 | `notifyOnComplete` | `true` | announce a followed build when it finishes |
-| `notifyWakeOnFailure` | `false` | wake the model on failure (**not active yet**) |
+| `notifyWakeOnFailure` | `false` | hand a failed followed build to the session that followed it |
 | `allowAnalyze` | `true` | allow handing a failed build to the model |
 | `analyzeLogBytes` | `16384` | log-tail bytes handed to the model |
 | `uiAutoOpenOnTrigger` | `true` | open the panel on trigger (**not active yet**) |
@@ -154,7 +158,7 @@ Static configuration is only the **fallback layer**: instances configured in the
 ```sh
 npm install          # runs prepare (= build) once
 npm run typecheck
-npm test             # 235 assertions, no test framework: every tests/*.ts runs on its own
+npm test             # 415 assertions, no test framework: every tests/*.ts runs on its own
 npm run build        # tsc (Host half) + esbuild (browser half → lib/client.js)
 npm run check        # test + secret scan + packed-payload audit
 ```
@@ -163,7 +167,7 @@ The browser half is bundled into the client module system's lazy factory (`windo
 
 `tests/stub-jenkins.ts` is a zero-dependency stub Jenkins (`node tests/stub-jenkins.ts`) with stages, a failing build, a parameterized Maven job, write endpoints and a queue delay; it exercises the panel's live path and write path without touching a real controller.
 
-Three gates run before a release (and are what CI should run):
+Three gates run before a release (and are what CI runs):
 
 ```sh
 npm run check:secrets   # credential shapes in everything a commit would carry (private hostnames / user paths warn only)
@@ -171,6 +175,9 @@ npm run check:payload   # reads npm pack's manifest: artifacts present, no src/
 npm pack                # produce the tarball, install it into a clean profile, then publish
 ```
 
+Releasing is scripted end to end in [RELEASING.md](RELEASING.md) (`npm run release:check` is the
+pre-flight that refuses to reuse a version or a tag).
+
 ## License
 
 [MIT](LICENSE)

package/README.zh.md

@@ -1,5 +1,7 @@
 # dsh-jenkins-plugin
 
+[![check](https://img.shields.io/github/actions/workflow/status/Endless-zby/dsh-jenkins-plugin/ci.yml?branch=main&label=check)](https://github.com/Endless-zby/dsh-jenkins-plugin/actions/workflows/ci.yml)
+
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 Jenkins 插件：**Web GUI 右侧栏里的实时构建面板**，加上一组面向模型的 Jenkins 工具。
 
 装完之后，你不再需要为了看一次构建进度而切到 Jenkins 页面：关注的 job 变成侧栏里的卡片，进度条实时走，构建结束发通知，失败了一键交给模型分析原因。
@@ -77,6 +79,8 @@ allowBuilds:
 
 **完成通知**：关注的 job 一有构建结束就用平台的后台作业机制发一次通知，同一次构建只通知一次。
 
+**失败唤醒**（`notifyWakeOnFailure`，默认关）：**关注的** job 一旦失败，就把它交给「你当初关注它的那个会话」——发的是和按钮相同的那份日志尾部、失败阶段与提交，所以模型能在没人盯着构建列表的时候先说明原因，答案出现在你正在读的对话里。关注项记着是哪个会话关注的，所以通知不会跑错地方。只有真正的失败才唤醒（`unstable`、`aborted` 不算），同一次构建最多唤醒一次，会话已经关闭就静默跳过。`allowAnalyze: false` 也会关掉它——两者发给模型的是同一份日志。
+
 ## 权限与风险
 
 装之前请如实了解这个插件会做什么：
@@ -90,7 +94,7 @@ allowBuilds:
 
 ## 兼容性
 
-- **Harness**：针对 `0.1.6-alpha.2` 构建并验证（`package.json` 的 `engines.dsh` 与 peerDependencies 都钉在这个版本）。
+- **Harness**：针对 `0.2.1-rc.3` 构建并验证。`engines.dsh` 接受 `0.2.1-rc.3` 及后续 `0.2.x`（`>=0.2.1-rc.3 <0.3.0-0`），`@deepseek-ai/dsh-*` 的 peerDependencies 用 `^0.2.1-rc.3`。**不再支持**旧 `0.1.x` 线：插件使用的 harness API 在其间有变化。
 - **Node**：与 harness 一致，`^22.19.0 || >=24.0.0`。
 - **载体**：面板是 Web GUI 的界面（`dsh web`），在 Web 组合上验证过。
 - **Jenkins**：在 **Jenkins 2.176.2** 上实测（FreeStyle 与 Maven job，777 个 job 的实例）。几条如实降级：
@@ -98,7 +102,7 @@ allowBuilds:
   - **读工作空间**需要 Jenkins Workspace API 插件；缺失时 `jenkins_workspace` 会如实说明该 Jenkins 不支持。
   - **Maven 版本号**取自 `mavenArtifacts/api/json`，只有 Maven job 有，且真实 2.176.2 上通常在构建**结束后**才产生，所以正在跑的 Maven 构建卡片上可能没有版本号（拿不到就不显示，绝不猜）。
   - **产物没有大小**：Jenkins 的 `tree` 查询取不到 artifact size。
-- **已知未完成**：`notifyWakeOnFailure`（失败时唤醒模型）与 `uiAutoOpenOnTrigger`（触发后自动展开面板）两个配置项已接受但**尚未生效**；`maxTrackedBuilds` 只是建议值，不硬性限制跟踪数量（关注列表是用户自己挑的）。
+- **已知未完成**：`uiAutoOpenOnTrigger`（触发后自动展开面板）已接受但**尚未生效**；`maxTrackedBuilds` 只是建议值，不硬性限制跟踪数量（关注列表是用户自己挑的）。
 
 ## 配置
 
@@ -142,7 +146,7 @@ allowBuilds:
 | `maxWorkspaceEntries` | `500` | 单次工作空间目录列出的条目上限 |
 | `maxReadFileBytes` | `1048576` | 单个工作空间文件的读取上限 |
 | `notifyOnComplete` | `true` | 关注的构建结束时是否发通知 |
-| `notifyWakeOnFailure` | `false` | 失败时唤醒模型（**尚未生效**） |
+| `notifyWakeOnFailure` | `false` | 关注的构建失败时，交给当初关注它的会话 |
 | `allowAnalyze` | `true` | 是否允许把失败构建交给模型分析 |
 | `analyzeLogBytes` | `16384` | 交给模型分析的日志尾部字节数 |
 | `uiAutoOpenOnTrigger` | `true` | 触发后自动展开面板（**尚未生效**） |
@@ -154,7 +158,7 @@ allowBuilds:
 ```sh
 npm install          # 会跑一次 prepare（=构建）
 npm run typecheck
-npm test             # 235 项断言，无测试框架：每个 tests/*.ts 都是可直接运行的脚本
+npm test             # 415 项断言，无测试框架：每个 tests/*.ts 都是可直接运行的脚本
 npm run build        # tsc（Host 半）+ esbuild（浏览器半 → lib/client.js）
 npm run check        # test + 密钥扫描 + 打包内容审计
 ```
@@ -171,6 +175,9 @@ npm run check:payload   # 读 npm pack 的清单：产物齐不齐、有没有
 npm pack                # 出 tarball，先在一个干净 profile 上装一遍再 publish
 ```
 
+完整的发布步骤（含实测脚本、陷阱速查、以及"只有人能做的三件事"）见 [RELEASING.md](RELEASING.md)；
+`npm run release:check` 是发布前预检，会挡住重复使用版本号或 tag 这类事故。
+
 ## 许可证
 
 [MIT](LICENSE)

package/lib/client/Panel.js

@@ -133,7 +133,9 @@ function Home({ t, state, busy, instanceId, sessionId, onReload, onOpenJob, onSw
     /** Follow or unfollow one job, then refresh the cards. */
     const toggle = useCallback(async (job) => {
         const wantFollowed = !followed.has(job.path);
-        const answer = await toggleFavorite(instanceId, job.path, job.name, wantFollowed);
+        // The session goes along with the follow: a failure of this job wakes that
+        // conversation, and the host records it on the favorite for the watcher.
+        const answer = await toggleFavorite(instanceId, job.path, job.name, wantFollowed, sessionId);
         if (isFailure(answer)) {
             setToast(answer.message);
             setTimeout(() => { setToast(undefined); }, 4000);
@@ -142,7 +144,7 @@ function Home({ t, state, busy, instanceId, sessionId, onReload, onOpenJob, onSw
         setToast(wantFollowed ? t('favorites.added', { name: job.name }) : t('favorites.removed', { name: job.name }));
         setTimeout(() => { setToast(undefined); }, 2500);
         await loadFavorites();
-    }, [followed, instanceId, loadFavorites, t]);
+    }, [followed, instanceId, loadFavorites, sessionId, t]);
     // The followed list itself is only re-read when a followed build ends, so a
     // card's own numbers never go stale while it is running.
     return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0 }, children: [_jsxs("div", { style: { padding: '8px 12px', borderBottom: '1px solid var(--dsw-alias-border-l2)' }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_jsx("span", { style: { fontWeight: 600, fontSize: 'var(--dsw-font-sm-13)' }, children: t('panel.title') }), _jsxs("span", { title: `${state.connection.name} — ${state.connection.baseUrl}`, style: {

package/lib/client/api.d.ts

@@ -202,8 +202,19 @@ export interface FavoritesPayload {
 }
 /** Read one instance's favorited jobs, with their current build and progress. */
 export declare function fetchFavorites(instanceId?: string): Promise<FavoritesPayload | ApiFailure>;
-/** Add or remove one favorite. */
-export declare function toggleFavorite(instanceId: string, path: string, name: string, favorited: boolean): Promise<{
+/**
+ * Add or remove one favorite.
+ *
+ * The session is sent so the host can remember who followed the job: that is
+ * where a failure wake goes, and the watcher has no other way to know it.
+ * @param instanceId - the instance the job belongs to.
+ * @param path - job path.
+ * @param name - display name to record.
+ * @param favorited - the desired state.
+ * @param sessionId - the conversation following it, when the panel knows one.
+ * @returns the instance's favorites after the change, or a failure.
+ */
+export declare function toggleFavorite(instanceId: string, path: string, name: string, favorited: boolean, sessionId?: string): Promise<{
     ok: true;
     instanceId: string;
     favorites: FavoriteRow[];

package/lib/client/api.js

@@ -103,11 +103,22 @@ export async function fetchFavorites(instanceId) {
         : `?instance=${encodeURIComponent(instanceId)}`;
     return await request(`/jenkins-plugin/favorites${query}`);
 }
-/** Add or remove one favorite. */
-export async function toggleFavorite(instanceId, path, name, favorited) {
+/**
+ * Add or remove one favorite.
+ *
+ * The session is sent so the host can remember who followed the job: that is
+ * where a failure wake goes, and the watcher has no other way to know it.
+ * @param instanceId - the instance the job belongs to.
+ * @param path - job path.
+ * @param name - display name to record.
+ * @param favorited - the desired state.
+ * @param sessionId - the conversation following it, when the panel knows one.
+ * @returns the instance's favorites after the change, or a failure.
+ */
+export async function toggleFavorite(instanceId, path, name, favorited, sessionId) {
     return await request('/jenkins-plugin/favorites/toggle', {
         method: 'POST',
-        body: { instance: instanceId, path, name, favorited },
+        body: { instance: instanceId, path, name, favorited, ...sessionId === undefined ? {} : { session: sessionId } },
     });
 }
 /**

package/lib/client.js

@@ -100,10 +100,10 @@ async function fetchFavorites(instanceId) {
   const query = instanceId === void 0 || instanceId.length === 0 ? "" : `?instance=${encodeURIComponent(instanceId)}`;
   return await request(`/jenkins-plugin/favorites${query}`);
 }
-async function toggleFavorite(instanceId, path, name, favorited) {
+async function toggleFavorite(instanceId, path, name, favorited, sessionId) {
   return await request("/jenkins-plugin/favorites/toggle", {
     method: "POST",
-    body: { instance: instanceId, path, name, favorited }
+    body: { instance: instanceId, path, name, favorited, ...sessionId === void 0 ? {} : { session: sessionId } }
   });
 }
 function parseParameters(text) {
@@ -1171,7 +1171,7 @@ function Home({ t, state, busy, instanceId, sessionId, onReload, onOpenJob, onSw
   const moving = subscribed.length > 0 || [...live.values()].some((record) => record.state === "queued");
   const toggle = (0, import_react3.useCallback)(async (job) => {
     const wantFollowed = !followed.has(job.path);
-    const answer = await toggleFavorite(instanceId, job.path, job.name, wantFollowed);
+    const answer = await toggleFavorite(instanceId, job.path, job.name, wantFollowed, sessionId);
     if (isFailure(answer)) {
       setToast(answer.message);
       setTimeout(() => {
@@ -1184,7 +1184,7 @@ function Home({ t, state, busy, instanceId, sessionId, onReload, onOpenJob, onSw
       setToast(void 0);
     }, 2500);
     await loadFavorites();
-  }, [followed, instanceId, loadFavorites, t]);
+  }, [followed, instanceId, loadFavorites, sessionId, t]);
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { style: { display: "flex", flexDirection: "column", height: "100%", minHeight: 0 }, children: [
     /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { style: { padding: "8px 12px", borderBottom: "1px solid var(--dsw-alias-border-l2)" }, children: [
       /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { style: { display: "flex", alignItems: "center", gap: "8px" }, children: [

package/lib/connection.d.ts

@@ -113,13 +113,19 @@ export declare class InstanceRegistry {
      * The whole list is rewritten because the settings file has no update-in-place
      * path; a read-modify-write is safe here because this plugin is the only
      * writer and the call is awaited before the cache advances.
+     *
+     * Re-favoriting a job that is already followed refreshes the recorded name and
+     * session instead of leaving them stale: following a job from another
+     * conversation has to move where its failure wake goes, or the notice would
+     * keep arriving in a session the person has left.
      * @param instanceId - the instance the path belongs to.
      * @param jobPath - the job path to toggle.
      * @param name - display name to record when adding.
      * @param favorited - the desired state.
+     * @param sessionId - session that followed it, when the caller knows one.
      * @returns the instance's favorites after the change.
      */
-    setFavorite(instanceId: string, jobPath: string, name: string, favorited: boolean): Promise<FavoriteJob[]>;
+    setFavorite(instanceId: string, jobPath: string, name: string, favorited: boolean, sessionId?: string): Promise<FavoriteJob[]>;
     /**
      * Persist a new instance list, keeping every other setting.
      *

package/lib/connection.js

@@ -139,18 +139,25 @@ export class InstanceRegistry {
      * The whole list is rewritten because the settings file has no update-in-place
      * path; a read-modify-write is safe here because this plugin is the only
      * writer and the call is awaited before the cache advances.
+     *
+     * Re-favoriting a job that is already followed refreshes the recorded name and
+     * session instead of leaving them stale: following a job from another
+     * conversation has to move where its failure wake goes, or the notice would
+     * keep arriving in a session the person has left.
      * @param instanceId - the instance the path belongs to.
      * @param jobPath - the job path to toggle.
      * @param name - display name to record when adding.
      * @param favorited - the desired state.
+     * @param sessionId - session that followed it, when the caller knows one.
      * @returns the instance's favorites after the change.
      */
-    async setFavorite(instanceId, jobPath, name, favorited) {
+    async setFavorite(instanceId, jobPath, name, favorited, sessionId) {
         const forInstance = await this.favorites(instanceId);
+        const recorded = { ...sessionId === undefined ? {} : { sessionId } };
         const next = favorited
             ? forInstance.some(entry => entry.path === jobPath)
-                ? forInstance
-                : [...forInstance, { path: jobPath, name, addedAt: Date.now() }]
+                ? forInstance.map(entry => (entry.path === jobPath ? { ...entry, name, ...recorded } : entry))
+                : [...forInstance, { path: jobPath, name, addedAt: Date.now(), ...recorded }]
             : forInstance.filter(entry => entry.path !== jobPath);
         await this.storeFavorites(instanceId, next);
         return next;

package/lib/follow.d.ts

@@ -1,5 +1,5 @@
 /**
- * Completion notifications for followed jobs.
+ * Completion notifications for followed jobs, and the failure wake.
  *
  * The operator follows jobs in the panel to hear when they finish, so this is
  * the one place that watches Jenkins on its own initiative. Its rules, in order
@@ -15,6 +15,11 @@
  *   notification the model and the user both see, exactly once (`reported`).
  *   That mechanism resolves the job on the tick it is registered, so the job
  *   exists only to carry the notice.
+ * - **A failure also wakes the session that followed the job.** The wake rides
+ *   the same once-per-build decision, so it cannot arrive twice for one build;
+ *   it goes to the session recorded on the favorite, and it stays silent when
+ *   that session has no live agent (a closed conversation is not an error). The
+ *   log hand-off itself is the same one the panel's button performs.
  * @module dsh-jenkins-plugin/follow
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -34,7 +39,7 @@ export declare class FollowWatcher {
     private timer;
     private running;
     /**
-     * @param ctx - plugin context, used to reach the optional job service.
+     * @param ctx - plugin context, used to reach the optional job and agent services.
      * @param registry - reads the instances, the followed set, and their jobs.
      * @param config - validated plugin configuration.
      */
@@ -42,12 +47,25 @@ export declare class FollowWatcher {
     /**
      * Arm the watcher.
      *
-     * Does nothing when the operator turned completion notices off or when the
-     * composition mounts no job service — both are ordinary compositions, not
-     * errors, and a watcher with nowhere to deliver would only burn requests.
+     * Does nothing when neither channel can deliver anything — notices switched
+     * off, no job service, wake switched off, no agent runtime — because a watcher
+     * that would poll Jenkins and then drop what it found only burns requests.
      * @returns a disposer stopping the watcher.
      */
     start(): () => void;
+    /**
+     * Whether a finished build should become a platform completion notice.
+     * @returns true when the configuration and the composition both allow it.
+     */
+    private wantsNotices;
+    /**
+     * Whether a failed build should wake the session that followed it.
+     *
+     * `allowAnalyze` gates this too: it is the switch that says "build logs may be
+     * sent to a model", and a wake sends the same log tail the panel's button does.
+     * @returns true when the configuration and the composition both allow it.
+     */
+    private wantsWake;
     /**
      * One poll: read every instance's followed jobs and announce what finished.
      *
@@ -59,9 +77,20 @@ export declare class FollowWatcher {
     tick(): Promise<void>;
     /**
      * Read the current build state of every followed job, across every instance.
-     * @returns one row per followed job.
+     * @returns one row per followed job, plus the routing a wake needs.
      */
     private followedStates;
+    /**
+     * Wake the session that followed a failed build.
+     *
+     * Every failure mode here is silent by design: a favorite with no recorded
+     * session, a session with no live agent, a controller that stopped answering.
+     * The build is already recorded as announced, so a wake that could not be
+     * delivered is dropped rather than retried on every tick.
+     * @param notice - the build that failed.
+     * @param followed - this tick's routing.
+     */
+    private wake;
     /**
      * Hand one finished build to the platform's background-job mechanism.
      *

package/lib/follow.js

@@ -1,5 +1,5 @@
 /**
- * Completion notifications for followed jobs.
+ * Completion notifications for followed jobs, and the failure wake.
  *
  * The operator follows jobs in the panel to hear when they finish, so this is
  * the one place that watches Jenkins on its own initiative. Its rules, in order
@@ -15,9 +15,16 @@
  *   notification the model and the user both see, exactly once (`reported`).
  *   That mechanism resolves the job on the tick it is registered, so the job
  *   exists only to carry the notice.
+ * - **A failure also wakes the session that followed the job.** The wake rides
+ *   the same once-per-build decision, so it cannot arrive twice for one build;
+ *   it goes to the session recorded on the favorite, and it stays silent when
+ *   that session has no live agent (a closed conversation is not an error). The
+ *   log hand-off itself is the same one the panel's button performs.
  * @module dsh-jenkins-plugin/follow
  */
-import { NoticeLog, noticeLabel, pendingNotices } from './watch.js';
+import { handOverFailure } from './analyze.js';
+import { followupFor } from './handoff.js';
+import { NoticeLog, jobNoticeKey, noticeLabel, pendingNotices, shouldWake, wakeRoutes } from './watch.js';
 /** The plugin's kind in the platform's job list. */
 const JOB_KIND = 'jenkins';
 /** A build never takes longer than this to be worth waiting for as a job. */
@@ -36,7 +43,7 @@ export class FollowWatcher {
     timer;
     running = false;
     /**
-     * @param ctx - plugin context, used to reach the optional job service.
+     * @param ctx - plugin context, used to reach the optional job and agent services.
      * @param registry - reads the instances, the followed set, and their jobs.
      * @param config - validated plugin configuration.
      */
@@ -48,15 +55,13 @@ export class FollowWatcher {
     /**
      * Arm the watcher.
      *
-     * Does nothing when the operator turned completion notices off or when the
-     * composition mounts no job service — both are ordinary compositions, not
-     * errors, and a watcher with nowhere to deliver would only burn requests.
+     * Does nothing when neither channel can deliver anything — notices switched
+     * off, no job service, wake switched off, no agent runtime — because a watcher
+     * that would poll Jenkins and then drop what it found only burns requests.
      * @returns a disposer stopping the watcher.
      */
     start() {
-        if (!this.config.notifyOnComplete)
-            return () => { };
-        if (this.ctx.get('jobs') === undefined)
+        if (!this.wantsNotices() && !this.wantsWake())
             return () => { };
         this.timer = setInterval(() => { void this.tick(); }, this.config.progressIntervalMs);
         // A first tick runs immediately so a build that finished while the plugin
@@ -68,6 +73,25 @@ export class FollowWatcher {
             this.timer = undefined;
         };
     }
+    /**
+     * Whether a finished build should become a platform completion notice.
+     * @returns true when the configuration and the composition both allow it.
+     */
+    wantsNotices() {
+        return this.config.notifyOnComplete && this.ctx.get('jobs') !== undefined;
+    }
+    /**
+     * Whether a failed build should wake the session that followed it.
+     *
+     * `allowAnalyze` gates this too: it is the switch that says "build logs may be
+     * sent to a model", and a wake sends the same log tail the panel's button does.
+     * @returns true when the configuration and the composition both allow it.
+     */
+    wantsWake() {
+        return this.config.notifyWakeOnFailure
+            && this.config.allowAnalyze
+            && this.ctx.get('agents') !== undefined;
+    }
     /**
      * One poll: read every instance's followed jobs and announce what finished.
      *
@@ -81,15 +105,20 @@ export class FollowWatcher {
             return;
         this.running = true;
         try {
-            const jobs = await this.followedStates();
-            if (jobs.length === 0)
+            const followed = await this.followedStates();
+            if (followed.jobs.length === 0)
                 return;
-            for (const notice of pendingNotices(jobs, this.announced.snapshot())) {
+            for (const notice of pendingNotices(followed.jobs, this.announced.snapshot())) {
                 // Recorded before delivery: the record must not depend on a delivery
                 // succeeding, or a throwing job service would announce the same build
                 // again on the next tick.
                 this.announced.add(notice.key);
-                this.deliver(noticeLabel(notice));
+                if (this.wantsNotices())
+                    this.deliver(noticeLabel(notice));
+                // The wake rides the same decision, so one build can never wake twice —
+                // not even when the completion notice could not be delivered.
+                if (this.wantsWake() && shouldWake(notice.outcome))
+                    await this.wake(notice, followed);
             }
         }
         catch {
@@ -103,11 +132,13 @@ export class FollowWatcher {
     }
     /**
      * Read the current build state of every followed job, across every instance.
-     * @returns one row per followed job.
+     * @returns one row per followed job, plus the routing a wake needs.
      */
     async followedStates() {
         const { instances } = await this.registry.list();
-        const out = [];
+        const jobs = [];
+        const sessions = new Map();
+        const sources = new Map();
         for (const instance of instances) {
             const favorites = await this.registry.favorites(instance.id);
             if (favorites.length === 0)
@@ -115,21 +146,59 @@ export class FollowWatcher {
             // One listing per instance answers every followed job on it, which is the
             // bound that keeps this cheap on a large controller.
             const resolved = await this.registry.require(instance.id);
-            const jobs = await resolved.client.listJobs();
-            const byPath = new Map(jobs.map(job => [job.path, job]));
+            const jobsOnInstance = await resolved.client.listJobs();
+            const byPath = new Map(jobsOnInstance.map(job => [job.path, job]));
             for (const favorite of favorites) {
+                for (const [route, sessionId] of wakeRoutes(instance.id, [favorite]))
+                    sessions.set(route, sessionId);
                 const job = byPath.get(favorite.path);
                 if (job === undefined)
                     continue;
+                sources.set(instance.id, { client: resolved.client, instanceName: resolved.instance.name });
                 const build = job.lastBuild;
-                out.push({
+                jobs.push({
                     instanceId: instance.id,
                     jobPath: favorite.path,
                     ...build === undefined ? {} : { buildNumber: build.number, outcome: build.outcome, building: build.building },
                 });
             }
         }
-        return out;
+        return { jobs, sessions, sources };
+    }
+    /**
+     * Wake the session that followed a failed build.
+     *
+     * Every failure mode here is silent by design: a favorite with no recorded
+     * session, a session with no live agent, a controller that stopped answering.
+     * The build is already recorded as announced, so a wake that could not be
+     * delivered is dropped rather than retried on every tick.
+     * @param notice - the build that failed.
+     * @param followed - this tick's routing.
+     */
+    async wake(notice, followed) {
+        const sessionId = followed.sessions.get(jobNoticeKey(notice.instanceId, notice.jobPath));
+        if (sessionId === undefined)
+            return;
+        const source = followed.sources.get(notice.instanceId);
+        if (source === undefined)
+            return;
+        const sink = followupFor(this.ctx, sessionId);
+        if (sink.kind !== 'ok')
+            return;
+        try {
+            await handOverFailure({
+                client: source.client,
+                jobPath: notice.jobPath,
+                buildNumber: notice.buildNumber,
+                logBytes: this.config.analyzeLogBytes,
+                instanceName: source.instanceName,
+                followup: sink.followup,
+            });
+        }
+        catch {
+            // A build that failed to hand over stays announced: the alternative is a
+            // wake attempt against a broken controller on every single tick.
+        }
     }
     /**
      * Hand one finished build to the platform's background-job mechanism.

package/lib/handoff.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Delivering a plugin-authored message into a session.
+ *
+ * Two callers want the same thing: the panel's "hand it to the AI" route, where
+ * a person clicked, and the failure watcher, which wakes the session that
+ * followed the job. Both need "reach this session's live agent, or say precisely
+ * why not", so the lookup and the message construction live here rather than
+ * being written twice — a hand-rolled message shape is exactly the kind of thing
+ * that drifts from what the platform actually accepts.
+ *
+ * The three outcomes are distinct on purpose: a composition without an agent
+ * runtime is a different situation from a session whose agent has gone away, and
+ * the route answers them with different statuses.
+ * @module dsh-jenkins-plugin/handoff
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Declare this plugin's own message provenance kind.
+ *
+ * The harness has no shared catch-all `plugin` source kind: each producer
+ * declares its own `kind` in its own module, and consumers fall through kinds
+ * they do not know. Declaring one keeps the conversation able to tell a
+ * Jenkins-plugin message apart from something the operator typed, without
+ * pretending to be `user`.
+ */
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A message the Jenkins plugin authored for a conversation it was asked to wake. */
+        'jenkins-plugin': {
+            kind: 'jenkins-plugin';
+        };
+    }
+}
+/** The part of one agent this plugin uses. */
+export interface AgentLike {
+    /** Queue a message in this agent's conversation. */
+    followup(message: unknown): void;
+}
+/**
+ * The agent runtime, as seen through `ctx.get('agents')`.
+ *
+ * Declared structurally rather than imported so a composition that mounts no
+ * agent runtime still loads this plugin: the lookup then reports `no-service`.
+ */
+export interface AgentService {
+    /**
+     * The live agent for a session.
+     * @param sessionId - durable session identity.
+     * @returns the agent, or undefined when that session has none.
+     */
+    get(sessionId: string): AgentLike | undefined;
+}
+/** Whether a session can be reached, and how. */
+export type FollowupLookup = {
+    kind: 'ok';
+    followup: (prompt: string) => void;
+} | {
+    kind: 'no-service';
+} | {
+    kind: 'no-session';
+};
+/**
+ * Resolve the message sink for one session.
+ *
+ * A missing session is not an error: a favorite may have been added in a
+ * conversation that has since been closed, and waking nothing is the correct
+ * answer there.
+ * @param ctx - plugin context, read for the optional agent runtime.
+ * @param sessionId - the session to deliver into.
+ * @returns the sink, or which half of the chain is missing.
+ */
+export declare function followupFor(ctx: Context, sessionId: string): FollowupLookup;

package/lib/handoff.js

@@ -0,0 +1,45 @@
+/**
+ * Delivering a plugin-authored message into a session.
+ *
+ * Two callers want the same thing: the panel's "hand it to the AI" route, where
+ * a person clicked, and the failure watcher, which wakes the session that
+ * followed the job. Both need "reach this session's live agent, or say precisely
+ * why not", so the lookup and the message construction live here rather than
+ * being written twice — a hand-rolled message shape is exactly the kind of thing
+ * that drifts from what the platform actually accepts.
+ *
+ * The three outcomes are distinct on purpose: a composition without an agent
+ * runtime is a different situation from a session whose agent has gone away, and
+ * the route answers them with different statuses.
+ * @module dsh-jenkins-plugin/handoff
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/**
+ * Resolve the message sink for one session.
+ *
+ * A missing session is not an error: a favorite may have been added in a
+ * conversation that has since been closed, and waking nothing is the correct
+ * answer there.
+ * @param ctx - plugin context, read for the optional agent runtime.
+ * @param sessionId - the session to deliver into.
+ * @returns the sink, or which half of the chain is missing.
+ */
+export function followupFor(ctx, sessionId) {
+    const agents = ctx.get('agents');
+    if (agents === undefined)
+        return { kind: 'no-service' };
+    const agent = agents.get(sessionId);
+    if (agent === undefined)
+        return { kind: 'no-session' };
+    return {
+        kind: 'ok',
+        followup: (prompt) => {
+            agent.followup(createUserMessage({
+                content: [{ type: 'text', text: prompt }],
+                // Tagged as this plugin's own message, so the conversation shows where
+                // it came from and the model can tell it apart from the operator.
+                source: { kind: 'jenkins-plugin' },
+            }));
+        },
+    };
+}

package/lib/routes.js

@@ -18,10 +18,10 @@
  * - `POST /jenkins-plugin/analyze`   — hand a failed build to the model.
  * @module dsh-jenkins-plugin/routes
  */
-import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import { analysisKey, handOverFailure } from './analyze.js';
 import { InstanceUnavailable } from './connection.js';
+import { followupFor } from './handoff.js';
 import { JenkinsClient, JenkinsError } from './jenkins/client.js';
 import { buildProgress } from './jenkins/types.js';
 import { checkWritePolicy } from './policy.js';
@@ -257,7 +257,15 @@ export function registerJenkinsRoutes(ctx, registry, config, tracker) {
     const selected = new Map();
     /** Reject an untrusted caller; true when the response is already written. */
     const rejected = (req, res) => {
-        const rejection = trustOf(ctx)?.requestRejection(req);
+        const trust = trustOf(ctx);
+        // No trust service means no browser can be authenticated at all, so the
+        // route is closed rather than open: these handlers serve controller data and
+        // perform controller writes, and a composition that mounted them without the
+        // fence must not hand either to whoever can reach the port. Reading the
+        // service through `ctx.get` returns `undefined` rather than throwing, which
+        // is exactly why the door has to be closed here instead of being assumed
+        // shut by the lookup.
+        const rejection = trust === undefined ? 401 : trust.requestRejection(req);
         if (rejection === undefined)
             return false;
         res.statusCode = rejection;
@@ -632,6 +640,11 @@ export function registerJenkinsRoutes(ctx, registry, config, tracker) {
                     ? record.name.trim()
                     : jobPath.split('/').at(-1) ?? jobPath;
                 const instanceId = typeof record.instance === 'string' ? record.instance : undefined;
+                // Recorded so a failure of this job can wake the conversation it was
+                // followed from; the panel sends the session it is rendering.
+                const sessionId = typeof record.session === 'string' && record.session.trim().length > 0
+                    ? record.session.trim()
+                    : undefined;
                 const resolved = await registry.require(instanceId);
                 // Verified before it is stored: favoriting a path that does not exist
                 // would produce a card that can never resolve.
@@ -646,7 +659,7 @@ export function registerJenkinsRoutes(ctx, registry, config, tracker) {
                         return;
                     }
                 }
-                const favorites = await registry.setFavorite(resolved.instance.id, jobPath, name, favorited);
+                const favorites = await registry.setFavorite(resolved.instance.id, jobPath, name, favorited, sessionId);
                 sendJson(res, { ok: true, instanceId: resolved.instance.id, favorites });
             }
             catch (error) {
@@ -787,8 +800,8 @@ export function registerJenkinsRoutes(ctx, registry, config, tracker) {
                     }, 403);
                     return;
                 }
-                const agents = ctx.get('agents');
-                if (agents === undefined) {
+                const sink = followupFor(ctx, sessionId);
+                if (sink.kind === 'no-service') {
                     sendJson(res, {
                         ok: false,
                         code: 'unavailable',
@@ -796,8 +809,7 @@ export function registerJenkinsRoutes(ctx, registry, config, tracker) {
                     }, 503);
                     return;
                 }
-                const agent = agents.get(sessionId);
-                if (agent === undefined) {
+                if (sink.kind === 'no-session') {
                     sendJson(res, {
                         ok: false,
                         code: 'no-session',
@@ -826,15 +838,10 @@ export function registerJenkinsRoutes(ctx, registry, config, tracker) {
                         buildNumber,
                         logBytes: config.analyzeLogBytes,
                         instanceName: resolved.instance.name,
-                        // The message factory lives here rather than in the hand-off, so the
-                        // hand-off stays a pure decision about *what* to say and this stays
-                        // the plumbing that says it in this composition's session.
-                        followup: (prompt) => {
-                            agent.followup(createUserMessage({
-                                content: [{ type: 'text', text: prompt }],
-                                source: { kind: 'plugin', plugin: 'jenkins-plugin' },
-                            }));
-                        },
+                        // The hand-off stays a pure decision about *what* to say; the sink
+                        // that says it in this composition's session is `handoff.ts`, shared
+                        // with the failure watcher.
+                        followup: sink.followup,
                     });
                     sendJson(res, {
                         ok: true,

package/lib/settings.d.ts

@@ -41,6 +41,16 @@ export interface FavoriteJob {
     name: string;
     /** When it was favorited, epoch milliseconds. */
     addedAt: number;
+    /**
+     * Session that followed this job, when the panel knew one.
+     *
+     * This is what makes a failure wake go to the right conversation: the person
+     * who followed the job is the person who wants to hear that it broke, and the
+     * watcher is unowned background work that cannot infer that from anywhere else.
+     * Favorites stored before this field existed have none, and those stay silent
+     * rather than guessing an owner.
+     */
+    sessionId?: string;
 }
 /** The whole persisted configuration. */
 export interface JenkinsSettings {

package/lib/settings.js

@@ -87,7 +87,8 @@ function parseFavorite(value) {
     const addedAt = typeof value.addedAt === 'number'
         ? value.addedAt
         : 0;
-    return { path, name, addedAt };
+    const sessionId = stringField(value, 'sessionId');
+    return { path, name, addedAt, ...sessionId === undefined ? {} : { sessionId } };
 }
 /**
  * Read the favorites map, dropping anything unusable.

package/lib/watch.d.ts

@@ -46,6 +46,46 @@ export interface BuildNotice {
  * @returns the announcement key.
  */
 export declare function noticeKey(instanceId: string, jobPath: string, buildNumber: number): string;
+/**
+ * The part of a notice key that names the job rather than the build.
+ *
+ * Routing a failure wake needs "which session followed this job", while a notice
+ * names one build. Both sides derive their key from this function so the pair
+ * cannot drift apart — a hand-written `${instanceId}/${jobPath}` in one place and
+ * `noticeKey` in the other is a silent mismatch that only shows up as a wake that
+ * never arrives.
+ * @param instanceId - instance id.
+ * @param jobPath - job path.
+ * @returns the job's route key.
+ */
+export declare function jobNoticeKey(instanceId: string, jobPath: string): string;
+/**
+ * Whether a finished build should wake the session that followed it.
+ *
+ * Only a real failure wakes anyone. `unstable` is a build that finished with
+ * warnings and `aborted` is usually the operator's own doing, so waking a model
+ * for either would spend a turn on news the person already has.
+ * @param outcome - terminal outcome.
+ * @returns true when the outcome deserves a wake.
+ */
+export declare function shouldWake(outcome: string): boolean;
+/** One followed job, as the wake routing needs to see it. */
+export interface WakeFavorite {
+    /** Job path. */
+    path: string;
+    /** Session that followed it, when the favorite recorded one. */
+    sessionId?: string;
+}
+/**
+ * Map followed jobs to the session that should hear about their failures.
+ *
+ * Favorites added before this feature existed carry no session id and are simply
+ * absent from the map: guessing an owner would be worse than staying quiet.
+ * @param instanceId - the instance every favorite belongs to.
+ * @param favorites - that instance's favorites.
+ * @returns route key to session id.
+ */
+export declare function wakeRoutes(instanceId: string, favorites: readonly WakeFavorite[]): Map<string, string>;
 /**
  * Whether a build outcome is terminal.
  * @param outcome - the outcome to test.

package/lib/watch.js

@@ -24,6 +24,51 @@ const TERMINAL = new Set(['success', 'failure', 'unstable', 'aborted', 'not-buil
 export function noticeKey(instanceId, jobPath, buildNumber) {
     return `${instanceId}/${jobPath}#${buildNumber}`;
 }
+/**
+ * The part of a notice key that names the job rather than the build.
+ *
+ * Routing a failure wake needs "which session followed this job", while a notice
+ * names one build. Both sides derive their key from this function so the pair
+ * cannot drift apart — a hand-written `${instanceId}/${jobPath}` in one place and
+ * `noticeKey` in the other is a silent mismatch that only shows up as a wake that
+ * never arrives.
+ * @param instanceId - instance id.
+ * @param jobPath - job path.
+ * @returns the job's route key.
+ */
+export function jobNoticeKey(instanceId, jobPath) {
+    return `${instanceId}/${jobPath}`;
+}
+/**
+ * Whether a finished build should wake the session that followed it.
+ *
+ * Only a real failure wakes anyone. `unstable` is a build that finished with
+ * warnings and `aborted` is usually the operator's own doing, so waking a model
+ * for either would spend a turn on news the person already has.
+ * @param outcome - terminal outcome.
+ * @returns true when the outcome deserves a wake.
+ */
+export function shouldWake(outcome) {
+    return outcome === 'failure';
+}
+/**
+ * Map followed jobs to the session that should hear about their failures.
+ *
+ * Favorites added before this feature existed carry no session id and are simply
+ * absent from the map: guessing an owner would be worse than staying quiet.
+ * @param instanceId - the instance every favorite belongs to.
+ * @param favorites - that instance's favorites.
+ * @returns route key to session id.
+ */
+export function wakeRoutes(instanceId, favorites) {
+    const routes = new Map();
+    for (const favorite of favorites) {
+        if (favorite.sessionId === undefined || favorite.sessionId.length === 0)
+            continue;
+        routes.set(jobNoticeKey(instanceId, favorite.path), favorite.sessionId);
+    }
+    return routes;
+}
 /**
  * Whether a build outcome is terminal.
  * @param outcome - the outcome to test.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-jenkins-plugin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Jenkins integration for DeepSeek Harness: a live build-progress panel in the Web GUI plus model-facing tools for triggering builds, reading stages and console logs, and browsing a build's workspace",
   "keywords": [
     "dsh",
@@ -62,7 +62,7 @@
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": "0.1.6-alpha.2"
+    "dsh": ">=0.2.1-rc.3 <0.3.0-0"
   },
   "publishConfig": {
     "access": "public"
@@ -75,34 +75,35 @@
     "check:secrets": "node scripts/check-secrets.mjs",
     "check:payload": "node scripts/check-payload.mjs",
     "check": "npm test && npm run build && npm run check:secrets && npm run check:payload",
+    "release:check": "node scripts/release-check.mjs",
     "prepare": "npm run build"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-credentials": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-credentials": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-dockkit": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-layout": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-credentials": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-dockkit": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-session": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
     "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "clsx": "^2.1.1",