@consiliency/agent-board-cli 1.24.0 → 1.26.0

package/dist/doctor.js

@@ -9,15 +9,26 @@
 // only with a live `wake_producer` at its expected tier, so 0 is never returned without runtime
 // evidence. Output is names and codes only: no identity value, key or path content is printed,
 // and an error's `code` is printed only when this repository authored it (`authoredCode`).
+import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
-import { resolve } from "node:path";
+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 { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
+import { resolveKeyslotDir } from "./assets.js";
+import { SLOT_RE, externalDeclarationProblems, fileIdentity, keyslotSocketDir, machineIdOf, resolveAgentSocketPath, unsealedOptinProblems, } from "./setup_storage.js";
 export const DOCTOR_CHECKS = Object.freeze([
-    "identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime",
+    "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
@@ -32,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"
@@ -228,6 +245,142 @@ async function keystoreCheck(values, env, probe) {
         ? check("pass", "fingerprint_matches")
         : check("fail", "fingerprint_mismatch");
 }
+/**
+ * IF-0-SETUP-3 / IF-0-KEYSEAL-6 — which storage holds the identity's key, MEASURED: from the file's
+ * key reference plus the packaged `status.sh --json`, never from anything setup recorded.
+ *
+ *  - an `os_keychain` reference → pass `os_keychain` (keystore_key proves the key is there);
+ *  - an `agent_socket` reference: the socket keystore_key signs through (same resolution, including
+ *    `MESSAGE_BOARD_AGENT_SOCKET_PATH`) is matched by DEVICE AND INODE, never spelling, against
+ *    each `$XDG_RUNTIME_DIR/agent-board/<slot>.sock`;
+ *    - a keyslot → `status.sh --harness <h> --slot <slot> --json`. Its measurement fields
+ *      (machine_id, uid, slot, seam, mode) are compared with doctor's own values FIRST: a report
+ *      that is not about this host, user and slot says nothing, so a mismatch or a missing field is
+ *      2 even beside a status exit 1 (both are non-pass). Then exit 1 → 1, exit 2 → 2, and exit 0
+ *      passes as `sealed`, or as `unsealed` only when doctor's own field-by-field read of the opt-in
+ *      is valid (an invalid opt-in is 1, as A1-S2 requires of status.sh);
+ *    - any other socket → `external`, which passes only with a valid declaration
+ *      (`<configRoot>/agent-board/external-agent`); undeclared or mismatched → 2.
+ *  - status.sh absent, unrunnable, timed out or unparseable → 2.
+ */
+const STATUS_MODES = new Set(["sealed", "unsealed", "contradiction", "undetermined"]);
+const STATUS_EXIT2_REASON = /^(nothing_committed|undeterminable|linger_off|upgrade_available|loader_outdated|loader_unrecorded|legacy_loader_present|capability_(error|incapable|incapable-for-keyslot))$/;
+const STATUS_TIMEOUT_MS = 180_000;
+function runStatus(file, args, env) {
+    return new Promise((done) => {
+        execFile(file, args, { env, timeout: STATUS_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (error, stdout) => {
+            const failure = error;
+            const code = !failure ? 0 : typeof failure.code === "number" && !failure.killed ? failure.code : null;
+            done({ code, stdout: String(stdout ?? "") });
+        });
+    });
+}
+/** The keyslot whose socket is the same file as `socket`, or null. */
+function matchKeyslot(socket, env) {
+    const dir = keyslotSocketDir(env);
+    const target = fileIdentity(socket);
+    if (!dir || !target)
+        return null;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    for (const name of names.sort()) {
+        if (!name.endsWith(".sock"))
+            continue;
+        const slot = name.slice(0, -".sock".length);
+        if (!SLOT_RE.test(slot))
+            continue;
+        const candidate = fileIdentity(join(dir, name));
+        if (candidate && candidate.dev === target.dev && candidate.ino === target.ino)
+            return slot;
+    }
+    return null;
+}
+async function keyStorageCheck(harness, values, fileEnv, env, options) {
+    let reference;
+    try {
+        reference = normalizeKeyReference(values[KEY_REFERENCE_KEY]);
+    }
+    catch {
+        return check("undetermined", "key_reference_invalid");
+    }
+    if (reference.resolver === "os_keychain")
+        return check("pass", "os_keychain");
+    if (reference.resolver !== "agent_socket")
+        return check("undetermined", "resolver_unsupported");
+    const socket = resolveAgentSocketPath(String(reference.handle), fileEnv);
+    if (socket === null)
+        return check("undetermined", "agent_socket_unresolved");
+    if (fileIdentity(socket) === null)
+        return check("undetermined", "agent_socket_absent");
+    const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : -1);
+    const machineId = machineIdOf(options.machineIdFile);
+    const slot = matchKeyslot(socket, env);
+    if (slot === null) {
+        const problems = externalDeclarationProblems(env, socket, uid, machineId);
+        if (problems.length === 0)
+            return check("pass", "external");
+        return check("undetermined", problems.includes("missing") ? "external_undeclared" : "external_declaration_mismatch");
+    }
+    let dir;
+    try {
+        dir = options.keyslotDir ?? resolveKeyslotDir();
+    }
+    catch {
+        return check("undetermined", "status_absent");
+    }
+    if (!existsSync(join(dir, "status.sh")))
+        return check("undetermined", "status_absent");
+    const run = await runStatus(join(dir, "status.sh"), ["--harness", harness, "--slot", slot, "--json"], env);
+    if (run.code === null)
+        return check("undetermined", "status_did_not_complete");
+    let report;
+    try {
+        const parsed = JSON.parse(run.stdout);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("not an object");
+        report = parsed;
+    }
+    catch {
+        return check("undetermined", "status_unreadable");
+    }
+    const seam = typeof env.KEYSEAL_TEST_ROOT === "string" && env.KEYSEAL_TEST_ROOT !== "";
+    const own = {
+        machine_id: (value) => machineId !== null && value === machineId,
+        uid: (value) => value === uid,
+        slot: (value) => value === slot,
+        seam: (value) => value === seam,
+        mode: (value) => typeof value === "string" && STATUS_MODES.has(value),
+    };
+    for (const [field, matches] of Object.entries(own)) {
+        if (!(field in report) || report[field] === null)
+            return check("undetermined", `status_field_missing:${field}`);
+        if (!matches(report[field]))
+            return check("undetermined", `status_field_mismatch:${field}`);
+    }
+    if (run.code === 1)
+        return check("fail", "keyslot_status_failed");
+    if (run.code === 2) {
+        const reasons = Array.isArray(report.exit2_reasons) ? report.exit2_reasons : [];
+        const named = reasons.length > 0 && reasons.every((reason) => typeof reason === "string" && STATUS_EXIT2_REASON.test(reason));
+        return check("undetermined", named ? `keyslot_status_undetermined:${reasons.join(",")}` : "keyslot_status_undetermined");
+    }
+    if (run.code !== 0)
+        return check("undetermined", "status_unexpected_exit");
+    if (report.mode === "sealed")
+        return check("pass", "sealed");
+    if (report.mode === "unsealed") {
+        const optin = report.optin;
+        if (optin?.ok !== true)
+            return check("fail", "unsealed_optin_invalid");
+        return unsealedOptinProblems(env, slot, uid, machineId).length === 0 ? check("pass", "unsealed") : check("fail", "unsealed_optin_invalid");
+    }
+    return check("undetermined", "status_mode_unexpected");
+}
 async function whoamiCheck(client, expectedHandle) {
     let rows;
     try {
@@ -342,12 +495,14 @@ export async function runDoctor(options) {
     }
     if (values === null) {
         checks.keystore_key = check("undetermined", "no_identity_file");
+        checks.key_storage = check("undetermined", "no_identity_file");
         checks.whoami = check("undetermined", "no_identity_file");
         checks.board_membership = check("undetermined", "no_identity_file");
     }
     else {
         const fileEnv = fileIdentityEnv(env, values);
         checks.keystore_key = await keystoreCheck(values, fileEnv, options.probeKeystore ?? defaultKeystoreProbe);
+        checks.key_storage = await keyStorageCheck(harness, values, fileEnv, env, options);
         let client = null;
         try {
             client = (options.createClient ?? defaultClient)(fileEnv);
@@ -391,7 +546,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"));
@@ -413,6 +569,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)
@@ -434,9 +593,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 {};

package/dist/doctor_scopes.js

@@ -84,9 +84,14 @@
 //   tree         a github-sourced plugin runs from its row's `installPath` in the cache (measured:
 //                editing the cached `plugin.json` changed what ran, the marketplace clone's did
 //                not). A DIRECTORY-sourced plugin runs from the source directory, not the cache
-//                (editing the source without reinstalling changed what ran). Ours never has a
-//                directory source; for a FOREIGN directory plugin this is a floor: doctor reads
-//                the cache copy, which may not be what runs.
+//                (editing the source without reinstalling changed what ran). For a FOREIGN
+//                directory plugin this is a floor: doctor reads the cache copy, which may not be
+//                what runs. Ours has a directory source since message-board#549 — the per-user
+//                `claudeMarketplaceDir` that `setup` materialises from the cli package, byte-equal
+//                to what it installed — so the floor is the same, and a MISSING directory is
+//                `plugin_source_missing` (measured: `plugin list` then shows `failed to load`).
+//                A directory source is `{source:"directory", path}` in both files (measured,
+//                claude 2.1.283, 2026-09-27); its installed row has no `gitCommitSha`.
 //   auto-update  off globally when `DISABLE_UPDATES` or `DISABLE_AUTOUPDATER` is truthy
 //                (1/true/yes/on), `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is non-empty, or
 //                `.claude.json` has `autoUpdates: false` (unless `installMethod` is native and
@@ -228,6 +233,8 @@
 import { spawnSync } from "node:child_process";
 import * as nodeFs from "node:fs";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { resolveMarketplaceDir } from "./assets.js";
+import { MARKETPLACE_MANIFEST_KEY, checkTrustChain, claudeMarketplaceDir, compareVersions, isOurMarketplacePath, pluginVersionIn, readTree, sameTree, } from "./claude_marketplace.js";
 export const BOARD_MCP_MARKER = "agent-board-mcp";
 export const METADATA_ONLY_FLAG = "--metadata-only";
 export const OPENCODE_PLUGIN_PACKAGE = "@consiliency/agent-board-opencode";
@@ -244,6 +251,8 @@ export const CLAUDE_PLUGIN_MARKETPLACE = "message-board";
 /** Compared lower-cased, as Claude Code compares repos. */
 export const CLAUDE_PLUGIN_REPO = "consiliency/message-board";
 export 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 const CLAUDE_PLUGIN_MCP_PACKAGE = "@consiliency/agent-board-mcp";
 /** The SL-0 outcome: `B` = the FileChanged hook carries `asyncRewake: true`. */
 export const CLAUDE_WAKE_SHAPE = "B";
@@ -1068,11 +1077,24 @@ function readJsonFile(fs, path) {
     return text === null ? null : parseJson(text);
 }
 const truthyEnv = (value) => value !== undefined && ["1", "true", "yes", "on"].includes(value.toLowerCase().trim());
-/** `source` names a github marketplace of this repository, with no alternate manifest path. */
-function isOurMarketplaceSource(source) {
-    const repo = own(source, "repo");
-    return isObject(source) && own(source, "source") === "github" && typeof repo === "string"
-        && repo.toLowerCase() === CLAUDE_PLUGIN_REPO && own(source, "path") === undefined;
+/**
+ * `source` is ours: a github marketplace of this repository with no alternate manifest path (fleet
+ * hosts installed from a release tag), OR a directory marketplace whose path resolves to THE
+ * per-user directory setup materialises (`claudeMarketplaceDir`, message-board#549). Any other
+ * directory is not ours, so a plugin from it is judged as foreign.
+ */
+function marketplaceSourceKind(source, ctx) {
+    if (!isObject(source))
+        return null;
+    const kind = own(source, "source");
+    if (kind === "github") {
+        const repo = own(source, "repo");
+        return typeof repo === "string" && repo.toLowerCase() === CLAUDE_PLUGIN_REPO && own(source, "path") === undefined ? "github" : null;
+    }
+    if (kind === "directory") {
+        return isOurMarketplacePath(own(source, "path"), ctx.env, ctx.home) ? "directory" : null;
+    }
+    return null;
 }
 /**
  * Reads one plugin tree, confined to the cache. `installPath` must resolve (realpath) strictly
@@ -1080,10 +1102,11 @@ function isOurMarketplaceSource(source) {
  * `UntrustedPluginPathError` and nothing beyond it is read: the only call made on an untrusted
  * path is the `realpath` that judged it.
  */
-function readPluginTree(ctx, installPath, serverPrefix) {
+function readPluginTree(ctx, installPath, serverPrefix, confineTo) {
     if (!isAbsolute(installPath))
         throw new UntrustedPluginPathError();
-    const cache = ctx.fs.realpath(join(claudePluginsDir(ctx), "cache"));
+    // Confined to the cache, or (round 3, C2) to our validated source directory.
+    const cache = ctx.fs.realpath(confineTo ?? join(claudePluginsDir(ctx), "cache"));
     const root = cache === null ? null : ctx.fs.realpath(installPath);
     if (cache === null || root === null || !within(root, cache))
         throw new UntrustedPluginPathError();
@@ -1207,15 +1230,18 @@ function claudeAutoUpdate(ctx, declarations, known) {
  * 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 function readClaudePluginScopes(ctx) {
     const unparseable = new Set();
     const failures = new Set();
     const files = [];
     let untrusted = false;
+    const sourceUndetermined = [];
     const summary = {
-        installed: false, serverActive: false, version: null, pinnedMcpVersion: null, sourceRef: null, autoUpdate: { effective: false, source: "default" },
+        installed: false, serverActive: false, version: null, pinnedMcpVersion: null, sourceRef: null, sourceKind: null, sourcePath: null, versionFrom: null,
+        autoUpdate: { effective: false, source: "default" },
     };
     const tolerant = (read, fallback) => {
         try {
@@ -1271,12 +1297,17 @@ export function readClaudePluginScopes(ctx) {
     const ourDeclarations = declarationsOf(CLAUDE_PLUGIN_MARKETPLACE);
     const ourKnown = own(known, CLAUDE_PLUGIN_MARKETPLACE);
     const everyDeclaration = [...ourDeclarations, ...(ourKnown === undefined ? [] : [ourKnown])];
+    // Every declaration must be ours, but not all of one kind: a host migrated from the github ref to
+    // the directory can still carry the github form in a project's settings file.
     const marketplaceIsOurs = everyDeclaration.length > 0
-        && everyDeclaration.every((declaration) => isOurMarketplaceSource(own(declaration, "source")));
+        && everyDeclaration.every((declaration) => marketplaceSourceKind(own(declaration, "source"), ctx) !== null);
     if (marketplaceIsOurs) {
-        // The winning declaration's ref: the highest settings scope, else known_marketplaces.json.
-        const ref = own(own(everyDeclaration[ourDeclarations.length > 0 ? ourDeclarations.length - 1 : 0], "source"), "ref");
-        summary.sourceRef = typeof ref === "string" ? ref : null;
+        // The winning declaration: the highest settings scope, else known_marketplaces.json.
+        const winning = own(everyDeclaration[ourDeclarations.length > 0 ? ourDeclarations.length - 1 : 0], "source");
+        summary.sourceKind = marketplaceSourceKind(winning, ctx);
+        const ref = own(winning, "ref");
+        summary.sourceRef = summary.sourceKind === "github" && typeof ref === "string" ? ref : null;
+        summary.sourcePath = summary.sourceKind === "directory" ? claudeMarketplaceDir(ctx.env, ctx.home) : null;
     }
     summary.autoUpdate = tolerant(() => claudeAutoUpdate(ctx, ourDeclarations, known), { effective: false, source: "undetermined" });
     for (const [id, on] of enabled) {
@@ -1303,9 +1334,23 @@ export function readClaudePluginScopes(ctx) {
             continue;
         }
         const ours = id === CLAUDE_PLUGIN_ID && marketplaceIsOurs;
+        // Round 3 (C2): a directory-sourced plugin RUNS from its source directory, so once that directory
+        // is judged sound (trusted, byte-equal to this cli's packaged copy), the version, pin, stanza and
+        // hooks are read from IT, not from the cache row (which a migration can leave at an old version).
+        // A github source, or a source that is not sound, is read from the cache as before.
+        let sourceVerdict;
+        if (ours && summary.sourceKind === "directory" && summary.sourcePath !== null) {
+            sourceVerdict = judgeOurSourceDirectory(ctx, summary.sourcePath);
+            if (sourceVerdict === "plugin_source_unverifiable" || sourceVerdict === "plugin_source_newer")
+                sourceUndetermined.push(sourceVerdict);
+            else if (sourceVerdict !== null)
+                failures.add(sourceVerdict);
+        }
+        const fromSource = ours && sourceVerdict === null && summary.sourcePath !== null;
+        const treePath = fromSource ? join(summary.sourcePath, "plugins", "agent-board") : own(row, "installPath");
         let tree;
         try {
-            tree = readPluginTree(ctx, own(row, "installPath"), `plugin:${name}`);
+            tree = readPluginTree(ctx, treePath, `plugin:${name}`, fromSource ? summary.sourcePath : undefined);
         }
         catch (error) {
             if (error instanceof UntrustedPluginPathError) {
@@ -1318,10 +1363,11 @@ export function readClaudePluginScopes(ctx) {
             continue;
         }
         const { contribution, manifest } = tree;
-        files.push({ row: ours ? CLAUDE_PLUGIN_ROW : CLAUDE_FOREIGN_PLUGIN_ROW, path: own(row, "installPath"), contribution, pluginId: id });
+        files.push({ row: ours ? CLAUDE_PLUGIN_ROW : CLAUDE_FOREIGN_PLUGIN_ROW, path: treePath, contribution, pluginId: id });
         if (ours) {
             const version = own(manifest, "version");
             summary.installed = true;
+            summary.versionFrom = fromSource ? "source" : "cache";
             summary.version = typeof version === "string" ? version : null;
             const pinArg = contribution.mcp[0]?.args.find((arg) => arg.startsWith(`${CLAUDE_PLUGIN_MCP_PACKAGE}@`));
             summary.pinnedMcpVersion = pinArg === undefined ? null : pinArg.slice(CLAUDE_PLUGIN_MCP_PACKAGE.length + 1);
@@ -1335,7 +1381,68 @@ export function readClaudePluginScopes(ctx) {
                 failures.add("foreign_board_plugin");
         }
     }
-    return { files, unparseable: [...unparseable], untrusted, failures: [...failures], summary, hookPolicy };
+    return { files, unparseable: [...unparseable], untrusted, sourceUndetermined, failures: [...failures], summary, hookPolicy };
+}
+/**
+ * Our directory source, judged as what RUNS: a directory-sourced plugin runs from its source
+ * directory, not the cache copy doctor reads above (CCPLUGIN recon; the header's `tree`). So the
+ * directory itself must be trusted (`checkTrustChain`, shared with setup) and byte-equal to this cli's
+ * packaged marketplace (`readTree`/`sameTree`, shared with setup). Gone → `plugin_source_missing`
+ * (Claude Code then fails to load it, measured). Doctor never tightens a mode: that is setup's.
+ */
+function judgeOurSourceDirectory(ctx, dir) {
+    if (!ctx.fs.exists(dir))
+        return "plugin_source_missing";
+    if (checkTrustChain(dir, { ...ctx.claudeMarketplaceTrust, uid: ctx.fs.getuid(), platform: ctx.platform }) !== null)
+        return "plugin_source_untrusted";
+    let packagedDir;
+    try {
+        packagedDir = ctx.claudeMarketplacePackaged ?? resolveMarketplaceDir();
+    }
+    catch {
+        return "plugin_source_unverifiable";
+    }
+    const packaged = readTree(packagedDir);
+    if (packaged.kind !== "ok" || !packaged.files.has(MARKETPLACE_MANIFEST_KEY))
+        return "plugin_source_unverifiable";
+    // Round 5: every entry inside the directory is judged too (owner, no group/world write): it is
+    // what Claude Code executes. The offending path is not echoed: reasons are authored codes.
+    const current = readTree(dir, { uid: ctx.fs.getuid(), platform: ctx.platform, lstat: ctx.claudeMarketplaceTrust?.lstat });
+    if (current.kind === "missing")
+        return "plugin_source_missing";
+    if (current.kind === "untrusted")
+        return "plugin_source_untrusted";
+    if (current.kind === "ok" && sameTree(current.files, packaged.files))
+        return null;
+    // Round 2, version skew: a directory another cli version wrote. OLDER (or the same version with
+    // other bytes, or unreadable) is stale: re-run setup with this cli. NEWER means THIS doctor is
+    // the old one; it cannot judge a plugin it does not ship, so that is undetermined, not a failure.
+    const skew = current.kind === "ok" ? compareVersions(pluginVersionIn(current.files), pluginVersionIn(packaged.files)) : null;
+    return skew !== null && skew > 0 ? "plugin_source_newer" : "plugin_source_stale";
+}
+/**
+ * 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 function claudeMarketplaceDeclarations(ctx) {
+    const managed = new Set(managedSettingsPaths(ctx));
+    const layerOf = (path, index) => managed.has(path) ? "managed" : index === 0 ? "user" : index === 1 ? "project" : "local";
+    const out = [];
+    claudeSettingsLayers(ctx).forEach((path, index) => {
+        let document;
+        try {
+            document = readJsonFile(ctx.fs, path);
+        }
+        catch {
+            return;
+        }
+        const declaration = own(own(document, "extraKnownMarketplaces"), CLAUDE_PLUGIN_MARKETPLACE);
+        if (declaration === undefined)
+            return;
+        out.push({ layer: layerOf(path, index), path, directory: marketplaceSourceKind(own(declaration, "source"), ctx) === "directory" });
+    });
+    return out;
 }
 // ---------------------------------------------------------------------------------------------
 // Judgement
@@ -1516,7 +1623,7 @@ export function judgeRegistration(harness, ctx) {
     // An absence is only evidence when every file was read: the missing entry may be in the file
     // that did not parse, under the plugin path doctor refused to follow, or a handler doctor
     // cannot judge. A duplicate or the flag, seen in files that DID parse, stands.
-    const complete = unparseable.length === 0 && !plugins?.untrusted && !unjudgeable && !policyUnjudgeable && policyCheckFailed.length === 0;
+    const complete = unparseable.length === 0 && !plugins?.untrusted && (plugins?.sourceUndetermined.length ?? 0) === 0 && !unjudgeable && !policyUnjudgeable && policyCheckFailed.length === 0;
     const standing = complete
         ? failures
         : failures.filter((failure) => failure !== "no_registration" && !failure.startsWith("missing_hook:"));
@@ -1525,6 +1632,7 @@ export function judgeRegistration(harness, ctx) {
     const unknowns = [
         ...(unparseable.length > 0 ? [`unparseable:${[...new Set(unparseable)].join("+")}`] : []),
         ...(plugins?.untrusted ? ["plugin_path_untrusted"] : []),
+        ...(plugins?.sourceUndetermined ?? []),
         ...(unjudgeable ? ["unjudgeable_hook"] : []),
         ...(policyUnjudgeable ? ["hook_policy_unjudgeable"] : []),
         ...policyCheckFailed,

package/dist/identity_writer.d.ts

@@ -16,16 +16,18 @@ export interface IdentityDeployment {
     publishableKey: string;
 }
 /**
- * Where each deployment value is read, in precedence order: the enrollment's own names first
- * (so the file records the deployment the enrollment used — pinned against the client's
- * enrollment resolvers in the test), then the identity names. The generic Supabase names the
- * enrollment also accepts for the publishable key are NOT read: a generic key never fills an
- * identity field, here or in the loader.
+ * Where each deployment value is read, in precedence order: the client's one alias table
+ * (`DEPLOYMENT_ENV_ALIASES`), which puts the enrollment's own names first (so the file records
+ * the deployment the enrollment used) and then the identity names. The enrollment resolvers read
+ * the same table, so the two cannot disagree. The generic Supabase names are in no list: a
+ * generic key never fills an identity field, here or in the loader.
  */
 export declare const DEPLOYMENT_ENV_NAMES: Readonly<Record<keyof IdentityDeployment, readonly string[]>>;
 /**
- * The deployment half of an identity, read and shape-checked before enrollment commits.
- * Absent → `identity_incomplete`; not the non-secret shape its key requires →
+ * The deployment half of an identity, read and shape-checked before enrollment commits. Each
+ * value is the shipped default, or env under the board group's all-or-nothing rule (the
+ * client's `resolveDeploymentField`). Absent from an env-set group → `identity_incomplete`,
+ * naming the variable that switched the group off; not the non-secret shape its key requires →
  * `identity_secret_value`. Both name the variable, never the value.
  */
 export declare function resolveIdentityDeployment(env: NodeJS.ProcessEnv): IdentityDeployment;