auriga-cli 1.18.0 → 1.18.2

package/dist/api-types.d.ts

@@ -1,4 +1,13 @@
 export type ItemStatus = "installed" | "update-available" | "not-installed";
+/**
+ * Per-category scan scope. Each category (workflow / skills / plugins / hooks)
+ * can be independently scanned in either user scope (~/.claude/, ~/.codex/)
+ * or project scope (<proj>/.claude/). The Web UI's per-column scope picker
+ * carries these through the `/api/state` query so the scanner reads the
+ * right truth source per category. Codex plugins are user-scope only by
+ * design and ignore this field.
+ */
+export type ScanScope = "user" | "project";
 export interface StateReport {
     /** Absolute path to the project the server was launched against. Surfaced
      *  in the UI's top bar so users know where Apply will write project-scope
@@ -16,6 +25,13 @@ export interface WorkflowState {
     status: ItemStatus;
     currentVersion?: string;
     expectedVersion: string;
+    /** Which scope the scanner read to produce this row. Reflects the scope
+     *  scanned, not where the file was found — e.g. when scope=user and
+     *  ~/.claude/CLAUDE.md is absent, observedScope is still "user". The
+     *  scanner ALWAYS sets this field at runtime; it is typed optional only
+     *  so the mergePluginsById regression helper (which carries over from the
+     *  pre-rewrite suite without an explicit scope) continues to compile. */
+    observedScope?: ScanScope;
 }
 export interface SkillState {
     name: string;
@@ -24,6 +40,8 @@ export interface SkillState {
     isWorkflow: boolean;
     currentHash?: string;
     expectedHash: string;
+    /** Scope the scanner read to produce this row. See WorkflowState comment. */
+    observedScope?: ScanScope;
 }
 export type ApplyAgent = "claude" | "codex";
 export interface PluginState {
@@ -41,6 +59,10 @@ export interface PluginState {
     currentVersion?: string;
     expectedVersion?: string;
     versionSource: "upstream-live" | "catalog";
+    /** Scope the scanner read to produce this row. Codex plugins are always
+     *  "user" (Codex has no project-scope plugin concept). See WorkflowState
+     *  comment on why this is typed optional. */
+    observedScope?: ScanScope;
 }
 export interface HookState {
     name: string;
@@ -48,9 +70,11 @@ export interface HookState {
     status: ItemStatus;
     currentHash?: string;
     expectedHash: string;
+    /** Scope the scanner read to produce this row. See WorkflowState comment. */
+    observedScope?: ScanScope;
 }
 export interface StateWarning {
-    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline";
+    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline" | "claude-code-not-installed" | "settings-unreadable" | "skill-malformed" | "workflow-unknown-version";
     message: string;
 }
 export type ApplyCategory = "workflow" | "skill" | "recommended-skill" | "plugin" | "hook";

package/dist/catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-12T11:46:16.926Z",
+  "generatedAt": "2026-05-12T13:41:34.719Z",
   "workflowSkills": [
     {
       "name": "brainstorming",

package/dist/cli.js

@@ -562,7 +562,12 @@ async function dispatchInstaller(category, packageRoot, opts) {
 // ---------------------------------------------------------------------------
 const UI_DEFAULT_PORT = 4747;
 const UI_PORT_RANGE = 10; // 4747..4756
-const UI_HEARTBEAT_TIMEOUT_MS = 15_000;
+// 2 minutes covers Chrome's "intensive throttling" of background tabs
+// (kicks in after ~5 min of being hidden, drops setInterval to ~1 ping/min).
+// At 15s the browser tab being switched away for a moment would tear down
+// the server — bad UX. Closing the browser now takes up to 2 min to release
+// the port; users who care can ctrl+C the CLI for immediate exit.
+const UI_HEARTBEAT_TIMEOUT_MS = 120_000;
 async function runUi(p, version) {
     // Lazy-load the server-side deps so the install / guide paths stay light.
     const { randomBytes } = await import("node:crypto");

package/dist/scan-catalog.js

@@ -8,7 +8,9 @@
 //   skills-lock.json      — expected SHA256 for every vendored skill
 //   .claude/plugins.json  — Claude plugin entries (agent = "claude")
 //   .agents/plugins/install.json — Codex plugin entries (agent = "codex")
-//   .claude/hooks/<name>/index.mjs — runtime SHA256 = expected hash
+//   .claude/hooks/hooks.json — registers settingsEvents per hook (event /
+//                           matcher / if) used by state.ts for drift
+//                           detection in <scope>/.claude/settings.json
 //   CLAUDE.md             — `# auriga Workflow (vX.Y.Z)` provides
 //                           workflowVersion
 //
@@ -20,6 +22,39 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { loadCatalog } from "./catalog.js";
+async function sha256SkillMd(skillsRoot, name) {
+    try {
+        const buf = await readFile(path.join(skillsRoot, name, "SKILL.md"));
+        return createHash("sha256").update(buf).digest("hex");
+    }
+    catch {
+        return "";
+    }
+}
+/** Read `plugins/<name>/.claude-plugin/plugin.json` (or `.codex-plugin/plugin.json`
+ *  as fallback) and return the `version` field. Returns "" when no manifest
+ *  exists or the JSON is malformed — the scanner then leaves expectedVersion
+ *  unset, which means external-marketplace plugins (whose source lives
+ *  upstream, not in this repo) get the "trust installed" classification. */
+async function readPluginManifestVersion(packageRoot, name) {
+    const candidates = [
+        path.join(packageRoot, "plugins", name, ".claude-plugin", "plugin.json"),
+        path.join(packageRoot, "plugins", name, ".codex-plugin", "plugin.json"),
+    ];
+    for (const p of candidates) {
+        try {
+            const raw = await readFile(p, "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version === "string" && parsed.version.length > 0) {
+                return parsed.version;
+            }
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    return "";
+}
 const WORKFLOW_VERSION_RE = /^#\s*auriga Workflow\s*\(v([\d.]+)\)/m;
 async function tryReadFile(p) {
     try {
@@ -29,10 +64,6 @@ async function tryReadFile(p) {
         return null;
     }
 }
-async function sha256File(p) {
-    const bytes = await readFile(p);
-    return createHash("sha256").update(bytes).digest("hex");
-}
 export async function buildScanCatalog(packageRoot) {
     const dist = loadCatalog(packageRoot);
     // Workflow version: parse from auriga-cli's own CLAUDE.md template.
@@ -41,22 +72,18 @@ export async function buildScanCatalog(packageRoot) {
     const claudeMd = await tryReadFile(path.join(packageRoot, "CLAUDE.md"));
     const m = claudeMd ? WORKFLOW_VERSION_RE.exec(claudeMd) : null;
     const workflowVersion = m ? m[1] : "";
-    // Skills + recommended: hashes from skills-lock.json.
-    let lock = {};
-    const lockText = await tryReadFile(path.join(packageRoot, "skills-lock.json"));
-    if (lockText) {
-        try {
-            lock = JSON.parse(lockText);
-        }
-        catch {
-            // corrupted lock → no expectations; user state still classifies safely
-        }
-    }
+    // Skills + recommended: sha256 of each shipped SKILL.md. This is the same
+    // hash the scanner computes for `<scope>/.claude/skills/<name>/SKILL.md`
+    // at scan time, so a match means "user's installed copy is identical to
+    // the version auriga-cli ships". skills-lock.json's `computedHash` field
+    // hashes the entire skill directory (every file, sorted), which doesn't
+    // line up with the scanner's per-file model — we deliberately ignore it.
+    const skillsRoot = path.join(packageRoot, ".agents", "skills");
     const skills = {};
     for (const entry of dist.workflowSkills) {
         skills[entry.name] = {
             description: entry.description,
-            expectedHash: lock.skills?.[entry.name]?.computedHash ?? "",
+            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
             isWorkflow: true,
         };
     }
@@ -64,7 +91,7 @@ export async function buildScanCatalog(packageRoot) {
     for (const entry of dist.recommendedSkills) {
         recommendedSkills[entry.name] = {
             description: entry.description,
-            expectedHash: lock.skills?.[entry.name]?.computedHash ?? "",
+            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
         };
     }
     // Plugins: split by agent based on which config file lists them. A
@@ -111,22 +138,49 @@ export async function buildScanCatalog(packageRoot) {
             agents.push("codex");
         if (agents.length === 0)
             agents.push("claude"); // unknown defaults to claude
-        plugins[entry.name] = { description: entry.description, agents };
+        // Bake expectedVersion from the owned plugin's manifest. For Claude-side
+        // plugins prefer plugins/<name>/.claude-plugin/plugin.json; fall back to
+        // .codex-plugin/plugin.json for codex-only plugins (e.g.
+        // session-instructions-loader). External-marketplace plugins (skill-creator,
+        // claude-md-management, codex) have no local manifest — they install from
+        // their upstream marketplace, so we deliberately leave expectedVersion
+        // undefined. The scanner then falls through to "trust whatever is installed",
+        // which matches what the user agreed to when they registered the upstream.
+        const expectedVersion = await readPluginManifestVersion(packageRoot, entry.name);
+        plugins[entry.name] = {
+            description: entry.description,
+            agents,
+            ...(expectedVersion ? { expectedVersion } : {}),
+        };
+    }
+    // Hooks: the scanner reads <scope>/.claude/settings.json and matches by
+    // `_marker` (see state.ts scanHooks). Drift detection compares the
+    // registered event / matcher / if values against the hook's canonical
+    // settingsEvents[0] from .claude/hooks/hooks.json. We deliberately do NOT
+    // hash index.mjs — the user's installed index.mjs lives at <scope>/.claude/
+    // hooks/<name>/index.mjs and isn't part of the settings.json drift signal.
+    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]);
+        }
     }
-    // Hooks: runtime SHA256 of each hook's index.mjs serves as the expected
-    // hash. If the file can't be read, leave the expectation empty so the
-    // hook classifies as not-installed.
     const hooks = {};
     for (const entry of dist.hooks) {
-        const hookEntry = path.join(packageRoot, ".claude", "hooks", entry.name, "index.mjs");
-        let expectedHash = "";
-        try {
-            expectedHash = await sha256File(hookEntry);
-        }
-        catch {
-            /* missing or unreadable hook payload; leave hash empty */
-        }
-        hooks[entry.name] = { description: entry.description, expectedHash };
+        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 } : {}),
+        };
     }
     return {
         workflowVersion,

package/dist/server.js

@@ -7,13 +7,14 @@
 //
 // Public contract is anchored in docs/architecture/web-ui.md §4 (server
 // surface), §6 (data flow + types), §7 (errors).
+import { spawnSync } from "node:child_process";
 import { createServer } from "node:http";
 import { Buffer } from "node:buffer";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { buildScanCatalog } from "./scan-catalog.js";
-import { scanState } from "./state.js";
+import { defaultExecPluginList, scanState } from "./state.js";
 // Body parsing cap. /api/apply payloads are tiny (an array of item refs);
 // 1 MiB is generously above the largest realistic batch and small enough that
 // abusive clients can't pin memory.
@@ -576,7 +577,7 @@ export async function startServer(opts) {
             return;
         }
         if (pathname === "/api/state" && method === "GET") {
-            await routeState(opts.cwd, opts.packageRoot ?? opts.cwd, res);
+            await routeState(opts.cwd, opts.packageRoot ?? opts.cwd, searchParams, res);
             return;
         }
         if (pathname === "/api/apply" && method === "POST") {
@@ -705,10 +706,21 @@ export async function startServer(opts) {
 // ---------------------------------------------------------------------------
 // Route: GET /api/state
 // ---------------------------------------------------------------------------
-async function routeState(cwd, packageRoot, res) {
+async function routeState(cwd, packageRoot, searchParams, res) {
     try {
         const catalog = await buildScanCatalog(packageRoot);
-        const report = await scanState(cwd, catalog);
+        const scopes = parseScopesParam(searchParams);
+        // Only wire `defaultExecPluginList` if the `claude` CLI is on PATH —
+        // otherwise the scanner's degraded-path warning ("claude-cli-missing")
+        // is what we want the UI to surface. Cache the result per process so we
+        // don't re-`which` on every /api/state poll.
+        const execPluginList = isClaudeOnPath()
+            ? (scope) => defaultExecPluginList(scope, cwd)
+            : undefined;
+        const report = await scanState(cwd, catalog, {
+            ...(scopes ? { scopes } : {}),
+            ...(execPluginList ? { execPluginList } : {}),
+        });
         sendJson(res, 200, report);
     }
     catch {
@@ -717,6 +729,40 @@ async function routeState(cwd, packageRoot, res) {
         sendJson(res, 500, { error: "scan-failed" });
     }
 }
+let claudeOnPathCache = null;
+function isClaudeOnPath() {
+    if (claudeOnPathCache !== null)
+        return claudeOnPathCache;
+    const res = spawnSync("which", ["claude"], { stdio: "ignore" });
+    claudeOnPathCache = res.status === 0;
+    return claudeOnPathCache;
+}
+/**
+ * Parses the /api/state `scopes` query into a per-category map for
+ * `scanState`. The query string shape is comma-separated `category:scope`
+ * pairs, e.g. `?scopes=workflow:user,skills:project,plugins:user`. Unknown
+ * categories and unknown scope values are dropped (rather than throwing) so
+ * the scanner falls back to install defaults on garbled input — keeps the
+ * Web UI degraded-but-functional rather than 500-ing on a stale link.
+ *
+ * Returns `null` when the param is absent so the caller can omit `opts.scopes`
+ * entirely and let `scanState` apply its built-in defaults.
+ */
+function parseScopesParam(searchParams) {
+    const raw = searchParams.get("scopes");
+    if (!raw)
+        return null;
+    const allowedCategories = new Set(["workflow", "skills", "plugins", "hooks"]);
+    const allowedScopes = new Set(["user", "project"]);
+    const out = {};
+    for (const pair of raw.split(",")) {
+        const [cat, scope] = pair.split(":");
+        if (allowedCategories.has(cat) && allowedScopes.has(scope)) {
+            out[cat] = scope;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 // ---------------------------------------------------------------------------
 // Route: GET /api/catalog
 // ---------------------------------------------------------------------------

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import type { PluginState, StateReport } from "./api-types.js";
+import type { PluginState, ScanScope, StateReport } from "./api-types.js";
 export interface Catalog {
     workflowVersion: string;
     skills: Record<string, {
@@ -18,16 +18,51 @@ export interface Catalog {
     }>;
     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 {
-    execPluginList?: () => Promise<{
+    /** 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. */
+    execPluginList?: (scope: ScanScope) => Promise<{
         installed: any[];
         available: any[];
     }>;
     readCodexConfig?: () => Promise<string | null>;
     readCodexPluginsDir?: () => Promise<Map<string, string>>;
+    /** Per-category scope picker. Each field is independently routed to the
+     *  right truth source. Defaults match the Web UI's per-column picker:
+     *    workflow = 'project', skills = 'project',
+     *    plugins  = 'user',    hooks  = 'user'. */
+    scopes?: {
+        workflow?: ScanScope;
+        skills?: ScanScope;
+        plugins?: ScanScope;
+        hooks?: ScanScope;
+    };
+    /** Test-time HOME override. When unset the scanner reads os.homedir()
+     *  (which itself consults process.env.HOME / USERPROFILE), so tests that
+     *  redirect HOME via env vars also work. */
+    homeDir?: string;
 }
 export declare function scanState(projectRoot: string, catalog: Catalog, opts?: ScanOptions): Promise<StateReport>;
 /**
@@ -48,10 +83,12 @@ export declare function scanState(projectRoot: string, catalog: Catalog, opts?:
  * we'll need a deliberate merge policy.
  */
 export declare function mergePluginsById(records: PluginState[]): PluginState[];
-/** Default: run `claude plugins list --json` and `claude plugins list
- *  --available --json`. Returns null is NOT an option here — server.ts
- *  decides whether to pass this function based on `which claude`. */
-export declare function defaultExecPluginList(): Promise<{
+/** 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`. */
+export declare function defaultExecPluginList(scope?: ScanScope, projectRoot?: string): Promise<{
     installed: any[];
     available: any[];
 }>;

package/dist/state.js

@@ -1,9 +1,19 @@
-// scanState — read the user's project + (optionally) live CLIs to produce
-// a tri-state report per category. Pure-ish: all external I/O is either
-// injected via `ScanOptions` (for tests) or done through the default
-// filesystem / child-process implementations declared at the bottom of
-// this file. See docs/architecture/web-ui.md §6.3 + §10.4 for the judgment rules
-// and tests/state.test.ts for the full behavioral contract.
+// scanState — produce a tri-state install report (installed / update-available /
+// not-installed) for every category, reading the *actual* Claude Code install
+// locations rather than auriga-cli's own dev-repo layout. The truth sources
+// (per docs/specs/web-ui-scanner-redesign.md):
+//
+//   Workflow:  ~/.claude/CLAUDE.md                          (user scope)
+//              <proj>/CLAUDE.md, fallback .claude/CLAUDE.md (project scope)
+//   Skills:    ~/.claude/skills/<name>/SKILL.md             (user scope)
+//              <proj>/.claude/skills/<name>/SKILL.md        (project scope)
+//   Plugins(Claude): execPluginList(scope) + settings.json enabledPlugins
+//   Plugins(Codex):  ~/.codex/config.toml + ~/.codex/plugins/cache (user only)
+//   Hooks:     <scope>/.claude/settings.json `hooks` segment, matched by _marker
+//
+// External I/O is either injected via ScanOptions (tests) or done through the
+// default implementations at the bottom of the file (server.ts production
+// wiring). See tests/state.test.ts for the full behavioral contract.
 import { createHash } from "node:crypto";
 import { exec as execCallback } from "node:child_process";
 import { promisify } from "node:util";
@@ -12,14 +22,19 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
+/** Wildcard sentinel for the catalog hook `expectedHash` field. A value
+ *  equal to this string (or the empty string) is treated as "no drift
+ *  expectation, trust marker presence" — useful when the catalog hasn't yet
+ *  been populated with a real settings-entry signature. The test suite uses
+ *  this sentinel explicitly (see tests/state.test.ts assumption A7). */
+const WILDCARD_EXPECTED_HASH = "any";
 /**
  * Shorten an absolute path by replacing the user's $HOME with `~`. Avoids
  * leaking the full username in screenshots and keeps the TopBar label
  * readable. Falls back to the original path when HOME is unset or the path
  * doesn't sit under it.
  */
-function homeReducedPath(p) {
-    const home = os.homedir();
+function homeReducedPath(p, home) {
     if (!home)
         return p;
     if (p === home)
@@ -30,19 +45,39 @@ function homeReducedPath(p) {
     }
     return p;
 }
+const DEFAULT_SCOPES = {
+    workflow: "project",
+    skills: "project",
+    plugins: "user",
+    hooks: "user",
+};
 export async function scanState(projectRoot, catalog, opts = {}) {
     const warnings = [];
-    const workflow = scanWorkflow(projectRoot, catalog);
-    const lock = readSkillsLock(projectRoot);
-    const skills = scanSkills(catalog.skills, lock);
-    const recommendedSkills = scanRecommendedSkills(catalog.recommendedSkills, lock);
-    const hooks = scanHooks(projectRoot, catalog.hooks);
+    const home = opts.homeDir ?? os.homedir();
+    const scopes = { ...DEFAULT_SCOPES, ...(opts.scopes ?? {}) };
+    const workflow = scanWorkflow(scopes.workflow, projectRoot, home, catalog, warnings);
+    const skills = scanSkills(scopes.skills, projectRoot, home, catalog.skills, 
+    /* recommended */ false, warnings);
+    const recommendedSkills = scanRecommendedSkills(scopes.skills, projectRoot, home, catalog.recommendedSkills, warnings);
+    const hooks = scanHooks(scopes.hooks, projectRoot, home, catalog.hooks, warnings);
     const claudePluginEntries = filterPluginsByAgent(catalog.plugins, "claude");
     const codexPluginEntries = filterPluginsByAgent(catalog.plugins, "codex");
-    const claudePlugins = await scanClaudePlugins(claudePluginEntries, opts.execPluginList, warnings);
+    const claudePlugins = await scanClaudePlugins(scopes.plugins, claudePluginEntries, opts.execPluginList, warnings);
     const codexPlugins = await scanCodexPlugins(codexPluginEntries, opts.readCodexConfig ?? defaultReadCodexConfig, opts.readCodexPluginsDir ?? defaultReadCodexPluginsDir, warnings);
+    // Aggregate `claude-code-not-installed`: emit ONCE if neither ~/.claude/
+    // nor <proj>/.claude/ exists, regardless of how many user-scope categories
+    // were scanned. We check after the per-category scans so we can detect the
+    // condition just once at the end.
+    if (!dirExists(path.join(home, ".claude")) && !dirExists(path.join(projectRoot, ".claude"))) {
+        if (!warnings.some((w) => w.code === "claude-code-not-installed")) {
+            warnings.push({
+                code: "claude-code-not-installed",
+                message: "No Claude Code install detected (~/.claude/ and <project>/.claude/ both absent). Install Claude Code first.",
+            });
+        }
+    }
     return {
-        cwd: homeReducedPath(projectRoot),
+        cwd: homeReducedPath(projectRoot, home),
         workflow,
         skills,
         recommendedSkills,
@@ -51,6 +86,14 @@ export async function scanState(projectRoot, catalog, opts = {}) {
         warnings,
     };
 }
+function dirExists(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Dedupe plugins by `id`, merging dual-Agent records into a single
  * multi-agent row. Aggregation rules:
@@ -106,81 +149,108 @@ function aggregateStatus(statuses) {
         return "not-installed";
     // Anything else — partial install, pending updates on any agent, mixed
     // — falls through to update-available so a single Apply backfills the
-    // missing pieces. This is the boundary the user asked for: "一边装一边
-    // 没装" surfaces as a yellow UPDATE pill rather than a misleading green.
+    // missing pieces.
     return "update-available";
 }
 // ---------------------------------------------------------------------------
 // Workflow
 // ---------------------------------------------------------------------------
 const WORKFLOW_HEADER_RE = /^#\s+auriga\s+Workflow\s*\(v(\d+\.\d+\.\d+)\)/;
-function scanWorkflow(projectRoot, catalog) {
+function workflowPathsForScope(scope, projectRoot, home) {
+    if (scope === "user") {
+        return [path.join(home, ".claude", "CLAUDE.md")];
+    }
+    // Project: <proj>/CLAUDE.md preferred, .claude/CLAUDE.md as fallback.
+    return [
+        path.join(projectRoot, "CLAUDE.md"),
+        path.join(projectRoot, ".claude", "CLAUDE.md"),
+    ];
+}
+function scanWorkflow(scope, projectRoot, home, catalog, warnings) {
     const expectedVersion = catalog.workflowVersion;
-    const claudeMdPath = path.join(projectRoot, "CLAUDE.md");
-    let content;
-    try {
-        content = fs.readFileSync(claudeMdPath, "utf8");
+    const candidates = workflowPathsForScope(scope, projectRoot, home);
+    let content = null;
+    for (const candidate of candidates) {
+        try {
+            content = fs.readFileSync(candidate, "utf8");
+            break;
+        }
+        catch {
+            // try next candidate
+        }
     }
-    catch {
-        return { status: "not-installed", expectedVersion };
+    if (content === null) {
+        return { status: "not-installed", expectedVersion, observedScope: scope };
     }
-    // Match the canonical header anywhere in the first few lines; the spec
-    // and tests put it on the first line, but tolerate leading blank lines /
-    // BOM by scanning every line until we either find a match or run out.
+    // Walk the first non-blank lines looking for the auriga header.
     for (const line of content.split(/\r?\n/)) {
         const m = WORKFLOW_HEADER_RE.exec(line);
         if (m) {
             const currentVersion = m[1];
-            const status = currentVersion === expectedVersion ? "installed" : "update-available";
-            return { status, expectedVersion, currentVersion };
+            // Empty expectedVersion means scan-catalog couldn't extract the
+            // shipped workflow's header (auriga-cli's own CLAUDE.md missing or
+            // malformed at build time). Trust the installed version rather than
+            // forcing a phantom "update-available" against the empty string.
+            const status = !expectedVersion || currentVersion === expectedVersion ? "installed" : "update-available";
+            return { status, expectedVersion, currentVersion, observedScope: scope };
         }
-        // Bail at the first non-blank line — the header must be a top heading.
         if (line.trim().length > 0)
             break;
     }
-    // File exists but no parseable header → assumption #1 in state.test.ts:
-    // prefer reinstall over false-positive "installed" with unknown version.
-    return { status: "not-installed", expectedVersion };
+    // CLAUDE.md exists but no recognizable auriga marker. Per spec degraded
+    // path: status remains "installed" (don't clobber user content on apply)
+    // and emit a workflow-unknown-version warning.
+    warnings.push({
+        code: "workflow-unknown-version",
+        message: `CLAUDE.md present but no auriga-workflow header found; cannot determine installed version.`,
+    });
+    return { status: "installed", expectedVersion, observedScope: scope };
 }
-/** Return the parsed lockfile, or null if absent / unparseable. The "null"
- *  path is the degraded mode: skills still show up as catalog rows but their
- *  `currentHash` is undefined and they are reported as not-installed. */
-function readSkillsLock(projectRoot) {
-    const lockPath = path.join(projectRoot, "skills-lock.json");
-    let text;
+// ---------------------------------------------------------------------------
+// Skills + recommendedSkills
+// ---------------------------------------------------------------------------
+function skillsRoot(scope, projectRoot, home) {
+    if (scope === "user")
+        return path.join(home, ".claude", "skills");
+    return path.join(projectRoot, ".claude", "skills");
+}
+/** Classify a single skill by reading its SKILL.md from the scope's skills
+ *  dir. Returns the status + (when readable) the on-disk content hash. The
+ *  `malformedSeen` set is mutated when a skill dir exists but SKILL.md is
+ *  missing/unreadable — the caller emits ONE skill-malformed warning per
+ *  scan. */
+function classifySkillByFile(name, expectedHash, rootDir, malformedSeen) {
+    const skillDir = path.join(rootDir, name);
+    const skillMd = path.join(skillDir, "SKILL.md");
+    let buf;
     try {
-        text = fs.readFileSync(lockPath, "utf8");
+        buf = fs.readFileSync(skillMd);
     }
     catch {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(text);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
+        // SKILL.md unreadable. Two sub-cases:
+        //   (a) skill dir also missing → simply not installed.
+        //   (b) skill dir present but SKILL.md missing → malformed; row stays
+        //       "installed" so the user can repair, plus a warning.
+        if (dirExists(skillDir)) {
+            malformedSeen.add(name);
+            return { status: "installed" };
         }
-        return null;
-    }
-    catch {
-        // Per state.test.ts "corrupt skills-lock" case: don't throw; degrade.
-        return null;
-    }
-}
-function classifySkill(expectedHash, lock, name) {
-    const entry = lock?.skills?.[name];
-    const currentHash = entry?.computedHash;
-    if (typeof currentHash !== "string" || currentHash.length === 0) {
         return { status: "not-installed" };
     }
-    if (currentHash === expectedHash) {
+    const currentHash = createHash("sha256").update(buf).digest("hex");
+    if (expectedHash === "" ||
+        expectedHash === WILDCARD_EXPECTED_HASH ||
+        currentHash === expectedHash) {
         return { status: "installed", currentHash };
     }
     return { status: "update-available", currentHash };
 }
-function scanSkills(catalogSkills, lock) {
+function scanSkills(scope, projectRoot, home, catalogSkills, _recommended, warnings) {
+    const rootDir = skillsRoot(scope, projectRoot, home);
+    const malformed = new Set();
     const out = [];
     for (const [name, entry] of Object.entries(catalogSkills)) {
-        const cls = classifySkill(entry.expectedHash, lock, name);
+        const cls = classifySkillByFile(name, entry.expectedHash, rootDir, malformed);
         out.push({
             name,
             description: entry.description,
@@ -188,21 +258,37 @@ function scanSkills(catalogSkills, lock) {
             isWorkflow: entry.isWorkflow,
             currentHash: cls.currentHash,
             expectedHash: entry.expectedHash,
+            observedScope: scope,
+        });
+    }
+    if (malformed.size > 0) {
+        warnings.push({
+            code: "skill-malformed",
+            message: `Skill directory present but SKILL.md missing or unreadable: ${[...malformed].join(", ")}`,
         });
     }
     return out;
 }
-function scanRecommendedSkills(catalogRec, lock) {
+function scanRecommendedSkills(scope, projectRoot, home, catalogRec, warnings) {
+    const rootDir = skillsRoot(scope, projectRoot, home);
+    const malformed = new Set();
     const out = [];
     for (const [name, entry] of Object.entries(catalogRec)) {
-        const cls = classifySkill(entry.expectedHash, lock, name);
+        const cls = classifySkillByFile(name, entry.expectedHash, rootDir, malformed);
         out.push({
             name,
             description: entry.description,
             status: cls.status,
-            isWorkflow: false, // recommended skills are by definition opt-in utilities
+            isWorkflow: false,
             currentHash: cls.currentHash,
             expectedHash: entry.expectedHash,
+            observedScope: scope,
+        });
+    }
+    if (malformed.size > 0) {
+        warnings.push({
+            code: "skill-malformed",
+            message: `Skill directory present but SKILL.md missing or unreadable: ${[...malformed].join(", ")}`,
         });
     }
     return out;
@@ -222,50 +308,63 @@ function parseRef(ref) {
     const m = /^v?(\d+\.\d+\.\d+(?:[-+][\w.]+)?)$/.exec(ref);
     return m ? m[1] : null;
 }
-async function scanClaudePlugins(entries, execPluginList, warnings) {
+async function scanClaudePlugins(scope, entries, execPluginList, warnings) {
     if (entries.length === 0)
         return [];
-    // Degraded path 1: no exec injected AND no default. We expose a default
-    // implementation below that wraps `claude plugins list --available --json`,
-    // but the test contract treats "execPluginList undefined" as "Claude CLI
-    // missing" — we honor that by NOT silently falling back to the default
-    // when the caller leaves it undefined. (server.ts will pass the default
-    // explicitly when it confirms `claude` is on PATH.)
+    // Degraded path 1: no exec injected. The default implementation runs
+    // `claude plugins list`; server.ts decides whether to pass it based on
+    // `which claude`. When undefined → assume `claude` is missing.
     if (!execPluginList) {
         warnings.push({
             code: "claude-cli-missing",
             message: "Claude CLI not available — plugin update detection disabled. Install `claude` to enable update checks.",
         });
-        return entries.map(([id, def]) => degradedClaudeRow(id, def));
+        return entries.map(([id, def]) => degradedClaudeRow(id, def, scope));
     }
     let payload;
     try {
-        payload = await execPluginList();
+        payload = await execPluginList(scope);
     }
     catch (err) {
         warnings.push({
             code: "claude-cli-missing",
             message: `Claude CLI plugin list failed: ${err.message}`,
         });
-        return entries.map(([id, def]) => degradedClaudeRow(id, def));
-    }
+        return entries.map(([id, def]) => degradedClaudeRow(id, def, scope));
+    }
+    // claude plugins list emits ids in `<plugin>@<marketplace>` form (e.g.
+    // `auriga-go@auriga-cli`). The auriga-cli catalog tracks plugins by bare
+    // name. Index both forms so lookups succeed regardless of which side the
+    // suffix is on. Same trick for availables — note that the `--available`
+    // payload uses `pluginId` rather than `id`, so accept both as the key.
+    const indexBoth = (map, item) => {
+        if (!item || typeof item !== "object")
+            return;
+        const key = typeof item.id === "string"
+            ? item.id
+            : typeof item.pluginId === "string"
+                ? item.pluginId
+                : null;
+        if (!key)
+            return;
+        map.set(key, item);
+        const at = key.indexOf("@");
+        if (at > 0)
+            map.set(key.slice(0, at), item);
+    };
     const installedById = new Map();
-    for (const item of payload.installed ?? []) {
-        if (item && typeof item.id === "string")
-            installedById.set(item.id, item);
-    }
+    for (const item of payload.installed ?? [])
+        indexBoth(installedById, item);
     const availableById = new Map();
-    for (const item of payload.available ?? []) {
-        if (item && typeof item.id === "string")
-            availableById.set(item.id, item);
-    }
+    for (const item of payload.available ?? [])
+        indexBoth(availableById, item);
     const out = [];
     for (const [id, def] of entries) {
-        out.push(classifyClaudePlugin(id, def, installedById.get(id), availableById.get(id)));
+        out.push(classifyClaudePlugin(id, def, installedById.get(id), availableById.get(id), scope));
     }
     return out;
 }
-function degradedClaudeRow(id, def) {
+function degradedClaudeRow(id, def, scope) {
     return {
         id,
         description: def.description,
@@ -273,10 +372,10 @@ function degradedClaudeRow(id, def) {
         agents: ["claude"],
         expectedVersion: def.expectedVersion,
         versionSource: "upstream-live",
+        observedScope: scope,
     };
 }
-function classifyClaudePlugin(id, def, installed, available) {
-    // Not installed at all — easy case.
+function classifyClaudePlugin(id, def, installed, available, scope) {
     if (!installed || typeof installed.version !== "string") {
         return {
             id,
@@ -285,39 +384,55 @@ function classifyClaudePlugin(id, def, installed, available) {
             agents: ["claude"],
             expectedVersion: typeof available?.source?.ref === "string" ? available.source.ref : def.expectedVersion,
             versionSource: "upstream-live",
+            observedScope: scope,
         };
     }
     const installedVersion = installed.version;
     const ref = available?.source?.ref;
     const normalizedAvailable = parseRef(typeof ref === "string" ? ref : undefined);
     const normalizedInstalled = parseRef(installedVersion);
-    // Fallback rule 1: installed version "unknown" → trust it's installed.
-    // Fallback rule 2: available.ref is a branch / non-semver → trust it.
-    // Fallback rule 3: available info is missing entirely → trust it (we know
-    //   it's installed, we just can't say if there's a newer one).
-    if (installedVersion === "unknown" ||
-        normalizedAvailable === null ||
-        !available) {
+    // Pick the comparison target. The marketplace-live ref wins when it's a
+    // parseable semver — that's the freshest signal. Otherwise fall back to
+    // the build-time-baked `def.expectedVersion` (populated from
+    // plugins/<name>/.claude-plugin/plugin.json by scan-catalog for owned
+    // plugins). Without the fallback, the common upgrade case is invisible:
+    // `claude plugins list --available --json` excludes already-installed
+    // plugins from `.available[]`, so for any plugin the user already has,
+    // `ref` is undefined and the scanner can't tell whether a newer version
+    // ships in the marketplace.
+    const hasLiveRef = normalizedAvailable !== null && typeof ref === "string";
+    const expectedRaw = hasLiveRef ? ref : def.expectedVersion;
+    const expectedNormalized = hasLiveRef
+        ? normalizedAvailable
+        : parseRef(def.expectedVersion);
+    const versionSource = hasLiveRef
+        ? "upstream-live"
+        : "catalog";
+    // Fallback rules (no comparable expected version, or unknown installed):
+    //   - installed version "unknown" → trust it's installed.
+    //   - effective expected is null (branch ref + no baked version) → trust installed.
+    if (installedVersion === "unknown" || expectedNormalized === null) {
         return {
             id,
             description: def.description,
             status: "installed",
             agents: ["claude"],
             currentVersion: installedVersion,
-            expectedVersion: typeof ref === "string" ? ref : def.expectedVersion,
-            versionSource: "upstream-live",
+            expectedVersion: expectedRaw,
+            versionSource,
+            observedScope: scope,
         };
     }
-    // Both sides comparable.
-    if (normalizedInstalled !== null && normalizedInstalled === normalizedAvailable) {
+    if (normalizedInstalled !== null && normalizedInstalled === expectedNormalized) {
         return {
             id,
             description: def.description,
             status: "installed",
             agents: ["claude"],
             currentVersion: installedVersion,
-            expectedVersion: typeof ref === "string" ? ref : undefined,
-            versionSource: "upstream-live",
+            expectedVersion: expectedRaw,
+            versionSource,
+            observedScope: scope,
         };
     }
     return {
@@ -326,8 +441,9 @@ function classifyClaudePlugin(id, def, installed, available) {
         status: "update-available",
         agents: ["claude"],
         currentVersion: installedVersion,
-        expectedVersion: typeof ref === "string" ? ref : undefined,
-        versionSource: "upstream-live",
+        expectedVersion: expectedRaw,
+        versionSource,
+        observedScope: scope,
     };
 }
 // ---------------------------------------------------------------------------
@@ -359,8 +475,6 @@ async function scanCodexPlugins(entries, readCodexConfig, readCodexPluginsDir, w
         enabledIds = parseCodexEnabledPluginIds(tomlContent);
     }
     catch {
-        // Corrupt TOML — surface a warning but keep classifying as not-installed
-        // for each catalog entry rather than dropping rows.
         warnings.push({
             code: "codex-cli-missing",
             message: "Codex config.toml is unparseable — treating no plugins as installed",
@@ -373,9 +487,36 @@ async function scanCodexPlugins(entries, readCodexConfig, readCodexPluginsDir, w
     catch {
         fsVersions = new Map();
     }
+    // Mirror the Claude side: catalog tracks bare names (e.g. "auriga-go") but
+    // ~/.codex/config.toml [plugins.*] sections and defaultReadCodexPluginsDir
+    // both emit `<plugin>@<marketplace>` keys (e.g. "auriga-go@auriga-cli").
+    // Without dual indexing every dual-Agent plugin reports `not-installed` on
+    // the Codex side, which `mergePluginsById` then folds into a permanent
+    // `update-available` even when both sides are genuinely installed.
+    const lookupEnabled = (catalogId) => {
+        if (enabledIds.has(catalogId))
+            return true;
+        for (const id of enabledIds) {
+            const at = id.indexOf("@");
+            if (at > 0 && id.slice(0, at) === catalogId)
+                return true;
+        }
+        return false;
+    };
+    const lookupFsVersion = (catalogId) => {
+        const direct = fsVersions.get(catalogId);
+        if (direct)
+            return direct;
+        for (const [id, v] of fsVersions) {
+            const at = id.indexOf("@");
+            if (at > 0 && id.slice(0, at) === catalogId)
+                return v;
+        }
+        return undefined;
+    };
     const out = [];
     for (const [id, def] of entries) {
-        out.push(classifyCodexPlugin(id, def, enabledIds.has(id), fsVersions.get(id)));
+        out.push(classifyCodexPlugin(id, def, lookupEnabled(id), lookupFsVersion(id)));
     }
     return out;
 }
@@ -387,6 +528,7 @@ function degradedCodexRow(id, def) {
         agents: ["codex"],
         expectedVersion: def.expectedVersion,
         versionSource: "catalog",
+        observedScope: "user",
     };
 }
 function classifyCodexPlugin(id, def, enabled, fsVersion) {
@@ -399,10 +541,9 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             agents: ["codex"],
             expectedVersion,
             versionSource: "catalog",
+            observedScope: "user",
         };
     }
-    // Enabled in config but missing from fs — assumption #2 row contract:
-    // row present, status is NOT "installed".
     if (!fsVersion) {
         return {
             id,
@@ -411,10 +552,9 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             agents: ["codex"],
             expectedVersion,
             versionSource: "catalog",
+            observedScope: "user",
         };
     }
-    // Compare fs version to catalog expectation. If catalog gives no
-    // expectedVersion, trust it as installed.
     if (!expectedVersion || fsVersion === expectedVersion) {
         return {
             id,
@@ -424,6 +564,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             currentVersion: fsVersion,
             expectedVersion,
             versionSource: "catalog",
+            observedScope: "user",
         };
     }
     return {
@@ -434,6 +575,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
         currentVersion: fsVersion,
         expectedVersion,
         versionSource: "catalog",
+        observedScope: "user",
     };
 }
 /** Return the set of plugin ids whose `[plugins."<id>"]` table has
@@ -454,75 +596,173 @@ function parseCodexEnabledPluginIds(tomlContent) {
     }
     return ids;
 }
-function readHooksConfig(projectRoot) {
-    const configPath = path.join(projectRoot, ".claude", "hooks", "hooks.json");
-    let text;
-    try {
-        text = fs.readFileSync(configPath, "utf8");
-    }
-    catch {
-        return { config: null, corrupt: false };
-    }
-    try {
-        const parsed = JSON.parse(text);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return { config: parsed, corrupt: false };
+// ---------------------------------------------------------------------------
+// Hooks — read from <scope>/.claude/settings.json `hooks` segment, matched by
+// `_marker` sentinel against catalog hook names. Settings.json shape (Claude
+// Code convention):
+//
+//   {
+//     "hooks": {
+//       "<EventName>": [
+//         {
+//           "matcher": "<pattern>",
+//           "if": "<optional Claude-Code filter>",
+//           "hooks": [
+//             { "type": "command", "command": "...", "_marker": "<name>" }
+//           ]
+//         }
+//       ]
+//     }
+//   }
+//
+// ---------------------------------------------------------------------------
+function settingsPathForScope(scope, projectRoot, home) {
+    if (scope === "user")
+        return path.join(home, ".claude", "settings.json");
+    return path.join(projectRoot, ".claude", "settings.json");
+}
+/** Walk every settings hook action, returning a map keyed by the action's
+ *  `_marker` sentinel value. Malformed sub-shapes are skipped silently. */
+function indexSettingsHooksByMarker(settings) {
+    const out = new Map();
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        return out;
+    const hooksSeg = settings.hooks;
+    if (!hooksSeg || typeof hooksSeg !== "object" || Array.isArray(hooksSeg))
+        return out;
+    for (const [event, blocks] of Object.entries(hooksSeg)) {
+        if (!Array.isArray(blocks))
+            continue;
+        for (const block of blocks) {
+            if (!block || typeof block !== "object" || Array.isArray(block))
+                continue;
+            const b = block;
+            const matcher = typeof b.matcher === "string" ? b.matcher : undefined;
+            const ifExpr = typeof b.if === "string" ? b.if : undefined;
+            const actions = b.hooks;
+            if (!Array.isArray(actions))
+                continue;
+            for (const action of actions) {
+                if (!action || typeof action !== "object" || Array.isArray(action))
+                    continue;
+                const a = action;
+                const marker = typeof a._marker === "string" ? a._marker : undefined;
+                if (!marker)
+                    continue;
+                out.set(marker, {
+                    event,
+                    matcher,
+                    ifExpr,
+                    command: typeof a.command === "string" ? a.command : undefined,
+                });
+            }
         }
-        return { config: null, corrupt: true };
-    }
-    catch {
-        return { config: null, corrupt: true };
     }
+    return out;
+}
+/** Compute a coarse sha256 signature over a settings hook entry's drift-
+ *  relevant fields (event, matcher, if). Used to fall back to a single-
+ *  field comparison when the catalog hasn't been upgraded to expose
+ *  structured expectedMatcher / expectedEvent / expectedIf. */
+function signatureForSettingsEntry(entry) {
+    const canonical = JSON.stringify({
+        event: entry.event,
+        matcher: entry.matcher ?? "",
+        if: entry.ifExpr ?? "",
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** Returns true when the catalog's expectedHash is a wildcard sentinel
+ *  (empty string or the literal "any" placeholder). Wildcard means "no
+ *  drift expectation for this hook — trust marker presence." */
+function isWildcardExpectedHash(expectedHash) {
+    return expectedHash === "" || expectedHash === WILDCARD_EXPECTED_HASH;
+}
+function detectHookDrift(catalogEntry, settingsEntry) {
+    // Preferred drift path: structured expectations from catalog.
+    if (typeof catalogEntry.expectedMatcher === "string" &&
+        (settingsEntry.matcher ?? "") !== catalogEntry.expectedMatcher) {
+        return true;
+    }
+    if (typeof catalogEntry.expectedEvent === "string" &&
+        settingsEntry.event !== catalogEntry.expectedEvent) {
+        return true;
+    }
+    if (typeof catalogEntry.expectedIf === "string" &&
+        (settingsEntry.ifExpr ?? "") !== catalogEntry.expectedIf) {
+        return true;
+    }
+    // Fallback drift signal via expectedHash. When the catalog hasn't been
+    // populated with structured expected* fields (yet), expectedHash doubles
+    // as a coarse signature: if non-empty and non-wildcard, the implementation
+    // computes its own signature over the settings entry and treats any
+    // divergence as drift. Production scan-catalog.ts can populate this with
+    // a real settings-entry signature; until then, an explicit non-wildcard
+    // placeholder in tests (e.g. "expected-new-matcher-signature") deliberately
+    // triggers drift since it can never equal a sha256 hex digest.
+    if (!isWildcardExpectedHash(catalogEntry.expectedHash)) {
+        const sig = signatureForSettingsEntry(settingsEntry);
+        if (sig !== catalogEntry.expectedHash)
+            return true;
+    }
+    return false;
 }
-function hashHookIndex(projectRoot, name) {
-    const indexPath = path.join(projectRoot, ".claude", "hooks", name, "index.mjs");
+function scanHooks(scope, projectRoot, home, catalogHooks, warnings) {
+    const settingsPath = settingsPathForScope(scope, projectRoot, home);
+    let settingsRaw = null;
+    let settingsErr = null;
     try {
-        const buf = fs.readFileSync(indexPath);
-        return createHash("sha256").update(buf).digest("hex");
+        settingsRaw = fs.readFileSync(settingsPath, "utf8");
     }
-    catch {
-        return undefined;
+    catch (err) {
+        if (err && err.code === "ENOENT") {
+            settingsErr = "absent";
+        }
+        else {
+            settingsErr = "unreadable";
+        }
     }
-}
-function scanHooks(projectRoot, catalogHooks) {
-    const { config } = readHooksConfig(projectRoot);
-    const registeredNames = new Set();
-    if (config?.hooks && Array.isArray(config.hooks)) {
-        for (const entry of config.hooks) {
-            if (entry && typeof entry.name === "string")
-                registeredNames.add(entry.name);
+    let parsed = null;
+    if (settingsRaw !== null) {
+        try {
+            parsed = JSON.parse(settingsRaw);
+        }
+        catch {
+            settingsErr = "unreadable";
+            parsed = null;
         }
     }
+    if (settingsErr === "unreadable") {
+        warnings.push({
+            code: "settings-unreadable",
+            message: `Settings file unreadable or corrupt JSON: ${settingsPath}`,
+        });
+    }
+    const byMarker = indexSettingsHooksByMarker(parsed);
     const out = [];
     for (const [name, def] of Object.entries(catalogHooks)) {
-        if (!registeredNames.has(name)) {
+        const settingsEntry = byMarker.get(name);
+        if (!settingsEntry) {
             out.push({
                 name,
                 description: def.description,
                 status: "not-installed",
                 expectedHash: def.expectedHash,
+                observedScope: scope,
             });
             continue;
         }
-        const currentHash = hashHookIndex(projectRoot, name);
-        if (currentHash === undefined) {
-            // Registered but index.mjs missing — assumption #2: row present, not
-            // "installed", currentHash undefined so the UI can prompt repair.
-            out.push({
-                name,
-                description: def.description,
-                status: "not-installed",
-                expectedHash: def.expectedHash,
-            });
-            continue;
-        }
-        const status = currentHash === def.expectedHash ? "installed" : "update-available";
+        const drift = detectHookDrift(def, settingsEntry);
         out.push({
             name,
             description: def.description,
-            status,
-            currentHash,
+            status: drift ? "update-available" : "installed",
+            // Surface a coarse current signature so the UI can show diff details
+            // if it wants. The exact format is "sha256 of normalized settings
+            // entry" — opaque to the UI, used only for drift detection.
+            currentHash: signatureForSettingsEntry(settingsEntry),
             expectedHash: def.expectedHash,
+            observedScope: scope,
         });
     }
     return out;
@@ -531,20 +771,45 @@ function scanHooks(projectRoot, catalogHooks) {
 // Default external-I/O implementations (used when ScanOptions are not
 // injected — server.ts wires these up in production).
 // ---------------------------------------------------------------------------
-/** Default: run `claude plugins list --json` and `claude plugins list
- *  --available --json`. Returns null is NOT an option here — server.ts
- *  decides whether to pass this function based on `which claude`. */
-export async function defaultExecPluginList() {
+/** 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`. */
+export async function defaultExecPluginList(scope = "user", projectRoot) {
     // Run both lookups in parallel via async exec so /api/state doesn't block
     // the event loop. `claude plugins list` can take several seconds on cold
     // marketplace fetches; sync exec would freeze heartbeats and other
-    // concurrent /api requests.
+    // concurrent /api requests. Note: `claude plugins list` does NOT support
+    // `--user` / `--project`; each record carries its own `scope` field which
+    // we filter on below.
     const [installedRes, availableRes] = await Promise.all([
-        execAsync("claude plugins list --json", { encoding: "utf8" }),
-        execAsync("claude plugins list --available --json", { encoding: "utf8" }),
+        execAsync(`claude plugins list --json`, { encoding: "utf8" }),
+        execAsync(`claude plugins list --available --json`, { encoding: "utf8" }),
     ]);
-    const installed = parseJsonArray(installedRes.stdout);
-    const available = parseJsonArray(availableRes.stdout);
+    const allInstalled = parseJsonArray(installedRes.stdout);
+    // `claude plugins list --available --json` returns a wrapped object
+    // `{ installed: [...], available: [...] }`, NOT a flat array. parseJsonArray
+    // alone would return `[]` and silently lose every marketplace ref → the
+    // scanner could never surface "update-available" from upstream-live data.
+    // Pull `.available` out of the wrapper; tolerate the flat-array form too
+    // in case Claude CLI's shape regresses.
+    const available = extractAvailableArray(availableRes.stdout);
+    const installed = allInstalled.filter((rec) => {
+        if (!rec || typeof rec !== "object")
+            return false;
+        if (rec.scope !== scope)
+            return false;
+        // Project-scope records may match multiple projects (`projectPath`
+        // differs). If projectRoot was provided, narrow to records bound to
+        // the current cwd. When omitted, fall back to "any project-scope
+        // record" — better than dropping all project records on a malformed
+        // call.
+        if (scope === "project" && projectRoot && typeof rec.projectPath === "string") {
+            return path.resolve(rec.projectPath) === path.resolve(projectRoot);
+        }
+        return true;
+    });
     return { installed, available };
 }
 function parseJsonArray(text) {
@@ -556,6 +821,24 @@ function parseJsonArray(text) {
         return [];
     }
 }
+/** Pull the available-plugins array out of `claude plugins list --available
+ *  --json`'s response. Empirically the CLI returns `{ installed, available }`;
+ *  if a future version regresses to a flat array we keep working. Returns
+ *  `[]` on malformed JSON. */
+function extractAvailableArray(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed && typeof parsed === "object" && Array.isArray(parsed.available)) {
+            return parsed.available;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
 function codexHome() {
     return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.18.0",
+  "version": "1.18.2",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
   "license": "MIT",
   "repository": {