claude-code-session-manager 0.38.0 → 0.38.2

package/plugins/session-manager-dev/skills/blog-for-project-feature/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: blog-for-project-feature
+description: Produce a self-contained, interactive HTML "feature showcase" for one project + one feature — Project Mission & Description, Feature Description (with an optional generated companion illustration), and a Click-Through Demo built from REAL screenshots (never mockups) — one aspect revealed at a time. Output is a single portable HTML file uploadable anywhere (no server, no build step). Distinct from blog-from-git (which drafts narrative bilko.run changelog posts from git history) — this is an evergreen, per-feature product page, not a dated post. Orchestrates 8 nested sub-skills (blog-for-project-feature:select, :research, :storyboard, :capture, :draft-copy, :illustrate, :compose, :review) so each step is independently invokable and inspectable. Use for "make a feature page for X", "showcase this feature", "/blog-for-project-feature", "interactive demo of X", or turning a shipped feature in Session Manager / Social Signal Builder (or any project) into something you can hand someone a link to.
+---
+
+# blog-for-project-feature (orchestrator)
+
+Project-agnostic. Runs against whatever project the current working directory (or a named
+project path) points to — built first for **Session Manager** and **Social Signal Builder**,
+but nothing here is hardcoded to either.
+
+**Not `blog-from-git`.** That skill drafts a dated, narrative bilko.run post from git activity
+("here's what shipped this week"). This skill produces an **evergreen, single-feature product
+page** — no date, no changelog framing, not tied to a publishing cadence. One project, one
+feature, three things: what the project is for, what this feature does, and a real click-through
+demo of it working. The two skills never share output or ledger state.
+
+**`feature.config.yaml` in this folder is the grounding authority** for output conventions
+(where the HTML lands, image size/compression limits, single-file-vs-folder default, theme
+tokens). Read it first, before any sub-skill file. If prose here ever disagrees with the config,
+the config wins.
+
+## Pipeline DAG
+
+```
+project (+ optional feature name)
+              │
+              ▼
+┌───────────────────────────────┐
+│ 0. blog-for-project-feature:select │──▶ one confirmed project + one confirmed feature
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 1. :research                       │──▶ mission, feature description, key files/entry points
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 2. :storyboard                     │──▶ ordered demo steps (action, expected screen, caption)
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 3. :capture                        │──▶ real screenshots per step (+ storyboard corrections)
+└───────────────────────────────┘        │ no real screenshot obtainable for a step
+              │ all steps captured        ▼
+              ▼                    STOP — report which step blocked, don't fabricate
+┌───────────────────────────────┐
+│ 4. :draft-copy                     │──▶ FINAL mission/feature text + one-sentence "essence" line
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 5. :illustrate                     │──▶ one companion illustration from the essence line
+└───────────────────────────────┘        (or a clean "omitted" note — never blocks the pipeline)
+              │
+              ▼
+┌───────────────────────────────┐
+│ 6. :compose                        │──▶ one self-contained interactive HTML file
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 7. :review                         │──── fails a check ────┐
+└───────────────────────────────┘                            │
+              │ passes                                        │
+              ▼                                                │
+     report path, wait for explicit                            │
+     "publish/upload" instruction          loop back to :compose / :capture / :illustrate
+```
+
+| Step | Input | Output | On failure |
+|---|---|---|---|
+| 0. `:select` | project (cwd or named) + optional feature hint | one confirmed project + one confirmed feature name + why it's demo-worthy | **STOP** — report if no clear feature can be confirmed (don't guess) |
+| 1. `:research` | confirmed project + feature | mission/description (project-level), feature description, key files, how it actually works | n/a — always produces notes, flags gaps explicitly rather than inventing claims |
+| 2. `:storyboard` | mission + feature notes | ordered list of `{step, action, expected_screen, caption}` — one aspect per step | n/a — storyboard is a draft, `:capture` is allowed to correct it |
+| 3. `:capture` | storyboard | one real screenshot file per step + any corrected captions | **STOP** on that step — report what's missing; never substitute a placeholder/mockup image |
+| 4. `:draft-copy` | research notes + captured captions | final Mission & Feature Description prose + one-sentence essence line | n/a — always produces final text, gaps stay explicit |
+| 5. `:illustrate` | the essence line (text must exist first) | one companion illustration, tagged distinct from screenshots — or an explicit omission note | never blocks — skips cleanly if no image generator is configured, or after one off-brief retry |
+| 6. `:compose` | final copy + captured steps + optional illustration | one self-contained HTML file (or html+images folder per config) | loop back to `:capture` if a required image is missing, else fix and retry |
+| 7. `:review` | the composed HTML | pass/fail against the gate below | loop back to `:compose` (content), `:capture` (screenshot), or `:illustrate` (mislabeled companion image) — never ship on a failed gate |
+
+## Golden rule: screenshots are real or the step doesn't exist
+
+This skill exists specifically because "feature demo" content is worthless if the images are
+invented, stale, or from the wrong build. `:capture` uses `mcp__playwright__*` (or the project's
+own screenshot tooling if `run`/a project skill already drives it — check for one first) against
+a running instance of the actual project. If a step can't be captured for real (app won't start,
+feature is behind auth you don't have, flow requires data that doesn't exist locally), **that
+step is dropped and reported, not faked.** A shorter, honest demo beats a complete, fabricated one.
+
+## Output
+
+Default: one self-contained `.html` file (inline CSS/JS, base64-embedded images) written to
+`docs/feature-showcase/<feature-slug>.html` inside the target project — see
+`feature.config.yaml` for the exact path convention, size ceiling, and the single-file vs.
+folder fallback (used when embedded images would blow past the size ceiling). This is what
+"uploadable anywhere" means: no server, no relative asset paths, no build step — open the file
+or drop it on any static host and it works.
+
+**Only push, deploy, or upload when explicitly asked.** Report the local path and a one-line
+description of what the page shows, and wait — same convention as `blog-from-git`'s seed gate
+and `issue-address`'s "only push when asked" rule.
+
+## Why nested skills instead of one inline pass
+
+Same reasoning as `issue-address` and `pr-review-sweep`: each phase is a real, independently
+invokable `SKILL.md` so progress is visible step by step ("storyboard produced 5 steps, capture
+got 4 real screenshots, 1 dropped") instead of one opaque generation pass, and a single phase
+(e.g. swapping the screenshot tool, changing the HTML theme) can be edited without touching the
+others. If a step is still doing too much once this ships, decompose it further the same way
+`issue-address:select` was (nested sub-DAG) — continuously, wherever one file covers too much to
+inspect as one unit.
+
+## Folder map
+
+```
+blog-for-project-feature/
+  feature.config.yaml ← output path convention, size ceiling, theme tokens — read first
+  SKILL.md             ← this file: pipeline, DAG, output contract
+  0-select/SKILL.md
+  1-research/SKILL.md
+  2-storyboard/SKILL.md
+  3-capture/SKILL.md
+  4-draft-copy/SKILL.md
+  5-illustrate/SKILL.md
+  6-compose/SKILL.md
+  7-review/SKILL.md
+```
+
+## What this skill is not
+
+- Not `blog-from-git` — no dated post, no rotation ledger, no git-diff scan. This is
+  feature-scoped and evergreen; that skill is time-scoped and narrative.
+- Not a marketing copy generator — every claim in `:research`'s output must trace to real code,
+  docs, or a live screenshot, same evidentiary bar as `blog-from-git`'s `ground.md`.
+- Not a full site generator — one feature, one page, per run. A project with N features worth
+  showcasing gets N runs (and, if wanted later, a separate index/landing skill — not built yet,
+  don't invent one inline).

package/plugins/session-manager-dev/skills/blog-for-project-feature/feature.config.yaml

@@ -0,0 +1,74 @@
+# Grounding authority for blog-for-project-feature. Read this before any sub-skill file.
+# If prose in a SKILL.md ever disagrees with this file, this file wins.
+
+output:
+  # Path is relative to the TARGET project's repo root (the project being showcased),
+  # not this plugin's own repo.
+  path_template: "docs/feature-showcase/{feature-slug}.html"
+  feature_slug_rule: "kebab-case, derived from the confirmed feature name in :select"
+  # Prefer one self-contained file. Only fall back to a folder when the size ceiling
+  # below would be exceeded by inlining images.
+  default_mode: single_file          # single_file | folder
+  folder_fallback_layout:
+    html: "docs/feature-showcase/{feature-slug}/index.html"
+    images: "docs/feature-showcase/{feature-slug}/screenshots/"
+  single_file_size_ceiling_mb: 8       # switch to folder_fallback_layout above this
+  never_upload_or_deploy_without_explicit_ask: true
+
+images:
+  format: png
+  max_width_px: 1600                  # downscale before embedding; demo clarity, not pixel-perfect
+  compression: "reasonable lossy ok for PNG->WebP if it keeps text legible; never so lossy captions become unreadable"
+  source_of_truth: "mcp__playwright__browser_take_screenshot against a real running instance"
+  placeholder_or_mockup_images: forbidden   # a dropped step beats a fabricated one
+
+illustration:
+  # The ONE companion image, generated by :illustrate — a distinct image class from the
+  # click-through screenshots above. Optional: omitted cleanly if no generator is configured.
+  runs_after: draft-copy               # never generate from anything but finalized copy
+  generator: "project-local generator if the target project has one, else Gemini
+    (gemini-2.5-flash-image via google-genai — same provider/pattern as Burrow's
+    app/shared/image_gen.py) using GEMINI_API_KEY / GOOGLE_API_KEY from the environment"
+  count: 1
+  placement: "Feature Description section header only — never inside the Click-Through Demo"
+  format: png
+  max_width_px: 1200
+  style: "conceptual/editorial illustration — mood/palette should follow the project's own
+    theme tokens above if it has brand colors, otherwise a clean flat/geometric style"
+  must_not_resemble: "a UI mockup, screenshot, or contain invented interface text/window chrome
+    — must be visually distinguishable from a real captured screen at a glance"
+  max_regeneration_attempts: 1
+  on_no_generator_available: "skip silently, no page-visible note, report to the operator only"
+
+content:
+  sections_required:
+    - "Project Mission & Description"   # 2-4 sentences, from :research, project-level not feature-level
+    - "Feature Description"             # what it does, why it matters, 1-2 short paragraphs
+    - "Click-Through Demo"              # the storyboard steps, one aspect revealed at a time
+  demo_interaction: "one-step-at-a-time reveal (next/prev controls or numbered tabs) — never a single long scroll dump of every screenshot at once"
+  tone: "same plain, non-salesy, show-don't-tell bar as blog-from-git/voice.md bot-tell blocklist — no 'excited to share', no grand-implication filler"
+  caption_rule: "every screenshot has a one-sentence caption naming what changed on screen, not what the code does internally"
+
+theme:
+  # Minimal neutral tokens so every showcase looks consistent without importing a design system.
+  # Swap these per-project only if the project has its own documented brand tokens.
+  font_stack: "system-ui, -apple-system, 'Segoe UI', sans-serif"
+  bg: "#0b0d10"
+  surface: "#15181d"
+  text: "#e8eaed"
+  text_muted: "#9aa0a6"
+  accent: "#5b9dff"
+  radius_px: 10
+  max_width_px: 900
+
+gates:
+  # Checked in step 7 (:review). All must pass before reporting the page ready.
+  - "every image referenced actually loads (no broken src, no 404 in a local file:// open)"
+  - "zero placeholder/mockup images — every screenshot traces to a real :capture run"
+  - "if present, the companion illustration sits only in the Feature Description header and is
+    visually distinguishable from a real screenshot (no UI chrome/invented interface text)"
+  - "all three required sections present and non-empty (illustration is optional, never gates)"
+  - "demo is click-through (has working next/prev or tab controls), not a flat scroll"
+  - "file opens correctly via file:// with no console errors (network calls, external CDN fonts/JS forbidden — must be fully offline-capable)"
+  - "single_file_size_ceiling_mb respected, or folder fallback used instead"
+  - "no invented claims — every sentence in Mission/Feature sections traces to :research notes"

package/src/main/__tests__/classifyPromptTicket.test.cjs

@@ -0,0 +1,101 @@
+/**
+ * classifyPromptTicket.test.cjs — unit tests for the PromptTicket
+ * inline-vs-develop classifier (PRD 749).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/classifyPromptTicket.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach } from 'vitest';
+const { EventEmitter } = require('node:events');
+const {
+  classifyPromptTicket,
+  parseVerdict,
+  __setSpawnForTest,
+} = require('../lib/classifyPromptTicket.cjs');
+
+beforeEach(() => {
+  __setSpawnForTest(null); // restore real spawn between tests
+});
+
+test('parseVerdict returns "develop" only when the raw text contains the word develop', () => {
+  expect(parseVerdict('develop')).toBe('develop');
+  expect(parseVerdict('  Develop  ')).toBe('develop');
+  expect(parseVerdict('inline')).toBe('inline');
+  expect(parseVerdict('')).toBe('inline');
+  expect(parseVerdict(undefined)).toBe('inline');
+});
+
+function fakeChild() {
+  const child = new EventEmitter();
+  child.stdout = new EventEmitter();
+  child.stderr = new EventEmitter();
+  child.kill = () => {};
+  return child;
+}
+
+test('classifyPromptTicket resolves "develop" for a complex sample prompt (stubbed spawn)', async () => {
+  __setSpawnForTest(() => {
+    const child = fakeChild();
+    setTimeout(() => {
+      child.stdout.emit('data', Buffer.from('develop'));
+      child.emit('close', 0);
+    }, 0);
+    return child;
+  });
+
+  const verdict = await classifyPromptTicket('Build a full multi-tab prompt-queue feature with PRD decomposition');
+  expect(verdict).toBe('develop');
+});
+
+test('classifyPromptTicket resolves "inline" for a quick sample prompt (stubbed spawn)', async () => {
+  __setSpawnForTest(() => {
+    const child = fakeChild();
+    setTimeout(() => {
+      child.stdout.emit('data', Buffer.from('inline'));
+      child.emit('close', 0);
+    }, 0);
+    return child;
+  });
+
+  const verdict = await classifyPromptTicket('what time is it');
+  expect(verdict).toBe('inline');
+});
+
+test('classifyPromptTicket fails safe to "inline" when the child process errors', async () => {
+  __setSpawnForTest(() => {
+    const child = fakeChild();
+    setTimeout(() => child.emit('error', new Error('spawn failed')), 0);
+    return child;
+  });
+
+  const verdict = await classifyPromptTicket('anything');
+  expect(verdict).toBe('inline');
+});
+
+test('classifyPromptTicket spawns with a pinned model, argv array (no shell string), and closed stdin', async () => {
+  let capturedBin;
+  let capturedArgs;
+  let capturedOpts;
+  __setSpawnForTest((bin, args, opts) => {
+    capturedBin = bin;
+    capturedArgs = args;
+    capturedOpts = opts;
+    const child = fakeChild();
+    setTimeout(() => {
+      child.stdout.emit('data', Buffer.from('inline'));
+      child.emit('close', 0);
+    }, 0);
+    return child;
+  });
+
+  await classifyPromptTicket('hello');
+
+  expect(typeof capturedBin).toBe('string');
+  expect(Array.isArray(capturedArgs)).toBe(true);
+  expect(capturedArgs).toContain('--model');
+  expect(capturedArgs[capturedArgs.indexOf('--model') + 1]).toBe('sonnet');
+  expect(capturedOpts.stdio[0]).toBe('ignore');
+  expect(capturedOpts.shell).toBeFalsy();
+});

package/src/main/__tests__/exchangesPromptId.test.cjs

@@ -0,0 +1,70 @@
+/**
+ * exchangesPromptId.test.cjs — recordExchange() round-trips the optional
+ * promptId field (PRD 749). Separate file from exchanges.test.cjs (which
+ * runs under node:test, not vitest) so this is picked up by
+ * `npx vitest run` per this repo's test:unit convention.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/exchangesPromptId.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+let tmpHome;
+let origHome;
+
+beforeAll(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'exchanges-promptid-test-'));
+  origHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+});
+
+afterAll(async () => {
+  process.env.HOME = origHome;
+  await fsp.rm(tmpHome, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  // Stub summarize.cjs to avoid any network calls, and clear the modules
+  // that cache HOME-derived paths so each test sees the tmp HOME.
+  const summarizePath = require.resolve('../lib/summarize.cjs');
+  delete require.cache[summarizePath];
+  require.cache[summarizePath] = {
+    id: summarizePath,
+    filename: summarizePath,
+    loaded: true,
+    exports: { summarize: async () => ({ summary: 'ok', model: 'claude-haiku-4-5' }) },
+  };
+  delete require.cache[require.resolve('../exchanges.cjs')];
+  delete require.cache[require.resolve('../config.cjs')];
+  delete require.cache[require.resolve('../lib/encodeCwd.cjs')];
+});
+
+test('recordExchange persists promptId when supplied', async () => {
+  const { recordExchange } = require('../exchanges.cjs');
+  const { encodeCwd } = require('../lib/encodeCwd.cjs');
+
+  const cwd = '/home/user/promptid-project';
+  await recordExchange({ sessionId: 's1', cwd, prompt: 'do X', result: 'done', promptId: 'ticket-abc-123' });
+
+  const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encodeCwd(cwd)}.jsonl`);
+  const record = JSON.parse((await fsp.readFile(logPath, 'utf8')).trim());
+  expect(record.promptId).toBe('ticket-abc-123');
+});
+
+test('recordExchange omits promptId when not supplied (no backfill/synthesis)', async () => {
+  const { recordExchange } = require('../exchanges.cjs');
+  const { encodeCwd } = require('../lib/encodeCwd.cjs');
+
+  const cwd = '/home/user/no-promptid-project';
+  await recordExchange({ sessionId: 's2', cwd, prompt: 'do Y', result: 'done' });
+
+  const logPath = path.join(tmpHome, '.claude', 'knowledge-log', 'exchanges', `${encodeCwd(cwd)}.jsonl`);
+  const record = JSON.parse((await fsp.readFile(logPath, 'utf8')).trim());
+  expect('promptId' in record).toBe(false);
+});

package/src/main/__tests__/prdCreate.test.cjs

@@ -85,6 +85,23 @@ test('buildPrdBody omits parallelGroup frontmatter key when not supplied', () =>
   expect(!/parallelGroup:/.test(body)).toBeTruthy();
 });
 
+test('buildPrdBody writes sourcePromptId into frontmatter when supplied (PRD 749 traceability)', () => {
+  const body = buildPrdBody({
+    title: 't', cwd: '~/x', estimateMinutes: 5, goal: 'g',
+    acceptanceCriteria: ['a'], implementationNotes: 'n',
+    sourcePromptId: 'ticket-abc-123',
+  });
+  expect(body).toMatch(/sourcePromptId: ticket-abc-123/);
+});
+
+test('buildPrdBody omits sourcePromptId frontmatter key when not supplied', () => {
+  const body = buildPrdBody({
+    title: 't', cwd: '~/x', estimateMinutes: 5, goal: 'g',
+    acceptanceCriteria: ['a'], implementationNotes: 'n',
+  });
+  expect(!/sourcePromptId:/.test(body)).toBeTruthy();
+});
+
 test('readStandards result is byte-identical to the on-disk file (single source of truth)', async () => {
   const onDisk = fs.readFileSync(
     path.join(__dirname, '..', '..', '..', 'plugins', 'session-manager-dev', 'skills', 'develop', 'standards.md'),
@@ -320,3 +337,20 @@ test('POST /admin/scheduler/create-prd honors an explicit slug + parallelGroup i
     await admin.stop();
   }
 });
+
+test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the created PRD frontmatter', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+  const { admin, port, token } = await startWithRemote(remote);
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/create-prd', token,
+      body: validCreateBody({ slug: 'from-a-ticket', parallelGroup: 888, sourcePromptId: 'ticket-xyz-789' }),
+    });
+    expect(res.status).toBe(200);
+    const written = fs.readFileSync(path.join(prdsDir, '888-from-a-ticket.md'), 'utf8');
+    expect(written).toMatch(/sourcePromptId: ticket-xyz-789/);
+  } finally {
+    await admin.stop();
+  }
+});

package/src/main/__tests__/prdParserSourcePromptId.test.cjs

@@ -0,0 +1,65 @@
+/**
+ * prdParserSourcePromptId.test.cjs — parsePrdRaw() tolerates both presence
+ * and absence of the optional `sourcePromptId` frontmatter key (PRD 749).
+ * Additive-only: PRDs written before this field existed must still parse
+ * identically (no required-field regression).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdParserSourcePromptId.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const { parsePrdRaw, _resetCache } = require('../scheduler/prdParser.cjs');
+
+function mkTmpPrdsDir() {
+  return fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prd-sourceprompt-'));
+}
+
+test('parsePrdRaw extracts sourcePromptId when present in frontmatter', async () => {
+  const dir = await mkTmpPrdsDir();
+  _resetCache();
+  const filePath = path.join(dir, '1-with-source.md');
+  await fsp.writeFile(filePath, [
+    '---',
+    'title: Has a source ticket',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 10',
+    'sourcePromptId: ticket-xyz-789',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(filePath);
+  expect(parsed.sourcePromptId).toBe('ticket-xyz-789');
+  expect(parsed.title).toBe('Has a source ticket');
+});
+
+test('parsePrdRaw returns null sourcePromptId for a PRD authored before this field existed', async () => {
+  const dir = await mkTmpPrdsDir();
+  _resetCache();
+  const filePath = path.join(dir, '2-legacy.md');
+  await fsp.writeFile(filePath, [
+    '---',
+    'title: Legacy PRD, no sourcePromptId',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 5',
+    '---',
+    '# Goal',
+    '',
+    'Do the other thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(filePath);
+  expect(parsed.sourcePromptId).toBe(null);
+  expect(parsed.title).toBe('Legacy PRD, no sourcePromptId');
+  expect(parsed.cwd).toBe(path.join(os.homedir(), 'Projects', 'session-manager'));
+});

package/src/main/__tests__/scheduler-notify-originating-tab.test.cjs

@@ -0,0 +1,99 @@
+/**
+ * scheduler-notify-originating-tab.test.cjs — unit tests for
+ * notifyOriginatingTab (PRD 761): on a job's terminal completed/failed
+ * transition, push a short status prompt into the chat tab that originated
+ * it via enqueueExternalPrompt (PRD 753).
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-notify-originating-tab.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, vi } from 'vitest';
+const { notifyOriginatingTab, isNotifiableTerminalStatus } = require('../scheduler.cjs');
+
+test('isNotifiableTerminalStatus: completed and failed are notifiable', () => {
+  expect(isNotifiableTerminalStatus('completed')).toBe(true);
+  expect(isNotifiableTerminalStatus('failed')).toBe(true);
+});
+
+test('isNotifiableTerminalStatus: needs_review is not notifiable (may still auto-fix)', () => {
+  expect(isNotifiableTerminalStatus('needs_review')).toBe(false);
+});
+
+test('isNotifiableTerminalStatus: a rateLimited exit never reaches an effectiveStatus (undefined) and is not notifiable', () => {
+  // spawnJob's treatAsPending branch (rateLimited || paused for rate_limit)
+  // resets the job to pending and returns before effectiveStatus is ever
+  // computed — so this hook is only ever evaluated with undefined/pending,
+  // never with a real status, on that path.
+  expect(isNotifiableTerminalStatus(undefined)).toBe(false);
+  expect(isNotifiableTerminalStatus('pending')).toBe(false);
+});
+
+test('resolves via sourceTabId when present on the PRD frontmatter', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => ({ sourceTabId: 'tab-from-frontmatter' }));
+  const loadSessions = vi.fn(async () => ({ tabs: [] }));
+
+  await notifyOriginatingTab(
+    { slug: '761-notify', status: 'completed', cwd: '/some/cwd' },
+    { parsePrdRaw, loadSessions, sendPrompt },
+  );
+
+  expect(loadSessions).not.toHaveBeenCalled();
+  expect(sendPrompt).toHaveBeenCalledTimes(1);
+  expect(sendPrompt).toHaveBeenCalledWith(
+    'tab-from-frontmatter',
+    expect.stringContaining('761-notify'),
+  );
+});
+
+test('falls back to the first open tab whose cwd matches the job cwd', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => ({ sourceTabId: null }));
+  const loadSessions = vi.fn(async () => ({
+    tabs: [
+      { id: 'tab-other', cwd: '/other/cwd' },
+      { id: 'tab-match', cwd: '/some/cwd' },
+      { id: 'tab-second-match', cwd: '/some/cwd' },
+    ],
+  }));
+
+  await notifyOriginatingTab(
+    { slug: '761-notify', status: 'failed', cwd: '/some/cwd' },
+    { parsePrdRaw, loadSessions, sendPrompt },
+  );
+
+  expect(sendPrompt).toHaveBeenCalledTimes(1);
+  expect(sendPrompt).toHaveBeenCalledWith('tab-match', expect.stringContaining('761-notify'));
+});
+
+test('no-ops without throwing when neither sourceTabId nor a cwd-matching tab resolves', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => ({ sourceTabId: null }));
+  const loadSessions = vi.fn(async () => ({ tabs: [{ id: 'tab-other', cwd: '/unrelated' }] }));
+
+  await expect(
+    notifyOriginatingTab(
+      { slug: '761-notify', status: 'completed', cwd: '/some/cwd' },
+      { parsePrdRaw, loadSessions, sendPrompt },
+    ),
+  ).resolves.not.toThrow();
+
+  expect(sendPrompt).not.toHaveBeenCalled();
+});
+
+test('no-ops when parsing the PRD frontmatter throws', async () => {
+  const sendPrompt = vi.fn();
+  const parsePrdRaw = vi.fn(async () => { throw new Error('ENOENT'); });
+  const loadSessions = vi.fn(async () => ({ tabs: [] }));
+
+  await expect(
+    notifyOriginatingTab(
+      { slug: '761-notify', status: 'completed', cwd: '/some/cwd' },
+      { parsePrdRaw, loadSessions, sendPrompt },
+    ),
+  ).resolves.not.toThrow();
+
+  expect(sendPrompt).not.toHaveBeenCalled();
+});