create-claude-cabinet 0.45.0 → 0.46.0

package/templates/scripts/__tests__/routine-dispatch.test.mjs

@@ -0,0 +1,312 @@
+// Routine dispatch engine (act:c2a55c08) — hermetic suite.
+// R1: declaration validation warns-and-skips, never throws.
+// R2: trigger evaluation is pure and correct per type (time-of-day fires
+//     once per day, interval, path-nonempty + cooldown, session-close).
+// R3: a firing files a 'routine' inbox item AND pushes through the single
+//     mux dispatch path; state records last_fired; mux-absent degrades to
+//     inbox-only without losing the item.
+// R4: structural anti-pile-up — a pending item blocks refiring; a STALE
+//     pending item is superseded and redispatched.
+// R5: queue-lib generalization — terminal exits on 'routine' items clear
+//     mux descriptors (resolve/dismiss/expire/runExpiry), with no QA gate.
+//
+// Fixtures are self-contained: WATCHTOWER_DIR / MUX_QA_DIR /
+// WATCHTOWER_MUX_BIN are set BEFORE the dynamic import (both libs read env
+// into module consts at load) — a static import would target live state.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync,
+  chmodSync, readdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const root = mkdtempSync(join(tmpdir(), 'routine-dispatch-'));
+process.env.WATCHTOWER_DIR = root;
+const muxQaRoot = join(root, 'mux-qa');
+process.env.MUX_QA_DIR = muxQaRoot;
+
+// Stub mux: records its argv (one line per call) and succeeds. Tests that
+// need the mux-absent path point WATCHTOWER_MUX_BIN at a missing file.
+const muxStub = join(root, 'mux-stub.sh');
+const muxCalls = join(root, 'mux-calls.log');
+writeFileSync(muxStub, `#!/bin/sh\necho "$@" >> "${muxCalls}"\nexit 0\n`);
+chmodSync(muxStub, 0o755);
+process.env.WATCHTOWER_MUX_BIN = muxStub;
+
+const r = await import('../watchtower-routines.mjs');
+const q = await import('../watchtower-queue.mjs');
+
+test.after(() => rmSync(root, { recursive: true, force: true }));
+
+const projectPath = join(root, 'proj');
+mkdirSync(projectPath, { recursive: true });
+
+function routine(overrides = {}) {
+  return {
+    name: 'morning-briefing',
+    description: 'Walk the operator through the day',
+    trigger: { type: 'time-of-day', at: '08:30' },
+    script: '.claude/routines/morning-briefing.md',
+    ...overrides,
+  };
+}
+
+function configWith(routines, projectName = 'proj-a') {
+  return { projects: { [projectName]: { path: projectPath, routines } } };
+}
+
+function muxCallCount() {
+  try { return readFileSync(muxCalls, 'utf8').trim().split('\n').filter(Boolean).length; }
+  catch { return 0; }
+}
+
+const at = (iso) => new Date(iso);
+
+// --- R1: declaration validation ---
+
+test('valid declaration passes for every trigger type', () => {
+  assert.deepEqual(r.validateRoutine(routine()), []);
+  assert.deepEqual(r.validateRoutine(routine({ trigger: { type: 'interval', minutes: 30 } })), []);
+  assert.deepEqual(r.validateRoutine(routine({ trigger: { type: 'path-nonempty', path: 'queue/' } })), []);
+  assert.deepEqual(r.validateRoutine(routine({ trigger: { type: 'session-close' } })), []);
+});
+
+test('invalid declarations name the broken field', () => {
+  assert.match(r.validateRoutine(routine({ name: 'Bad Name!' })).join(';'), /kebab-case/);
+  assert.match(r.validateRoutine(routine({ script: '' })).join(';'), /script/);
+  assert.match(r.validateRoutine(routine({ trigger: { type: 'cron' } })).join(';'), /trigger\.type/);
+  assert.match(r.validateRoutine(routine({ trigger: { type: 'time-of-day', at: '25:99' } })).join(';'), /HH:MM/);
+  assert.match(r.validateRoutine(routine({ trigger: { type: 'interval', minutes: 1 } })).join(';'), /interval/);
+  assert.match(r.validateRoutine(routine({ trigger: { type: 'path-nonempty' } })).join(';'), /path/);
+});
+
+// --- R2: trigger evaluation (pure) ---
+
+const tick = { type: 'tick' };
+const close = { type: 'session-close' };
+
+test('time-of-day: not due before the slot, due after, fires once per day', () => {
+  const rt = routine();
+  const before = at('2026-06-12T08:00:00');
+  const after = at('2026-06-12T09:00:00');
+  assert.equal(r.triggerDue(rt, null, tick, before, projectPath), false);
+  assert.equal(r.triggerDue(rt, null, tick, after, projectPath), true);
+  // already fired today after the slot → not due again
+  assert.equal(r.triggerDue(rt, '2026-06-12T08:31:00', tick, after, projectPath), false);
+  // fired yesterday → due again today
+  assert.equal(r.triggerDue(rt, '2026-06-11T08:31:00', tick, after, projectPath), true);
+});
+
+test('interval: due when never fired or the interval has elapsed', () => {
+  const rt = routine({ trigger: { type: 'interval', minutes: 30 } });
+  const now = at('2026-06-12T12:00:00');
+  assert.equal(r.triggerDue(rt, null, tick, now, projectPath), true);
+  assert.equal(r.triggerDue(rt, '2026-06-12T11:45:00', tick, now, projectPath), false);
+  assert.equal(r.triggerDue(rt, '2026-06-12T11:20:00', tick, now, projectPath), true);
+});
+
+test('path-nonempty: content gates, cooldown throttles', () => {
+  const qdir = join(projectPath, 'cmd-queue');
+  const rt = routine({ trigger: { type: 'path-nonempty', path: 'cmd-queue' } });
+  const now = at('2026-06-12T12:00:00');
+  // missing → not due; empty dir → not due; content → due
+  assert.equal(r.triggerDue(rt, null, tick, now, projectPath), false);
+  mkdirSync(qdir, { recursive: true });
+  assert.equal(r.triggerDue(rt, null, tick, now, projectPath), false);
+  writeFileSync(join(qdir, 'cmd.json'), '{}');
+  assert.equal(r.triggerDue(rt, null, tick, now, projectPath), true);
+  // default 60-min cooldown
+  assert.equal(r.triggerDue(rt, '2026-06-12T11:30:00', tick, now, projectPath), false);
+  assert.equal(r.triggerDue(rt, '2026-06-12T10:30:00', tick, now, projectPath), true);
+});
+
+test('session-close: only fires on session-close events, tick triggers only on ticks', () => {
+  const rt = routine({ trigger: { type: 'session-close' } });
+  const now = at('2026-06-12T12:00:00');
+  assert.equal(r.triggerDue(rt, null, close, now, projectPath), true);
+  assert.equal(r.triggerDue(rt, null, tick, now, projectPath), false);
+  assert.equal(r.triggerDue(routine(), null, close, at('2026-06-12T09:00:00'), projectPath), false);
+  // cooldown_minutes throttles back-to-back closes
+  const cooled = routine({ trigger: { type: 'session-close' }, cooldown_minutes: 30 });
+  assert.equal(r.triggerDue(cooled, '2026-06-12T11:50:00', close, now, projectPath), false);
+  assert.equal(r.triggerDue(cooled, '2026-06-12T11:20:00', close, now, projectPath), true);
+});
+
+// --- R3: firing files the item and pushes the single dispatch path ---
+
+test('tick pass fires a due routine: inbox item + mux dispatch + state', () => {
+  const callsBefore = muxCallCount();
+  const pass = r.runRoutinePass({
+    config: configWith([routine()]),
+    event: tick,
+    filedBy: 'ring1',
+    now: at('2026-06-12T09:00:00'),
+  });
+  assert.equal(pass.fired.length, 1);
+  assert.equal(pass.fired[0].status, 'dispatched');
+  assert.equal(muxCallCount(), callsBefore + 1);
+
+  const item = q.getItem(pass.fired[0].item_id);
+  assert.equal(item.category, 'routine');
+  assert.equal(item.filed_by, 'ring1');
+  assert.equal(item.evidence.routine_key, 'proj-a/morning-briefing');
+  assert.match(item.title, /morning-briefing/);
+
+  const state = r.loadRoutineState();
+  assert.equal(state['proj-a/morning-briefing'].last_item_id, item.id);
+  assert.equal(state['proj-a/morning-briefing'].last_fired, at('2026-06-12T09:00:00').toISOString());
+
+  // descriptor tmp file is cleaned up after the push
+  const tmpFiles = existsSync(join(root, 'tmp')) ? readdirSync(join(root, 'tmp')) : [];
+  assert.deepEqual(tmpFiles.filter((f) => f.startsWith('routine-')), []);
+
+  // cleanup for later tests
+  q.resolveItem(item.id, { resolution: 'ran', resolution_type: 'acted-on' });
+});
+
+test('mux absent degrades to inbox-only without losing the item', () => {
+  process.env.WATCHTOWER_MUX_BIN = join(root, 'no-such-mux');
+  try {
+    const res = r.dispatchRoutine({
+      projectName: 'proj-a', projectPath,
+      routine: routine({ name: 'evening-review' }), filedBy: 'ring1',
+    });
+    assert.equal(res.status, 'inbox-only');
+    assert.equal(q.getItem(res.item_id).category, 'routine');
+    q.dismissItem(res.item_id, { notes: 'test cleanup' });
+  } finally {
+    process.env.WATCHTOWER_MUX_BIN = muxStub;
+  }
+});
+
+test('session-close pass fires only the named project, and only close-triggered routines', () => {
+  const config = {
+    projects: {
+      'proj-a': { path: projectPath, routines: [routine({ name: 'close-sweep', trigger: { type: 'session-close' } })] },
+      'proj-b': { path: projectPath, routines: [routine({ name: 'close-sweep-b', trigger: { type: 'session-close' } })] },
+    },
+  };
+  const pass = r.runRoutinePass({
+    config, event: { type: 'session-close', project: 'proj-a' },
+    filedBy: 'ring3-close', now: at('2026-06-12T13:00:00'),
+  });
+  assert.deepEqual(pass.fired.map((f) => f.key), ['proj-a/close-sweep']);
+  assert.equal(q.getItem(pass.fired[0].item_id).filed_by, 'ring3-close');
+  q.resolveItem(pass.fired[0].item_id, { resolution: 'ran', resolution_type: 'acted-on' });
+});
+
+test('invalid routine is reported and skipped, valid siblings still fire', () => {
+  const pass = r.runRoutinePass({
+    config: configWith([
+      routine({ name: 'BROKEN NAME' }),
+      routine({ name: 'still-fires', trigger: { type: 'interval', minutes: 30 } }),
+    ]),
+    event: tick, filedBy: 'ring1', now: at('2026-06-12T14:00:00'),
+  });
+  assert.equal(pass.invalid.length, 1);
+  assert.deepEqual(pass.fired.map((f) => f.key), ['proj-a/still-fires']);
+  q.resolveItem(pass.fired[0].item_id, { resolution: 'ran', resolution_type: 'acted-on' });
+});
+
+// --- R4: anti-pile-up ---
+
+test('pending item blocks refiring; stale pending item is superseded and redispatched', () => {
+  const rt = routine({ name: 'daily-digest', trigger: { type: 'time-of-day', at: '07:00' } });
+  const day1 = at('2026-06-12T07:05:00');
+  const first = r.runRoutinePass({ config: configWith([rt]), event: tick, filedBy: 'ring1', now: day1 });
+  assert.equal(first.fired.length, 1);
+  const firstId = first.fired[0].item_id;
+
+  // same day, later tick → blocked by once-per-day; next day with the item
+  // still pending but younger than stale_after_hours → pending-exists skip
+  const day2early = at('2026-06-13T07:05:00');
+  const freshRt = { ...rt, stale_after_hours: 48 };
+  const blocked = r.runRoutinePass({ config: configWith([freshRt]), event: tick, filedBy: 'ring1', now: day2early });
+  assert.equal(blocked.fired.length, 0);
+  assert.deepEqual(blocked.skipped.map((s) => s.reason), ['pending-exists']);
+  assert.equal(q.getItem(firstId).status, 'pending');
+
+  // next day with default 24h staleness → old item superseded, new one filed.
+  // createItem stamps filed_at with the REAL clock, so backdate it on disk
+  // to put the pending item past the staleness window relative to day2.
+  const day2 = at('2026-06-13T07:10:00');
+  const fp = join(root, 'queue', 'items', `${firstId}.json`);
+  const pendingItem = JSON.parse(readFileSync(fp, 'utf8'));
+  pendingItem.filed_at = new Date(day2.getTime() - 25 * 3_600_000).toISOString();
+  writeFileSync(fp, JSON.stringify(pendingItem, null, 2));
+  const second = r.runRoutinePass({ config: configWith([rt]), event: tick, filedBy: 'ring1', now: day2 });
+  assert.equal(second.fired.length, 1);
+  assert.notEqual(second.fired[0].item_id, firstId);
+  assert.equal(q.getItem(firstId).status, 'superseded');
+  assert.match(q.getItem(firstId).resolution_notes, /newer firing/);
+  q.resolveItem(second.fired[0].item_id, { resolution: 'ran', resolution_type: 'acted-on' });
+});
+
+// --- R5: queue-lib generalization (descriptor clearing, no QA gate) ---
+
+function plantDescriptors(itemId) {
+  const desk = join(muxQaRoot, 'some-desk');
+  mkdirSync(join(desk, 'in-flight'), { recursive: true });
+  writeFileSync(join(desk, `${itemId}.json`), '{}');
+  writeFileSync(join(desk, 'in-flight', `${itemId}.json`), '{}');
+  return desk;
+}
+
+function makeRoutineItem() {
+  return q.createItem({
+    project: 'proj-a', project_path: projectPath, category: 'routine',
+    title: 'Routine: x', summary: 's', context_anchor: 'routine proj-a/x',
+    evidence: { routine_key: 'proj-a/x' },
+  });
+}
+
+test('resolving a routine item needs no qa_verdict and clears descriptors (queued + in-flight)', () => {
+  const id = makeRoutineItem();
+  const desk = plantDescriptors(id);
+  const out = q.resolveItem(id, { resolution: 'ran', resolution_type: 'acted-on' });
+  assert.equal(out.status, 'resolved');
+  assert.equal(existsSync(join(desk, `${id}.json`)), false);
+  assert.equal(existsSync(join(desk, 'in-flight', `${id}.json`)), false);
+});
+
+test('dismissing a routine item needs no typed reason and clears descriptors', () => {
+  const id = makeRoutineItem();
+  const desk = plantDescriptors(id);
+  assert.equal(q.dismissItem(id).status, 'dismissed');
+  assert.equal(existsSync(join(desk, `${id}.json`)), false);
+});
+
+test('routine items expire normally (no qa gate) and expiry clears descriptors', () => {
+  const id = makeRoutineItem();
+  const desk = plantDescriptors(id);
+  assert.equal(q.expireItem(id).status, 'expired');
+  assert.equal(existsSync(join(desk, `${id}.json`)), false);
+  assert.equal(existsSync(join(desk, 'in-flight', `${id}.json`)), false);
+});
+
+test('runExpiry expires an aged routine item and clears its descriptor', () => {
+  const id = makeRoutineItem();
+  const desk = plantDescriptors(id);
+  // backdate filed_at past the expiry window
+  const fp = join(root, 'queue', 'items', `${id}.json`);
+  const item = JSON.parse(readFileSync(fp, 'utf8'));
+  item.filed_at = '2026-01-01T00:00:00.000Z';
+  writeFileSync(fp, JSON.stringify(item, null, 2));
+  const { expired } = q.runExpiry({ warnDays: 14, expireDays: 30 });
+  assert.ok(expired.some((i) => i.id === id));
+  assert.equal(q.getItem(id).status, 'expired');
+  assert.equal(existsSync(join(desk, `${id}.json`)), false);
+});
+
+test('qa-handoff gate untouched by the generalization (regression)', () => {
+  const id = q.createItem({
+    project: 'proj-a', project_path: projectPath, category: 'qa-handoff',
+    title: 'QA handoff: t', summary: 's', context_anchor: 'git show abc',
+  });
+  assert.throws(() => q.resolveItem(id, { resolution: 'done' }), /qa_verdict/);
+  assert.throws(() => q.expireItem(id), /never expire/);
+  q.dismissItem(id, { notes: 'test cleanup', resolution_type: 'noise' });
+});

