auriga-cli 1.18.5 → 1.20.0

package/dist/guide.js

@@ -20,7 +20,7 @@ export function renderGuide(opts) {
     return `${h(`# auriga-cli bootstrap SOP (v${opts.version})`)}
 
 This guide walks an Agent through installing the auriga harness
-(CLAUDE.md + skills + plugins + hooks) into the current repository.
+(CLAUDE.md + skills + plugins, plus any legacy hooks) into the current repository.
 
 Run each step in order. If any step fails with exit 1, stop and report.
 If exit 2, see stderr for per-category status and follow the "Retry"
@@ -62,8 +62,8 @@ Per-type detail (flags + only that category's catalog slice):
 
 ${h("## Step 3 — Install")}
 
-Preset — the full default-on set (workflow + skills + plugins + hooks;
-recommended skills are NOT included):
+Preset — the full default-on set (workflow + skills + default plugins;
+the legacy hooks category is currently empty; recommended skills are NOT included):
   ${cmd("npx -y auriga-cli install --all")}
 
 Targeted — single category, picking from the catalog surfaced in Step 2:
@@ -72,10 +72,10 @@ Targeted — single category, picking from the catalog surfaced in Step 2:
   ${cmd("npx -y auriga-cli install plugins --plugin skill-creator codex --scope user")}
   ${cmd("npx -y auriga-cli install plugins --agent codex --plugin session-instructions-loader")}
 
-Opt-in hooks (\`defaultOn: false\`) are NOT in the default \`install --all\`
-set because they have side effects (OS notifications, platform-gated
-deps). Inspect \`install hooks --help\` for the catalog and install by name:
-  ${cmd("npx -y auriga-cli install hooks --hook notify")}
+Opt-in plugins (\`defaultOn: false\`) are NOT in the default \`install --all\`
+set because they have side effects or platform-specific behavior. For example,
+the macOS notification plugin is explicit opt-in:
+  ${cmd("npx -y auriga-cli install plugins --plugin auriga-notify")}
 
 Opt-in recommended skills (cross-model delegation helpers —
 claude-code-agent, codex-agent):
@@ -94,7 +94,7 @@ Exit codes:
 ${h("## Step 4 — Reload session (REQUIRED when installed non-interactively)")}
 
 ${warn("⚠")} CLAUDE.md, .agents/skills/, .claude/plugins.json, Codex plugin
-config, and hook registrations are loaded at session startup. If you ran
+config, and hook/plugin registrations are loaded at session startup. If you ran
 \`npx -y auriga-cli install\` inside an existing Claude Code or Codex session
 (e.g., \`claude -p\` / \`claude -p --worktree\` / \`codex exec\`), the current session
 will NOT see the new harness.
@@ -112,7 +112,8 @@ Expected artifacts:
   - .agents/skills/<name>/    (one per installed skill)
   - .claude/plugins.json
   - ~/.codex/config.toml      (Codex plugin enablement, if Codex plugins selected)
-  - .claude/settings.json     (updated hook registrations, if hooks selected)
+  - .claude/settings.json     (updated hook/plugin registrations, if selected)
+  - .claude/auriga-notify/    (project notify config, if auriga-notify selected)
 
 ${h("## Troubleshooting")}
 

package/dist/help.js

@@ -125,7 +125,7 @@ USAGE
 
 FLAGS
   --plugin <names...>      space-separated; '*' = all
-                           omit → install every plugin available for the selected agent
+                           omit → install every plugin with defaultOn != false
   --agent <...>            target runtime: claude, codex, or both
                            default claude; codex enablement is user-level
   --scope <project|user>   default project

package/dist/hooks.js

@@ -687,7 +687,12 @@ export async function installHooks(packageRoot, opts) {
     const config = loadHooksConfig(packageRoot);
     const compatible = config.hooks.filter((h) => h.runtimePlatforms.includes(process.platform));
     if (compatible.length === 0) {
-        log.warn(`No hooks available for your platform (${process.platform}). Skipping.`);
+        if (config.hooks.length === 0) {
+            log.warn("No legacy hooks are defined. The notify hook moved to the opt-in auriga-notify plugin.");
+        }
+        else {
+            log.warn(`No hooks available for your platform (${process.platform}). Skipping.`);
+        }
         return;
     }
     // Non-interactive explicit `--hook <name>` has stronger intent than

package/dist/plugins.js

@@ -15,6 +15,14 @@ import { atomicWriteFile, exec, execAsync, fetchExtraContent, log, withEsc } fro
 // `./marketplace.js` so Claude and Codex sides share one validator.
 const PLUGIN_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const PLUGIN_PACKAGE_RE = /^[A-Za-z0-9][A-Za-z0-9._@/-]{0,255}$/;
+const MIGRATED_WORKFLOW_SKILLS = [
+    "incremental-impl",
+    "test-designer",
+    "session-compound",
+];
+const NOTIFY_PLUGIN_NAME = "auriga-notify";
+const WORKFLOW_SKILLS_PLUGIN_NAME = "auriga-workflow-skills";
+const LEGACY_NOTIFY_MARKER = "auriga:notify";
 export function validatePluginsConfig(raw) {
     if (!raw || typeof raw !== "object") {
         throw new Error("plugins.json: root must be an object");
@@ -37,6 +45,9 @@ export function validatePluginsConfig(raw) {
         if (plugin.marketplace !== undefined) {
             validateMarketplaceField(`plugins.json: plugins[${i}]`, plugin.marketplace);
         }
+        if (plugin.defaultOn !== undefined && typeof plugin.defaultOn !== "boolean") {
+            throw new Error(`plugins.json: plugins[${i}].defaultOn must be a boolean`);
+        }
     });
 }
 function getInstalledPlugins() {
@@ -60,12 +71,14 @@ function getInstalledPlugins() {
     }
 }
 /**
- * Non-interactive selection resolver for plugins. Mirrors the skills
- * resolveSelected: `undefined` / `["*"]` = full set; explicit names =
- * filter. CLI parser validates names up-front.
+ * Non-interactive selection resolver for plugins.
+ * `undefined` = default-on set; `["*"]` = full set; explicit names =
+ * exact filter. CLI parser validates names up-front.
  */
 function resolvePluginSelection(all, selected) {
-    if (!selected || (selected.length === 1 && selected[0] === "*"))
+    if (!selected)
+        return all.filter((p) => p.defaultOn !== false);
+    if (selected.length === 1 && selected[0] === "*")
         return all;
     const byName = new Map(all.map((p) => [p.name, p]));
     const missing = selected.filter((name) => !byName.has(name));
@@ -121,6 +134,164 @@ function codexHome() {
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
+function installTargetCwd(opts) {
+    return path.resolve(opts.cwd ?? process.cwd());
+}
+function emitMigrationLog(opts, line) {
+    opts.onLog?.(line, "stdout");
+}
+function runtimeSkillRoot(runtime) {
+    return runtime === "claude" ? ".claude" : ".agents";
+}
+function legacySkillDir(opts, runtime, name) {
+    const cwd = installTargetCwd(opts);
+    const scope = opts.scope ?? "project";
+    const baseDir = scope === "user" ? os.homedir() : cwd;
+    return path.join(baseDir, runtimeSkillRoot(runtime), "skills", name);
+}
+function isWorkflowPluginDevSymlink(skillPath, cwd, name) {
+    const stat = fs.lstatSync(skillPath, { throwIfNoEntry: false });
+    if (!stat?.isSymbolicLink())
+        return false;
+    const target = fs.readlinkSync(skillPath);
+    const resolved = path.resolve(path.dirname(skillPath), target);
+    const expected = path.resolve(cwd, "plugins", "auriga-workflow-skills", "skills", name);
+    return resolved === expected;
+}
+function removeMigratedSkillFromLock(cwd, name, opts) {
+    const lockPath = path.join(cwd, "skills-lock.json");
+    if (!fs.existsSync(lockPath))
+        return;
+    const raw = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+    if (!raw.skills || typeof raw.skills !== "object" || !(name in raw.skills))
+        return;
+    const nextSkills = { ...raw.skills };
+    delete nextSkills[name];
+    atomicWriteFile(lockPath, JSON.stringify({ ...raw, skills: nextSkills }, null, 2) + "\n");
+    emitMigrationLog(opts, `removed ${name} from skills-lock.json`);
+}
+function cleanupMigratedWorkflowSkillInstalls(opts, runtimes) {
+    const cwd = installTargetCwd(opts);
+    const scope = opts.scope ?? "project";
+    for (const name of MIGRATED_WORKFLOW_SKILLS) {
+        for (const runtime of runtimes) {
+            const dir = legacySkillDir(opts, runtime, name);
+            const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
+            if (!stat) {
+                emitMigrationLog(opts, `${runtimeSkillRoot(runtime)}/skills/${name} not present`);
+                continue;
+            }
+            if (scope === "project" && isWorkflowPluginDevSymlink(dir, cwd, name)) {
+                emitMigrationLog(opts, `preserved ${runtimeSkillRoot(runtime)}/skills/${name} development symlink`);
+                continue;
+            }
+            fs.rmSync(dir, { recursive: true, force: true });
+            emitMigrationLog(opts, `removed ${runtimeSkillRoot(runtime)}/skills/${name}`);
+        }
+        if (scope === "project")
+            removeMigratedSkillFromLock(cwd, name, opts);
+    }
+}
+function copyIfPresentWithoutOverwrite(src, dest) {
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return false;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    return true;
+}
+function removeMarkerFromSettings(settings, marker) {
+    const next = JSON.parse(JSON.stringify(settings ?? {}));
+    if (!next.hooks || typeof next.hooks !== "object" || Array.isArray(next.hooks)) {
+        return { settings: next, removed: 0 };
+    }
+    let removed = 0;
+    for (const event of Object.keys(next.hooks)) {
+        const groups = next.hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const nextGroups = [];
+        for (const group of groups) {
+            if (!Array.isArray(group.hooks)) {
+                nextGroups.push(group);
+                continue;
+            }
+            const hooks = group.hooks.filter((action) => {
+                if (action?._marker === marker) {
+                    removed += 1;
+                    return false;
+                }
+                return true;
+            });
+            if (hooks.length > 0)
+                nextGroups.push({ ...group, hooks });
+        }
+        if (nextGroups.length > 0)
+            next.hooks[event] = nextGroups;
+        else
+            delete next.hooks[event];
+    }
+    return { settings: next, removed };
+}
+function cleanLegacyNotifySettings(settingsPaths, opts) {
+    let allReadable = true;
+    for (const settingsPath of settingsPaths) {
+        if (!fs.existsSync(settingsPath))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        }
+        catch {
+            emitMigrationLog(opts, `skipped unreadable legacy notify settings: ${settingsPath}`);
+            allReadable = false;
+            continue;
+        }
+        const result = removeMarkerFromSettings(parsed, LEGACY_NOTIFY_MARKER);
+        if (result.removed === 0)
+            continue;
+        atomicWriteFile(settingsPath, JSON.stringify(result.settings, null, 2) + "\n");
+        emitMigrationLog(opts, `removed ${result.removed} legacy notify settings entries from ${settingsPath}`);
+    }
+    return allReadable;
+}
+function migrateLegacyNotifyConfig(opts) {
+    const scope = opts.scope ?? "project";
+    const cwd = installTargetCwd(opts);
+    const home = os.homedir();
+    const legacyBase = scope === "user" ? home : cwd;
+    const legacyDir = path.join(legacyBase, ".claude", "hooks", "notify");
+    const destDir = scope === "user"
+        ? path.join(home, ".config", "auriga-cli", "notify")
+        : path.join(cwd, ".claude", "auriga-notify");
+    const copiedConfig = copyIfPresentWithoutOverwrite(path.join(legacyDir, "config.json"), path.join(destDir, "config.json"));
+    const copiedIcon = copyIfPresentWithoutOverwrite(path.join(legacyDir, "icon.png"), path.join(destDir, "icon.png"));
+    if (copiedConfig)
+        emitMigrationLog(opts, `migrated legacy notify config to ${path.join(destDir, "config.json")}`);
+    if (copiedIcon)
+        emitMigrationLog(opts, `migrated legacy notify icon to ${path.join(destDir, "icon.png")}`);
+    const settingsPaths = scope === "user"
+        ? [path.join(home, ".claude", "settings.json")]
+        : [
+            path.join(cwd, ".claude", "settings.json"),
+            path.join(cwd, ".claude", "settings.local.json"),
+        ];
+    const settingsCleaned = cleanLegacyNotifySettings(settingsPaths, opts);
+    if (settingsCleaned && fs.existsSync(legacyDir)) {
+        fs.rmSync(legacyDir, { recursive: true, force: true });
+        emitMigrationLog(opts, `removed legacy notify hook directory ${legacyDir}`);
+    }
+    else if (!settingsCleaned && fs.existsSync(legacyDir)) {
+        emitMigrationLog(opts, `kept legacy notify hook directory because settings cleanup was incomplete: ${legacyDir}`);
+    }
+}
+function runPostInstallMigration(pluginName, opts, runtimes) {
+    if (pluginName === WORKFLOW_SKILLS_PLUGIN_NAME) {
+        cleanupMigratedWorkflowSkillInstalls(opts, runtimes);
+    }
+    if (pluginName === NOTIFY_PLUGIN_NAME) {
+        migrateLegacyNotifyConfig(opts);
+    }
+}
 function codexMarketplaceAddCommand(packageRoot) {
     if (process.env.DEV === "1") {
         return `codex plugin marketplace add ${shellQuote(packageRoot)}`;
@@ -401,6 +572,7 @@ async function installCodexPlugins(packageRoot, opts) {
         enableCodexPluginConfig(path.join(codexHome(), "config.toml"), pluginKeys, needsPluginHooks);
         for (const plugin of [...localSelected, ...externalSelected]) {
             log.ok(`${plugin.name} enabled for Codex`);
+            runPostInstallMigration(plugin.name, opts, ["codex"]);
         }
     }
     if (failures.length > 0 && !opts.interactive) {
@@ -490,10 +662,11 @@ export async function installPlugins(packageRoot, opts) {
                     choices: config.plugins.map((p) => {
                         const scopes = installed.get(p.package);
                         const suffix = scopes ? ` (installed: ${scopes.join(", ")})` : "";
+                        const installedEverywhere = scopes?.includes("user") && scopes?.includes("project");
                         return {
                             name: `${p.name} — ${p.description}${suffix}`,
                             value: p,
-                            checked: !scopes || !(scopes.includes("user") && scopes.includes("project")),
+                            checked: p.defaultOn !== false && !installedEverywhere,
                         };
                     }),
                 }))
@@ -572,14 +745,16 @@ export async function installPlugins(packageRoot, opts) {
                 console.log(`\nInstalling ${plugin.name}...`);
                 try {
                     const cmd = `claude plugins install ${plugin.package} --scope ${scope}`;
+                    const cmdOpts = { cwd: installTargetCwd(opts) };
                     if (opts.onLog) {
                         opts.onLog(`▸ ${cmd}`, "stdout");
-                        await execAsync(cmd, { onLine: opts.onLog });
+                        await execAsync(cmd, { ...cmdOpts, onLine: opts.onLog });
                     }
                     else {
-                        exec(cmd, { inherit: true });
+                        exec(cmd, { ...cmdOpts, inherit: true });
                     }
                     log.ok(`${plugin.name} installed`);
+                    runPostInstallMigration(plugin.name, { ...opts, scope }, ["claude"]);
                 }
                 catch {
                     log.error(`Failed to install: ${plugin.name}`);

package/dist/scan-catalog.js

@@ -1,53 +1,20 @@
 // Build the scan-time Catalog (the shape src/state.ts consumes) from the
-// build-time `dist/catalog.json`. This module is intentionally a *thin
-// adapter* — it must NOT read any file outside `dist/catalog.json`, because
-// the npm tarball's `files` field allowlists only `dist/`. Reading from
-// `packageRoot/CLAUDE.md`, `packageRoot/.claude/plugins.json`, or
-// `packageRoot/.agents/skills/<name>/SKILL.md` succeeds in dev (where
-// packageRoot === repoRoot) but silently returns empty for npm-installed
-// users, leaving the scanner unable to surface real update signals.
-//
-// Anything the scanner needs beyond what's already in catalog.json must
-// first be baked at build time in `src/build/generate-catalog.ts`.
-//
-// Scope of the current bake (covered fields):
-//   - workflowVersion         — from CLAUDE.md header
-//   - plugin agents map       — from .claude/plugins.json ∪ .agents/plugins/install.json
-//   - plugin expectedVersion  — from plugins/<name>/.claude-plugin/plugin.json
-//   - plugin external flag    — derived (no in-tree manifest = external)
-//
-// Out of scope for v1.18.4 (follow-up PRs):
-//   - hook expectedEvent / expectedMatcher / expectedIf (from .claude/hooks/hooks.json)
-//   - apply-time installer config (the install path reads .claude/plugins.json
-//     directly — that needs runWebUi → fetchContentRoot rewire, not bake).
-import { readFile } from "node:fs/promises";
-import path from "node:path";
+// build-time `dist/catalog.json`. Thin adapter — reads dist/catalog.json
+// only. v1.19.0 dropped all version / hash / event comparison from the
+// scanner, so the build-time catalog is reduced to {description, agents?,
+// external?} per entry; runtime reads outside dist/ are no longer needed.
 import { loadCatalog } from "./catalog.js";
-async function tryReadFile(p) {
-    try {
-        return await readFile(p, "utf8");
-    }
-    catch {
-        return null;
-    }
-}
 export async function buildScanCatalog(packageRoot) {
     const dist = loadCatalog(packageRoot);
-    // Workflow version — baked from CLAUDE.md header at build time. See
-    // module comment for the "no runtime reads outside dist/" rule.
-    const workflowVersion = dist.workflowVersion ?? "";
-    // Skills: drift detection deliberately deferred to `npx skills update
-    // --project`, which already compares against the skill's own upstream
-    // repo HEAD. Our catalog snapshot would only know "what auriga-cli
-    // shipped at this CLI release" — at best a stale proxy that mis-reports
-    // legitimate user-side updates as drift. Setting expectedHash to "" puts
-    // classifySkillByFile into wildcard mode: row reports installed if
-    // SKILL.md exists, not-installed otherwise; never update-available.
+    // v1.19.0 dropped update-available status. The scanner is now presence-
+    // only: skills / hooks / plugins / workflow all report installed iff their
+    // truth source exists, not-installed otherwise. No version / hash / event
+    // comparison happens, so the build-time catalog is reduced to the bare
+    // {description, agents?, external?} shape per entry.
     const skills = {};
     for (const entry of dist.workflowSkills) {
         skills[entry.name] = {
             description: entry.description,
-            expectedHash: "",
             isWorkflow: true,
         };
     }
@@ -55,16 +22,8 @@ export async function buildScanCatalog(packageRoot) {
     for (const entry of dist.recommendedSkills) {
         recommendedSkills[entry.name] = {
             description: entry.description,
-            expectedHash: "",
         };
     }
-    // Plugins: agents + expectedVersion + external all come from
-    // dist/catalog.json now (baked in src/build/generate-catalog.ts). The
-    // previous version of this module read .claude/plugins.json +
-    // .agents/plugins/install.json at runtime — those files are NOT in the
-    // npm tarball, so for installed users every plugin defaulted to a
-    // ["claude"] agent classification (root cause of dual-Agent plugin
-    // mis-classification in v1.18.x).
     const plugins = {};
     for (const entry of dist.plugins) {
         const agents = Array.isArray(entry.agents) && entry.agents.length > 0
@@ -73,47 +32,12 @@ export async function buildScanCatalog(packageRoot) {
         plugins[entry.name] = {
             description: entry.description,
             agents,
-            ...(typeof entry.expectedVersion === "string" && entry.expectedVersion.length > 0
-                ? { expectedVersion: entry.expectedVersion }
-                : {}),
             ...(entry.external === true ? { external: true } : {}),
         };
     }
-    // Hooks: TODO follow-up — bake expectedEvent / expectedMatcher / expectedIf
-    // into dist/catalog.json the same way agents are baked. Currently the
-    // runtime read of packageRoot/.claude/hooks/hooks.json works in dev
-    // (packageRoot === repoRoot) but fails silently for npm-installed users
-    // — `package.json` `files` allowlist doesn't ship `.claude/`. So hook
-    // drift detection is correct in dev and degraded (always "installed" if
-    // marker present) in production. Follow-up bake closes the dev/prod gap.
-    const hooksJsonPath = path.join(packageRoot, ".claude", "hooks", "hooks.json");
-    const hooksJsonRaw = await tryReadFile(hooksJsonPath);
-    const hooksJson = hooksJsonRaw ? JSON.parse(hooksJsonRaw) : {};
-    const settingsEventsByName = new Map();
-    for (const h of hooksJson.hooks ?? []) {
-        if (typeof h.name === "string" && h.settingsEvents?.length) {
-            settingsEventsByName.set(h.name, h.settingsEvents[0]);
-        }
-    }
     const hooks = {};
     for (const entry of dist.hooks) {
-        const ev = settingsEventsByName.get(entry.name);
-        hooks[entry.name] = {
-            description: entry.description,
-            // Empty expectedHash flips state.ts into wildcard mode — drift judged
-            // purely from the structured expected* fields below, not from a
-            // settings-entry content hash.
-            expectedHash: "",
-            ...(typeof ev?.event === "string" ? { expectedEvent: ev.event } : {}),
-            ...(typeof ev?.matcher === "string" ? { expectedMatcher: ev.matcher } : {}),
-            ...(typeof ev?.if === "string" ? { expectedIf: ev.if } : {}),
-        };
+        hooks[entry.name] = { description: entry.description };
     }
-    return {
-        workflowVersion,
-        skills,
-        recommendedSkills,
-        plugins,
-        hooks,
-    };
+    return { skills, recommendedSkills, plugins, hooks };
 }

package/dist/server.js

@@ -171,7 +171,7 @@ const VALID_CATEGORIES = new Set([
     "plugin",
     "hook",
 ]);
-const VALID_ACTIONS = new Set(["install", "update", "uninstall"]);
+const VALID_ACTIONS = new Set(["install", "uninstall"]);
 const VALID_SCOPES = new Set(["project", "user"]);
 const VALID_LANGS = new Set(["en", "zh-CN"]);
 function parseApplyRequest(raw) {

package/dist/skills.js

@@ -8,12 +8,9 @@ import { atomicWriteFile, exec, execAsync, log, withEsc } from "./utils.js";
 // installRecommendedSkills as an opt-in utility.
 export const WORKFLOW_SKILLS = [
     "brainstorming",
-    "incremental-impl",
     "planning-with-files",
     "playwright-cli",
-    "session-compound",
     "systematic-debugging",
-    "test-designer",
     "test-driven-development",
     "verification-before-completion",
 ];

package/dist/state.d.ts

@@ -1,57 +1,37 @@
 import type { PluginState, ScanScope, StateReport } from "./api-types.js";
 export interface Catalog {
-    workflowVersion: string;
     skills: Record<string, {
         description: string;
-        expectedHash: string;
         isWorkflow: boolean;
     }>;
     recommendedSkills: Record<string, {
         description: string;
-        expectedHash: string;
     }>;
     plugins: Record<string, {
         description: string;
         /** Agents this plugin can install into. Length 1 or 2. */
         agents: ("claude" | "codex")[];
-        expectedVersion?: string;
-        /** When true, this plugin is published in an UPSTREAM marketplace
-         *  (skill-creator / claude-md-management / codex), not in this repo.
-         *  Classifier MUST NOT report `update-available` for external plugins —
-         *  those upgrade through `claude plugins update`, not us. The UI surfaces
-         *  an EXTERNAL badge so users know to defer to the upstream tool. */
+        /** True for plugins whose source lives in an upstream marketplace
+         *  (skill-creator / claude-md-management / codex). Drives the UI's
+         *  EXTERNAL badge — upgrades go through `claude plugins update`, not us.
+         *  Pure UI hint since v1.19.0 (used to also gate update-available
+         *  reporting; that surface was removed). */
         external?: boolean;
     }>;
     hooks: Record<string, {
         description: string;
-        /** Coarse drift signal. The current production scan-catalog still
-         *  populates this with sha256(index.mjs) for back-compat with the v0.x
-         *  scanner that hashed the user's installed script. The new
-         *  settings.json-based scanner ignores it for drift comparison unless
-         *  the catalog also exposes the structured expected* fields below. */
-        expectedHash: string;
-        /** Settings.json event name (e.g. "PostToolUse", "Notification"). When
-         *  set, the scanner flags drift if the on-disk settings entry registers
-         *  under a different event. Optional; left undefined the scanner trusts
-         *  whatever event the marker was found under. */
-        expectedEvent?: string;
-        /** Settings.json `matcher` field (e.g. "Write|Edit" for PostToolUse).
-         *  Empty string means "no matcher" (e.g. Notification hooks). When set,
-         *  the scanner flags drift if the on-disk value differs. */
-        expectedMatcher?: string;
-        /** Settings.json `if` field (Claude-Code-specific filter expression).
-         *  Same drift semantics as expectedMatcher. */
-        expectedIf?: string;
     }>;
 }
 export interface ScanOptions {
     /** Run `claude plugins list` for the given scope. The scope argument is
      *  required so server.ts can pass --user / --project through to the CLI
      *  per opts.scopes.plugins. Implementations may accept a zero-arg legacy
-     *  form for back-compat but MUST honor a scope argument when given. */
+     *  form for back-compat but MUST honor a scope argument when given.
+     *
+     *  Returns just the installed records — v1.19.0 dropped the parallel
+     *  `--available` fetch since the scanner no longer compares versions. */
     execPluginList?: (scope: ScanScope) => Promise<{
         installed: any[];
-        available: any[];
     }>;
     readCodexConfig?: () => Promise<string | null>;
     readCodexPluginsDir?: () => Promise<Map<string, string>>;
@@ -73,13 +53,14 @@ export interface ScanOptions {
 export declare function scanState(projectRoot: string, catalog: Catalog, opts?: ScanOptions): Promise<StateReport>;
 export declare function mergePluginsById(records: PluginState[]): PluginState[];
 /** Default: run `claude plugins list --json` (no scope flag — the CLI
- *  doesn't expose one) plus the `--available` variant, then filter the
- *  installed records to the requested scope (and current projectRoot for
- *  project-scope) client-side. Server.ts decides whether to pass this
- *  function based on `which claude`. */
+ *  doesn't expose one), then filter the installed records to the requested
+ *  scope (and current projectRoot for project-scope) client-side. Server.ts
+ *  decides whether to pass this function based on `which claude`.
+ *
+ *  v1.19.0 dropped the parallel `--available` fetch — the scanner no longer
+ *  compares versions, so there's no use for the upstream-live ref. */
 export declare function defaultExecPluginList(scope?: ScanScope, projectRoot?: string): Promise<{
     installed: any[];
-    available: any[];
 }>;
 export declare function defaultReadCodexConfig(): Promise<string | null>;
 /** Walk `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`, returning