@consiliency/agent-board-cli 1.25.0 → 1.27.0

package/dist/claude_marketplace.js

@@ -0,0 +1,306 @@
+// message-board#549 — the per-user Claude Code marketplace directory, shared by setup (which writes
+// it) and doctor (which judges it). ONE implementation of each rule, imported by both, so the two
+// cannot disagree about where the directory is, what "the same content" means, or which chain of
+// directories is trusted.
+//
+//   claudeMarketplaceDir   `${XDG_DATA_HOME}` if absolute, else `$HOME/.local/share`, then
+//                          `/agent-board/claude-marketplace`. Claude Code 2.1.283 stores a directory
+//                          marketplace path AS GIVEN (a trailing slash stripped, symlinks NOT
+//                          resolved: measured), so setup and doctor compare paths lexically after
+//                          `resolve()` under one env.
+//   readTree / sameTree    every regular file, relative path (always `/`-separated, on every OS) →
+//                          bytes and exec bit; a symlink, device, socket or FIFO anywhere inside makes
+//                          the tree unusable. Equal = same file set, same bytes, same exec bit.
+//   resolveTrustChain      (round 4: replaces the lexical + real-path chains) walks the path as the
+//                          kernel does, from `/`, one component at a time. Every directory ENTERED:
+//                            * the marketplace directory and its `agent-board` parent: a real
+//                              directory (never a symlink), owned by this uid, not group/world-
+//                              writable;
+//                            * every other: owned by this uid or root, and not group/world-writable,
+//                              except root-owned with the sticky bit (`/tmp`), or owned by this uid and
+//                              group-writable (never world) by the user's PRIVATE group, proven from
+//                              `/etc/group` AND `/etc/passwd` (stock Ubuntu/Fedora `~/.local` is 0775
+//                              `<user>:<user>`).
+//                          A symlink component: its own owner must be this uid or root, and its target
+//                          is spliced into the remaining components, so every hop's containing
+//                          directory is entered and judged. More than 40 links: a loop, refused.
+//                          A same-uid attacker is out of scope (SETUP ruling). On win32 there is no
+//                          uid (getuid() is -1) and no POSIX mode, so only the symlink rule applies.
+//   plugin versions        `pluginVersionIn` / `compareVersions`, shared by setup (never downgrade a
+//                          TRUSTED newer directory; an untrusted one is rebuilt) and doctor (report version skew).
+import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
+import { userInfo } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+/** The manifest's key in a tree read by `readTree`: always `/`-separated. */
+export const MARKETPLACE_MANIFEST_KEY = ".claude-plugin/marketplace.json";
+/** THE per-user directory setup materialises the packaged marketplace into. User and local scope share it. */
+export function claudeMarketplaceDir(env, home) {
+    const data = env.XDG_DATA_HOME;
+    const root = data !== undefined && data.trim() !== "" && isAbsolute(data) ? data : join(home, ".local", "share");
+    return join(root, "agent-board", "claude-marketplace");
+}
+/** A declared directory path is ours when it resolves to `claudeMarketplaceDir` for this env. */
+export function isOurMarketplacePath(path, env, home) {
+    return typeof path === "string" && isAbsolute(path) && resolve(path) === resolve(claudeMarketplaceDir(env, home));
+}
+/**
+ * Every regular file under `dir`. `missing` when `dir` does not exist; `unusable` when it is not a
+ * plain tree. With `trust` (the materialised directory, never the packaged copy, which a root-owned
+ * global install legitimately owns): every directory and file under `dir` must be owned by this uid
+ * and not group/world-writable, else `untrusted` naming the first offender — a hook another uid can
+ * rewrite is a hook another uid runs as you. Skipped on win32, as elsewhere.
+ */
+export function readTree(dir, trust) {
+    let top;
+    try {
+        top = lstatSync(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { kind: "missing" };
+        return { kind: "unusable" };
+    }
+    if (!top.isDirectory())
+        return { kind: "unusable" };
+    const files = new Map();
+    const judged = trust !== undefined && (trust.platform ?? process.platform) !== "win32";
+    let offender = null;
+    const untrusted = (path, stats) => {
+        if (!judged)
+            return false;
+        const owned = trust.lstat ? trust.lstat(path) : stats;
+        if (owned.uid === trust.uid && (owned.mode & 0o022) === 0)
+            return false;
+        offender = path;
+        return true;
+    };
+    const walk = (relative) => {
+        for (const name of readdirSync(relative === "" ? dir : join(dir, ...relative.split("/"))).sort()) {
+            const child = relative === "" ? name : `${relative}/${name}`;
+            const absolute = join(dir, ...child.split("/"));
+            const stats = lstatSync(absolute);
+            if ((stats.isDirectory() || stats.isFile()) && untrusted(absolute, stats))
+                return false;
+            if (stats.isDirectory()) {
+                if (!walk(child))
+                    return false;
+            }
+            else if (stats.isFile()) {
+                files.set(child, { bytes: readFileSync(absolute), executable: (stats.mode & 0o111) !== 0 });
+            }
+            else {
+                return false;
+            }
+        }
+        return true;
+    };
+    try {
+        if (walk(""))
+            return { kind: "ok", files };
+        return offender !== null ? { kind: "untrusted", path: offender } : { kind: "unusable" };
+    }
+    catch {
+        return { kind: "unusable" };
+    }
+}
+/** Same file set, same bytes, same exec bit. */
+export function sameTree(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [path, file] of a) {
+        const other = b.get(path);
+        if (!other || other.executable !== file.executable || !other.bytes.equals(file.bytes))
+            return false;
+    }
+    return true;
+}
+/** Symlinks followed before a path is refused as a loop (Linux's MAXSYMLINKS). */
+export const MAX_SYMLINK_HOPS = 40;
+const readOr = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The user's PRIVATE group (USERGROUPS_ENAB: Ubuntu, Debian, Fedora, RHEL make `~/.local` 0775 owned
+ * `<user>:<user>`). Proven only from the local files, and only when BOTH say no one else is in it:
+ *   * `/etc/group` has exactly one entry for the gid, named as the user, whose members are a subset
+ *     of {the user} (some tools list the user in their own group);
+ *   * `/etc/passwd` has exactly one account whose primary gid is that gid, and it is this user (name
+ *     AND uid) — two accounts sharing a primary gid share its write bit (round 4).
+ * The gid must also be this process's primary gid. An account or group only in NSS/LDAP, a shared
+ * group (SUSE `users`) or an unreadable file proves nothing: refused.
+ */
+export function isPrivateGroup(gid, options) {
+    const primary = options.gid ?? process.getgid?.();
+    let name = options.userName;
+    if (name === undefined) {
+        try {
+            name = userInfo().username;
+        }
+        catch {
+            return false;
+        }
+    }
+    const groupText = options.groupFile === undefined ? readOr("/etc/group") : options.groupFile;
+    const passwdText = options.passwdFile === undefined ? readOr("/etc/passwd") : options.passwdFile;
+    if (primary === undefined || gid !== primary || groupText === null || passwdText === null)
+        return false;
+    const rows = (text) => text.split("\n").map((line) => line.split(":"));
+    const groups = rows(groupText).filter((fields) => fields.length >= 4 && fields[2] !== "" && Number(fields[2]) === gid);
+    if (groups.length !== 1 || groups[0][0] !== name)
+        return false;
+    const members = groups[0][3].split(",").map((member) => member.trim()).filter(Boolean);
+    if (!members.every((member) => member === name))
+        return false;
+    const accounts = rows(passwdText).filter((fields) => fields.length >= 4 && fields[3] !== "" && Number(fields[3]) === gid);
+    return accounts.length === 1 && accounts[0][0] === name && Number(accounts[0][2]) === options.uid;
+}
+/**
+ * Round 4: ONE resolver, walking `dir` as the kernel does — from `/`, one component at a time. Every
+ * directory ENTERED is judged (the marketplace directory and its `agent-board` parent strictly; every
+ * other by the ancestor rules). A symlink component is judged by its own owner (its containing
+ * directory was judged when entered), and its `readlink` is spliced into the remaining components
+ * (absolute → from `/`, relative → from the current directory), so EVERY hop's containing
+ * directory is judged, however many hops there are. More than `MAX_SYMLINK_HOPS` links is a loop:
+ * refused. The walk stops at the first missing component: what setup will create. The marketplace
+ * directory and its parent are the last two components however the path is spliced, and neither may
+ * be a symlink. On win32 (no uid, no POSIX mode) only that symlink rule applies.
+ */
+export function resolveTrustChain(dir, options) {
+    const windows = (options.platform ?? process.platform) === "win32";
+    const lstat = options.lstat ?? ((path) => lstatSync(path));
+    const readlink = options.readlink ?? ((path) => readlinkSync(path));
+    const target = resolve(dir);
+    const visited = [];
+    const done = (problem) => ({ problem, visited });
+    if (windows) {
+        for (const path of [dirname(target), target]) {
+            try {
+                if (lstat(path).isSymbolicLink())
+                    return done({ path, cause: "symlink", tightenable: false });
+            }
+            catch {
+                break;
+            }
+        }
+        return done(null);
+    }
+    const ownedOrRoot = (stats) => stats.uid === options.uid || stats.uid === 0;
+    const judge = (path, stats, own) => {
+        const root = stats.uid === 0;
+        if (own ? stats.uid !== options.uid : !ownedOrRoot(stats))
+            return { path, cause: "foreign_owner", tightenable: false };
+        const worldWritable = (stats.mode & 0o002) !== 0;
+        const groupWritable = (stats.mode & 0o020) !== 0;
+        if (!worldWritable && !groupWritable)
+            return null;
+        if (!own && root && (stats.mode & 0o1000) !== 0)
+            return null; // /tmp
+        if (!own && !worldWritable && stats.uid === options.uid && isPrivateGroup(stats.gid, options))
+            return null;
+        return { path, cause: "writable", tightenable: own, command: `chmod ${worldWritable && groupWritable ? "go-w" : worldWritable ? "o-w" : "g-w"} ${path}` };
+    };
+    const enter = (path, role) => {
+        const stats = lstat(path);
+        if (!stats.isDirectory())
+            return { path, cause: "not_directory", tightenable: false };
+        const problem = judge(path, stats, role !== "ancestor");
+        if (problem)
+            return problem;
+        visited.push({ path, dev: stats.dev ?? -1, ino: stats.ino ?? -1, role });
+        return null;
+    };
+    const rootProblem = enter("/", "ancestor");
+    if (rootProblem)
+        return done(rootProblem);
+    let current = "/";
+    const queue = target.split("/").filter(Boolean);
+    let hops = 0;
+    while (queue.length > 0) {
+        const name = queue.shift();
+        // The tail is never spliced (a symlink there is refused), so the last two are always ours.
+        const role = queue.length === 0 ? "dir" : queue.length === 1 ? "parent" : "ancestor";
+        if (name === ".")
+            continue;
+        if (name === "..") {
+            current = dirname(current);
+            continue;
+        }
+        const path = current === "/" ? `/${name}` : `${current}/${name}`;
+        let link;
+        try {
+            link = lstat(path);
+        }
+        catch {
+            break; // missing from here down: what setup creates
+        }
+        if (link.isSymbolicLink()) {
+            if (role !== "ancestor")
+                return done({ path, cause: "symlink", tightenable: false });
+            if (!ownedOrRoot(link))
+                return done({ path, cause: "foreign_owner", tightenable: false });
+            if (++hops > MAX_SYMLINK_HOPS)
+                return done({ path, cause: "symlink_loop", tightenable: false });
+            let to;
+            try {
+                to = readlink(path);
+            }
+            catch {
+                return done({ path, cause: "not_directory", tightenable: false });
+            }
+            if (to.startsWith("/"))
+                current = "/";
+            queue.unshift(...to.split("/").filter(Boolean));
+            continue;
+        }
+        const problem = enter(path, role);
+        if (problem)
+            return done(problem);
+        current = path;
+    }
+    return done(null);
+}
+/** The first untrusted path, or null (see `resolveTrustChain`). */
+export function checkTrustChain(dir, options) {
+    return resolveTrustChain(dir, options).problem;
+}
+/** The human words for a trust problem, for a `fix`. */
+export function describeTrustProblem(problem) {
+    const words = {
+        symlink: "is a symlink",
+        not_directory: "is not a directory",
+        foreign_owner: "is owned by another user",
+        writable: "is writable by other users",
+        symlink_loop: `resolves through more than ${MAX_SYMLINK_HOPS} symlinks (a loop)`,
+    };
+    return `${problem.path} ${words[problem.cause]}${problem.command ? ` (run \`${problem.command}\`)` : ""}`;
+}
+/** The version in a marketplace tree's `plugins/agent-board/.claude-plugin/plugin.json`, or null. */
+export function pluginVersionIn(files) {
+    const file = files.get("plugins/agent-board/.claude-plugin/plugin.json");
+    if (!file)
+        return null;
+    try {
+        const version = JSON.parse(file.bytes.toString("utf8"))?.version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `x.y.z` numeric comparison (sign), or null when either side is not a plain release version. */
+export function compareVersions(a, b) {
+    const parse = (value) => (value !== null && /^\d+\.\d+\.\d+$/.test(value) ? value.split(".").map(Number) : null);
+    const x = parse(a);
+    const y = parse(b);
+    if (x === null || y === null)
+        return null;
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return Math.sign(x[i] - y[i]);
+    return 0;
+}

package/dist/doctor.d.ts

@@ -1,5 +1,5 @@
-import { type IdentityHarness, type OperationSuccess, type OsKeychainExec, type SessionRecordEntry, type TrustOptions } from "@consiliency/agent-board-client";
-import { type ClaudePluginSummary, type RegistrationFs, type RegQuery, type RegistrationVerdict } from "./doctor_scopes.js";
+import { type IdentityHarness, type OperationSuccess, type OsKeychainBackendOptions, type OsKeychainExec, type SessionRecordEntry, type TrustOptions } from "@consiliency/agent-board-client";
+import { type ClaudePluginSummary, type RegistrationFs, type RegQuery, type RegistrationVerdict, type ScopeContext } from "./doctor_scopes.js";
 export type DoctorStatus = "pass" | "fail" | "undetermined";
 export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime"];
 export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number];
@@ -17,6 +17,12 @@ export interface PluginReport {
     installed_version: string | null;
     pinned_mcp_version: string | null;
     source_ref: string | null;
+    /** `github` (the repo at a ref: fleet hosts) or `directory` (the per-user copy setup made, #549). */
+    source_kind: "github" | "directory" | null;
+    /** A directory source's path; only ever our derived per-user directory, printed if path-shaped. */
+    source_path: string | null;
+    /** Where `installed_version` and `pinned_mcp_version` were read: `source` (our validated directory) or `cache`. */
+    version_from: "source" | "cache" | null;
     auto_update: ClaudePluginSummary["autoUpdate"];
 }
 export interface DoctorReport {
@@ -41,6 +47,12 @@ export interface DoctorReport {
     };
 }
 export declare const REPORTABLE_TOKEN: RegExp;
+/**
+ * A path prints only when absolute and made of the token alphabet (no spaces, quotes or control
+ * characters), up to 1024 characters; else `unrecognised`. It is only ever doctor's own derived
+ * per-user directory (#549), never a string read from a file, but `$HOME` is still input.
+ */
+export declare const REPORTABLE_PATH: RegExp;
 /**
  * The two reads doctor makes, on a client whose credentials come from the identity file. Typed
  * as the client's own `OperationSuccess` envelope, so `defaultClient` below stops compiling if
@@ -85,6 +97,10 @@ export interface DoctorOptions {
     claudeManagedDir?: string;
     /** The OS whose managed (MDM) sources are probed. Default `process.platform`. */
     platform?: NodeJS.Platform;
+    /** The packaged marketplace our directory source must equal (#549). Default: this cli's own copy. */
+    claudeMarketplacePackaged?: string;
+    /** Test injection for the marketplace trust chain (`/etc/group`, gid, user name, ownership). */
+    claudeMarketplaceTrust?: ScopeContext["claudeMarketplaceTrust"];
     /** The login name for the macOS per-user managed plist. Default: `lookupUserName()`. */
     userName?: string;
     /** Where the login name comes from; may throw. Default `os.userInfo().username`. */
@@ -131,7 +147,7 @@ export declare function fileIdentityEnv(ambient: NodeJS.ProcessEnv, values: Reco
  * for the keychain CLI. Nothing here reads its output; doctor.test.ts K-0 pins that no
  * key-decoding API is reachable.
  */
-export declare function osKeychainProbe(spawn?: OsKeychainExec): KeystoreProbe;
+export declare function osKeychainProbe(spawn?: OsKeychainExec, where?: Pick<OsKeychainBackendOptions, "platform" | "homeDir">): KeystoreProbe;
 /** The default agent_socket probe: the loaded key's fingerprint, derived from the agent's identity list. */
 export declare const agentSocketProbe: KeystoreProbe;
 export declare const OS_KEYCHAIN_PRESENT = "present; key_id proven server-side by whoami; file fingerprint unverified for os_keychain";

package/dist/doctor.js

@@ -14,7 +14,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, readdirSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { join, resolve } from "node:path";
-import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, normalizeKeyReference, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
+import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, normalizeKeyReference, osKeychainFailureOf, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
 import { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
 import { resolveKeyslotDir } from "./assets.js";
 import { SLOT_RE, externalDeclarationProblems, fileIdentity, keyslotSocketDir, machineIdOf, resolveAgentSocketPath, unsealedOptinProblems, } from "./setup_storage.js";
@@ -22,6 +22,13 @@ export const DOCTOR_CHECKS = Object.freeze([
     "identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime",
 ]);
 export const REPORTABLE_TOKEN = /^[A-Za-z0-9._/-]{1,64}$/;
+/**
+ * A path prints only when absolute and made of the token alphabet (no spaces, quotes or control
+ * characters), up to 1024 characters; else `unrecognised`. It is only ever doctor's own derived
+ * per-user directory (#549), never a string read from a file, but `$HOME` is still input.
+ */
+export const REPORTABLE_PATH = /^\/[A-Za-z0-9._/-]{0,1023}$/;
+const reportablePath = (value) => value === null ? null : REPORTABLE_PATH.test(value) ? value : "unrecognised";
 const reportable = (value) => value === null ? null : REPORTABLE_TOKEN.test(value) ? value : "unrecognised";
 /**
  * The pin, over the live wake_producers whose cwd (realpath) is doctor's cwd, and only while our
@@ -36,6 +43,12 @@ function pinCheck(verdict, entries, cwd, fs) {
     const pin = verdict.plugin?.installed && verdict.plugin.serverActive ? verdict.plugin.version : null;
     if (pin === null)
         return verdict;
+    // Round 4: a directory-sourced plugin runs from its directory. When that directory was not read as
+    // the effective, sound source (newer, stale, untrusted, unverifiable), `pin` is cache metadata,
+    // which says nothing about what runs: no mismatch is declared from it. The directory's own reason
+    // already stands (fail or undetermined).
+    if (verdict.plugin?.sourceKind === "directory" && verdict.plugin.versionFrom !== "source")
+        return verdict;
     // Real paths on both sides (panel S2): a server records its physical cwd; doctor may be in a symlink.
     const real = (path) => fs.realpath(path) ?? resolve(path);
     const here = entries.flatMap((entry) => entry.status === "live" && entry.record.role === "wake_producer"
@@ -163,11 +176,11 @@ function defaultClient(fileEnv) {
  * for the keychain CLI. Nothing here reads its output; doctor.test.ts K-0 pins that no
  * key-decoding API is reachable.
  */
-export function osKeychainProbe(spawn) {
+export function osKeychainProbe(spawn, where = {}) {
     return async (keyReference) => {
         const reference = normalizeKeyReference(keyReference);
         try {
-            const capability = await createOsKeychainBackend(spawn ? { exec: spawn } : {})(reference);
+            const capability = await createOsKeychainBackend({ ...where, ...(spawn ? { exec: spawn } : {}) })(reference);
             await capability.sign(randomBytes(32));
             return { kind: "present_unverified" };
         }
@@ -177,6 +190,15 @@ export function osKeychainProbe(spawn) {
             if (error instanceof KeystoreUnavailableError && /no key found/.test(error.message)) {
                 return { kind: "absent", reason: "key_absent" };
             }
+            // #554: the client classifies a platform keychain failure. A key held only OUTSIDE the macOS
+            // login keychain is not usable (the adapter reads the login keychain) and is a fail; any other
+            // class is carried in the reason, so a locked keychain reads `keystore_unavailable:keychain_locked`
+            // (fix: `security unlock-keychain <login keychain>`) instead of the bare code.
+            const classified = osKeychainFailureOf(error);
+            if (classified?.failure === "item_outside_login_keychain")
+                return { kind: "absent", reason: "key_outside_login_keychain" };
+            if (classified)
+                return { kind: "unreachable", reason: `keystore_unavailable:${classified.failure}` };
             return { kind: "unreachable", reason: codeOf(error, "keystore_unavailable") };
         }
     };
@@ -533,7 +555,8 @@ export async function runDoctor(options) {
     const verdicts = cwds.map((dir) => {
         try {
             return judgeRegistration(harness, { cwd: dir, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? defaultClaudeManagedDir(platform),
-                platform, userName, regQuery: options.regQuery });
+                platform, userName, regQuery: options.regQuery, claudeMarketplacePackaged: options.claudeMarketplacePackaged,
+                claudeMarketplaceTrust: options.claudeMarketplaceTrust });
         }
         catch (error) {
             return check("undetermined", codeOf(error, "registration_unreadable"));
@@ -555,6 +578,9 @@ export async function runDoctor(options) {
             installed_version: reportable(plugin?.version ?? null),
             pinned_mcp_version: reportable(plugin?.pinnedMcpVersion ?? null),
             source_ref: reportable(plugin?.sourceRef ?? null),
+            source_kind: plugin?.sourceKind ?? null,
+            source_path: reportablePath(plugin?.sourcePath ?? null),
+            version_from: plugin?.versionFrom ?? null,
             auto_update: plugin ? { effective: plugin.autoUpdate.effective, source: plugin.autoUpdate.source } : { effective: false, source: "undetermined" },
         };
         if (here.hookCounts)
@@ -576,9 +602,10 @@ export function formatDoctorReport(report) {
         const counts = report.registration?.hook_counts;
         lines.push([
             `${"plugin".padEnd(12)} installed=${plugin.installed ? "yes" : "no"}`,
-            `version=${plugin.installed_version ?? "none"}`,
+            `version=${plugin.installed_version ?? "none"}${plugin.version_from ? `(${plugin.version_from})` : ""}`,
             `pinned_mcp=${plugin.pinned_mcp_version ?? "none"}`,
             `ref=${plugin.source_ref ?? "none"}`,
+            `source=${plugin.source_kind ?? "none"}${plugin.source_path ? `:${plugin.source_path}` : ""}`,
             `auto_update=${plugin.auto_update.effective ? "on" : "off"}(${plugin.auto_update.source})`,
             counts ? `hooks SessionStart=${counts.SessionStart} FileChanged=${counts.FileChanged}` : "hooks undetermined",
         ].join(" "));

package/dist/doctor_scopes.d.ts

@@ -1,4 +1,5 @@
 import type { IdentityHarness } from "@consiliency/agent-board-client";
+import { type TrustOptions } from "./claude_marketplace.js";
 export declare const BOARD_MCP_MARKER = "agent-board-mcp";
 export declare const METADATA_ONLY_FLAG = "--metadata-only";
 export declare const OPENCODE_PLUGIN_PACKAGE = "@consiliency/agent-board-opencode";
@@ -12,6 +13,8 @@ export declare const CLAUDE_PLUGIN_MARKETPLACE = "message-board";
 /** Compared lower-cased, as Claude Code compares repos. */
 export declare const CLAUDE_PLUGIN_REPO = "consiliency/message-board";
 export declare const CLAUDE_PLUGIN_SERVER = "agent-board";
+/** message-board#549: THE per-user marketplace directory. Defined once, in `claude_marketplace.ts`. */
+export { claudeMarketplaceDir } from "./claude_marketplace.js";
 export declare const CLAUDE_PLUGIN_MCP_PACKAGE = "@consiliency/agent-board-mcp";
 /** The SL-0 outcome: `B` = the FileChanged hook carries `asyncRewake: true`. */
 export declare const CLAUDE_WAKE_SHAPE: "A" | "B";
@@ -40,6 +43,13 @@ export interface ScopeContext {
     userName?: string;
     /** Registry probe for the Windows policy keys; default `nodeRegQuery`. */
     regQuery?: RegQuery;
+    /**
+     * The cli's packaged marketplace (#549), which our directory source must equal byte for byte.
+     * Default: this cli package's own `claude-marketplace/`.
+     */
+    claudeMarketplacePackaged?: string;
+    /** Test injection for the shared trust chain (`/etc/group`, gid, user name, ownership). */
+    claudeMarketplaceTrust?: Omit<TrustOptions, "uid" | "platform">;
 }
 /** The filesystem reads registration makes; everything is read-only. */
 export interface RegistrationFs {
@@ -163,6 +173,12 @@ export interface ClaudePluginSummary {
     version: string | null;
     pinnedMcpVersion: string | null;
     sourceRef: string | null;
+    /** The winning declaration's kind, when the marketplace is ours: the github repo, or our directory. */
+    sourceKind: "github" | "directory" | null;
+    /** A directory source's path (always `claudeMarketplaceDir` for this env when set); else null. */
+    sourcePath: string | null;
+    /** Where `version` and the pin were read: our validated source directory, or the cache row (#549 round 3). */
+    versionFrom: "source" | "cache" | null;
     autoUpdate: {
         effective: boolean;
         source: AutoUpdateSource;
@@ -174,6 +190,11 @@ export interface ClaudePluginRead {
     unparseable: string[];
     /** An installPath (or a file under it) resolved outside the cache: nothing beyond it was read. */
     untrusted: boolean;
+    /**
+     * Undetermined reasons about our directory source: `plugin_source_unverifiable` (no packaged copy
+     * to compare with) or `plugin_source_newer` (it holds a NEWER plugin than this cli ships).
+     */
+    sourceUndetermined: string[];
     failures: string[];
     summary: ClaudePluginSummary;
     hookPolicy: ClaudeHookPolicy;
@@ -252,9 +273,21 @@ export declare const managedFileTierReplaced: (probe: ManagedPolicyProbe) => boo
  * IF-0-CCPLUGIN-3: every plugin enabled for `ctx.cwd`, followed from `enabledPlugins` to its
  * installed row and read from the cache. Ours is the plugin id `agent-board@message-board` whose
  * marketplace is declared, EVERYWHERE it is declared, as the github repository
- * Consiliency/message-board; anything else contributing a board server or a wake hook is foreign.
+ * Consiliency/message-board or as the per-user directory `claudeMarketplaceDir` (#549); anything
+ * else contributing a board server or a wake hook is foreign.
  */
 export declare function readClaudePluginScopes(ctx: ScopeContext): ClaudePluginRead;
+export type ClaudeSettingsLayer = "user" | "project" | "local" | "managed";
+/**
+ * Every settings layer that declares OUR marketplace name, in ascending precedence (the last one wins),
+ * with whether its source is exactly our per-user directory. Setup uses it to migrate each layer it
+ * may write and to name the one it may not.
+ */
+export declare function claudeMarketplaceDeclarations(ctx: ScopeContext): Array<{
+    layer: ClaudeSettingsLayer;
+    path: string;
+    directory: boolean;
+}>;
 /** A package spec's identity without its version: `@scope/name@1.2.3` → `@scope/name`. */
 export declare function packageIdentity(spec: string): string;
 interface BoardEntryVerdict {
@@ -285,4 +318,3 @@ export declare function readScopes(harness: IdentityHarness, ctx: ScopeContext):
 export declare function claudeProjectKey(ctx: ScopeContext): string;
 /** IF-0-CREDPATH-4 registration, for one working directory. */
 export declare function judgeRegistration(harness: IdentityHarness, ctx: ScopeContext): RegistrationVerdict;
-export {};