package/templates/scripts/watchtower-advisories.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+// Watchtower environment-advisories pass (act:f9ea075d).
+//
+// The single home for orient's stack-aware setup advisories — LSP plugins,
+// the Railway MCP, hookify, a missing project briefing, registry orphans —
+// with a per-project dismissal memory so nothing re-nags every session.
+//
+// HOME = the SessionStart context builder, NOT Ring 1: Ring 1's launchd cron
+// PATH cannot reach `claude`, so the install-probe (`claude plugin list`)
+// would fail there. The context builder runs in the real session env.
+//
+// This module owns ALL advisory I/O: signal computation, the throttled probe,
+// reading and atomic-writing the dismissal state, and applying the rules in
+// `advisories-state-schema.md`. The context builder only calls runAdvisoryPass
+// and renders the returned list. The pass NEVER throws — any failure returns
+// an empty list and persists nothing, so it can never block session start.
+//
+// State file: <projectPath>/.claude/cabinet/advisories-state.json. Read AND
+// written at the SAME path (the schema blesses per-worktree divergence; the
+// cardinal rule is never read one path and write another). atomicWrite is
+// temp+rename — corruption-safe but not read-modify-write-safe; concurrent
+// sessions accept lost-update semantics (a lost count++ = one extra nag,
+// self-correcting).
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import { atomicWrite } from './watchtower-lib.mjs';
+
+const STATE_REL = join('.claude', 'cabinet', 'advisories-state.json');
+const SCAN_MAX_DEPTH = 3;
+const SCAN_DENYLIST = new Set([
+  'node_modules', 'dist', 'build', 'vendor', 'coverage', 'target', 'out',
+]);
+const PROBE_TIMEOUT_MS = 3000;
+const SURFACE_COUNT_LIMIT = 2; // a `suggested` advisory surfaces while count < 2
+
+// --- date / IO helpers ---
+
+function todayUTC() {
+  // UTC ISO date, matching the schema's last_shown basis AND sqlite date('now')
+  // (the overdue query). Local-time formatting would drift at the day boundary.
+  return new Date().toISOString().slice(0, 10);
+}
+
+function safeReadJSON(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null; // absent OR malformed → treated as "every advisory never-seen"
+  }
+}
+
+// --- bounded stack-file scan ---
+
+// Existence-only, depth-limited, denylisted, early-exit. A recursive *.ts walk
+// over node_modules would be pathological on the session-start critical path;
+// a root-only scan would silently miss the common src/**/*.ts layout (a TS
+// project with no root tsconfig). This catches src/** while staying bounded.
+function hasFileWithExt(dir, ext, depth = SCAN_MAX_DEPTH) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  const subdirs = [];
+  for (const e of entries) {
+    if (e.isFile() && e.name.endsWith(ext)) return true;
+    if (e.isDirectory() && !SCAN_DENYLIST.has(e.name) && !e.name.startsWith('.')) {
+      subdirs.push(e.name);
+    }
+  }
+  if (depth <= 0) return false;
+  for (const sd of subdirs) {
+    if (hasFileWithExt(join(dir, sd), ext, depth - 1)) return true;
+  }
+  return false;
+}
+
+function has(projectPath, rel) {
+  return existsSync(join(projectPath, rel));
+}
+
+// Signal = a deterministic fingerprint of the indicators present. Tokens are
+// SORTED before joining so the same stack always produces the same string —
+// otherwise readdir order could flip "gemfile+rb" ↔ "rb+gemfile" and spuriously
+// re-arm a declined advisory every session.
+function signalFrom(tokens) {
+  const present = tokens.filter(Boolean);
+  return present.length ? present.slice().sort().join('+') : null;
+}
+
+// --- advisory descriptors ---
+//
+// kind:
+//   'probe-suppressed' — signal is on-disk (stack files); the probe only
+//      SUPPRESSES (confirms installed → terminal). Unknown probe → still
+//      surface (the LSP advisories).
+//   'probe-gated' — the surfacing predicate IS the probe ("X not installed");
+//      unknown probe → freeze, do not surface, do not mutate (hookify).
+//   'no-probe' — pure filesystem/config signal (railway, briefing-file,
+//      registry-orphan).
+
+function buildAdvisories(ctx) {
+  const { projectPath, claudeJsonText, registry } = ctx;
+  const list = [];
+
+  const lsp = [
+    { id: 'lsp:typescript', tokens: () => [has(projectPath, 'tsconfig.json') && 'tsconfig', hasFileWithExt(projectPath, '.ts') && 'ts'], needle: 'typescript-lsp', action: 'TypeScript detected but typescript-lsp not installed — catches missing imports/type errors after edits. Install: /plugin install typescript-lsp' },
+    { id: 'lsp:python', tokens: () => [has(projectPath, 'pyproject.toml') && 'pyproject', has(projectPath, 'requirements.txt') && 'requirements', hasFileWithExt(projectPath, '.py') && 'py'], needle: 'pyright-lsp', action: 'Python detected but pyright-lsp not installed. Install: /plugin install pyright-lsp' },
+    { id: 'lsp:rust', tokens: () => [has(projectPath, 'Cargo.toml') && 'cargo'], needle: 'rust-analyzer-lsp', action: 'Rust detected but rust-analyzer-lsp not installed. Install: /plugin install rust-analyzer-lsp' },
+    { id: 'lsp:go', tokens: () => [has(projectPath, 'go.mod') && 'gomod'], needle: 'gopls-lsp', action: 'Go detected but gopls-lsp not installed. Install: /plugin install gopls-lsp' },
+    { id: 'lsp:ruby', tokens: () => [has(projectPath, 'Gemfile') && 'gemfile', hasFileWithExt(projectPath, '.rb') && 'rb'], needle: 'ruby-lsp', action: 'Ruby detected but ruby-lsp not active. Install the plugin (/plugin install ruby-lsp@claude-plugins-official), the gem (gem install ruby-lsp), and set ENABLE_LSP_TOOL=1.' },
+  ];
+  for (const a of lsp) {
+    const signal = signalFrom(a.tokens());
+    if (signal) list.push({ id: a.id, kind: 'probe-suppressed', needle: a.needle, signal, action: a.action });
+  }
+
+  // Railway MCP — railway.toml present AND no railway key registered in
+  // ~/.claude.json. NOTE: Ring 1 also marker-checks railway.toml (deploy
+  // detection) — do NOT consolidate; this adds the registration predicate.
+  if (has(projectPath, 'railway.toml')) {
+    const registered = !!claudeJsonText && /railway/i.test(claudeJsonText);
+    if (!registered) {
+      list.push({ id: 'mcp:railway', kind: 'no-probe', needle: null, signal: 'railway-unregistered',
+        action: 'railway.toml present but no Railway MCP registered — agents get a cleaner surface with it. Local: railway setup agent -y · Remote: register mcp.railway.com (OAuth).' });
+    }
+  }
+
+  // hookify — enforcement-pipeline.md exists AND hookify not installed. Signal
+  // is STATIC (the file, once created, stays), so a declined hookify stays
+  // declined until its entry is cleared (intended sticky case).
+  if (has(projectPath, join('.claude', 'rules', 'enforcement-pipeline.md'))) {
+    list.push({ id: 'plugin:hookify', kind: 'probe-gated', needle: 'hookify', signal: 'enforcement-pipeline',
+      action: 'This project has an enforcement pipeline but hookify is not installed — it generates hooks from natural language. Install: /plugin install hookify' });
+  }
+
+  // Briefing file presence — surface only when ABSENT.
+  if (!has(projectPath, join('.claude', 'briefing', '_briefing.md'))) {
+    list.push({ id: 'briefing-file', kind: 'no-probe', needle: null, signal: 'missing',
+      action: 'No project briefing at .claude/briefing/_briefing.md — cabinet members bootstrap from it. Run /onboard to create one.' });
+  }
+
+  // Registry orphans — registry entries whose path no longer exists.
+  if (registry && Array.isArray(registry.projects)) {
+    const orphans = registry.projects
+      .filter((p) => p && p.path && !existsSync(p.path))
+      .map((p) => p.name || p.path)
+      .sort();
+    if (orphans.length > 0) {
+      list.push({ id: 'registry-orphan', kind: 'no-probe', needle: null, signal: `orphans:${orphans.join('+')}`,
+        action: `cc-registry lists project(s) whose path is gone: ${orphans.join(', ')} — consider removing them from ~/.claude/cc-registry.json.` });
+    }
+  }
+
+  return list;
+}
+
+// --- the probe ---
+
+// Returns the lowercased `claude plugin list` output, or null if the probe
+// could not answer (claude not on PATH, nonzero exit, timeout). null is the
+// tri-state's "unknown" — never conflated with "absent".
+function defaultPluginProbe() {
+  try {
+    const out = execSync('claude plugin list', {
+      encoding: 'utf8', timeout: PROBE_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return typeof out === 'string' ? out.toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+// tri-state: true | false | null
+function isInstalled(probeText, needle) {
+  if (probeText == null) return null;
+  return probeText.includes(needle.toLowerCase());
+}
+
+// --- the rule engine (advisories-state-schema.md) ---
+
+// Returns { surface, entry, mutated }. `entry` is the entry to store (or the
+// unchanged one); `mutated` says whether state changed (drives the dirty flag
+// and avoids needless writes / frozen no-ops).
+function applyRule(prev, { signal, kind, installed }, today) {
+  // Terminal: already installed → never surface, never change.
+  if (prev && prev.status === 'installed') {
+    return { surface: false, entry: prev, mutated: false };
+  }
+
+  // Probe confirms installed now → flip terminal (both probe kinds).
+  if (kind !== 'no-probe' && installed === true) {
+    const entry = { status: 'installed', count: prev?.count || 0, last_shown: prev?.last_shown || today, signal };
+    return { surface: false, entry, mutated: true };
+  }
+
+  // Probe-gated with unknown probe → predicate unknowable → freeze (no mutation).
+  if (kind === 'probe-gated' && installed === null) {
+    return { surface: false, entry: prev, mutated: false };
+  }
+
+  // No entry → surface, create.
+  if (!prev) {
+    return { surface: true, entry: { status: 'suggested', count: 1, last_shown: today, signal }, mutated: true };
+  }
+
+  if (prev.status === 'declined') {
+    if (prev.signal === signal) return { surface: false, entry: prev, mutated: false }; // silent
+    // signal changed → stack evolved → re-surface once, reset.
+    return { surface: true, entry: { status: 'suggested', count: 1, last_shown: today, signal }, mutated: true };
+  }
+
+  if (prev.status === 'suggested') {
+    if (prev.signal !== signal) {
+      // stack changed at any count → reset + surface.
+      return { surface: true, entry: { status: 'suggested', count: 1, last_shown: today, signal }, mutated: true };
+    }
+    if ((prev.count || 0) < SURFACE_COUNT_LIMIT) {
+      return { surface: true, entry: { ...prev, count: (prev.count || 0) + 1, last_shown: today, signal }, mutated: true };
+    }
+    return { surface: false, entry: prev, mutated: false }; // count >= 2, unchanged → quiet
+  }
+
+  return { surface: false, entry: prev, mutated: false };
+}
+
+// --- main entry ---
+
+export function runAdvisoryPass({ projectPath, pluginProbe = defaultPluginProbe, homeDir = homedir(), now = todayUTC() } = {}) {
+  try {
+    if (!projectPath) return [];
+
+    const today = now;
+    const statePath = join(projectPath, STATE_REL);
+    const rawState = safeReadJSON(statePath) || {};
+    const meta = (rawState._meta && typeof rawState._meta === 'object') ? rawState._meta : {};
+    const lastProbe = meta.last_probe ?? null;
+
+    const claudeJsonText = (() => {
+      try { return readFileSync(join(homeDir, '.claude.json'), 'utf8'); } catch { return null; }
+    })();
+    const registry = safeReadJSON(join(homeDir, '.claude', 'cc-registry.json'));
+
+    const advisories = buildAdvisories({ projectPath, claudeJsonText, registry });
+    if (advisories.length === 0) return [];
+
+    // Probe at most once/day/checkout, and only if a probe-kind advisory is
+    // applicable. Throttle skip leaves probeText=null → LSP still surfaces
+    // from cached state, hookify stays silent (probe-gated null = freeze).
+    const needProbe = advisories.some((a) => a.kind !== 'no-probe');
+    const throttled = lastProbe === today;
+    let probeText = null;
+    let probed = false;
+    if (needProbe && !throttled) {
+      probeText = pluginProbe();
+      probed = true;
+    }
+
+    const surfaced = [];
+    let dirty = false;
+    for (const a of advisories) {
+      const installed = a.kind === 'no-probe' ? false : isInstalled(probeText, a.needle);
+      const { surface, entry, mutated } = applyRule(rawState[a.id], { signal: a.signal, kind: a.kind, installed }, today);
+      if (mutated) {
+        rawState[a.id] = entry;
+        dirty = true;
+      }
+      if (surface) surfaced.push({ id: a.id, action: a.action });
+    }
+
+    // Record the probe stamp only when a probe actually ran (non-null result).
+    if (probed && probeText != null) {
+      rawState._meta = { ...meta, last_probe: today };
+      dirty = true;
+    }
+
+    if (dirty) {
+      try { atomicWrite(statePath, rawState); } catch { /* surfacing still valid; persistence is best-effort */ }
+    }
+
+    return surfaced;
+  } catch {
+    return []; // never throw — must not block session start
+  }
+}
+
+// CLI: print one advisory action per line (used by orient's non-watchtower
+// fallback, which can shell out to the single implementation).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  let projectPath = process.cwd();
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project-path' && args[i + 1]) { projectPath = args[i + 1]; i++; }
+  }
+  for (const a of runAdvisoryPass({ projectPath })) {
+    process.stdout.write(`${a.action}\n`);
+  }
+}