@consiliency/agent-board-cli 1.23.0 → 1.24.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 RegistrationFs } from "./doctor_scopes.js";
+import { type ClaudePluginSummary, type RegistrationFs, type RegQuery, type RegistrationVerdict } from "./doctor_scopes.js";
 export type DoctorStatus = "pass" | "fail" | "undetermined";
 export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime"];
 export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number];
@@ -7,11 +7,40 @@ export interface DoctorCheck {
     status: DoctorStatus;
     reason: string;
 }
+/**
+ * CCPLUGIN IF-0-CCPLUGIN-3 — the claude plugin report. Outside `DOCTOR_CHECKS`: it never changes
+ * the exit code. A version or ref prints only if it matches `REPORTABLE_TOKEN`, else
+ * `unrecognised`; `source` is authored. No other file string is echoed.
+ */
+export interface PluginReport {
+    installed: boolean;
+    installed_version: string | null;
+    pinned_mcp_version: string | null;
+    source_ref: string | null;
+    auto_update: ClaudePluginSummary["autoUpdate"];
+}
 export interface DoctorReport {
     harness: IdentityHarness;
     exit: 0 | 1 | 2;
     checks: Record<DoctorCheckName, DoctorCheck>;
+    /** claude only. */
+    plugin?: PluginReport;
+    /** claude only: wake hooks per required event in doctor's cwd, across settings and plugins. */
+    registration?: {
+        hook_counts: NonNullable<RegistrationVerdict["hookCounts"]>;
+    };
+    /**
+     * claude only; a report, never a check: which admin-policy sources doctor probed (authored
+     * names), which exist, and whether the platform has sources it checks by presence only.
+     */
+    managed_policy?: {
+        checked: string[];
+        evidence: string[];
+        unreadable_sources_possible: boolean;
+        platform: string;
+    };
 }
+export declare const REPORTABLE_TOKEN: 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
@@ -52,8 +81,16 @@ export interface DoctorOptions {
     createClient?: (fileEnv: NodeJS.ProcessEnv) => DoctorClient;
     probeKeystore?: KeystoreProbe;
     registrationFs?: RegistrationFs;
-    /** Claude Code's managed directory. Default `/etc/claude-code`. */
+    /** Claude Code's managed directory. Default: the binary's per-platform one (`/etc/claude-code` on Linux). */
     claudeManagedDir?: string;
+    /** The OS whose managed (MDM) sources are probed. Default `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** 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`. */
+    lookupUserName?: () => string;
+    /** Registry probe (Windows/WSL policy keys). Default: `reg query … /v Settings`, 5 s. */
+    regQuery?: RegQuery;
 }
 /**
  * An error's `code`, only when this repository wrote it: a member of the derived

package/dist/doctor.js

@@ -10,12 +10,50 @@
 // 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 { randomBytes } from "node:crypto";
-import { homedir } from "node:os";
+import { homedir, userInfo } from "node:os";
+import { 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 { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
 export const DOCTOR_CHECKS = Object.freeze([
     "identity_file", "keystore_key", "whoami", "board_membership", "registration", "runtime",
 ]);
+export const REPORTABLE_TOKEN = /^[A-Za-z0-9._/-]{1,64}$/;
+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
+ * plugin's server is registered there. All at the pin (our plugin's version) → unchanged; NONE at
+ * it → `plugin_pin_mismatch`; a MIXED set → `plugin_pin_ambiguous` (which one is ours is unknown).
+ * A record elsewhere was launched by whatever registration applies THERE. An earlier reason is
+ * kept and this one appended.
+ */
+function pinCheck(verdict, entries, cwd, fs) {
+    // Only while our plugin's server is registered here: one turned off by `disabledMcpServers`
+    // launched nothing whose version could be judged (panel S1).
+    const pin = verdict.plugin?.installed && verdict.plugin.serverActive ? verdict.plugin.version : null;
+    if (pin === null)
+        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"
+        && real(entry.record.cwd) === real(cwd) ? [entry.record] : []);
+    const atPin = here.filter((record) => record.packageVersion === pin).length;
+    // All at the pin → nothing to say; none → a mismatch; a mixed set → which one is ours is unknown (panel B1).
+    if (atPin === here.length)
+        return verdict;
+    // An earlier reason is kept, never overwritten (panel S5).
+    const earlier = verdict.status === "pass" ? [] : [verdict.reason];
+    if (atPin === 0)
+        return { ...verdict, status: "fail", reason: [...earlier, "plugin_pin_mismatch"].join(",") };
+    return { ...verdict, status: verdict.status === "fail" ? "fail" : "undetermined", reason: [...earlier, "plugin_pin_ambiguous"].join(",") };
+}
+/** The binary's managed-settings directory per platform (`Zh()`, 2.1.283). */
+function defaultClaudeManagedDir(platform) {
+    if (platform === "darwin")
+        return "/Library/Application Support/ClaudeCode";
+    if (platform === "win32")
+        return "C:\\Program Files\\ClaudeCode";
+    return "/etc/claude-code";
+}
 const FINGERPRINT_KEY = "AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT";
 const HANDLE_KEY = "AGENT_BOARD_EXPECTED_AGENT_HANDLE";
 const KEY_REFERENCE_KEY = "AGENT_BOARD_AGENT_KEY_REFERENCE";
@@ -340,21 +378,76 @@ export async function runDoctor(options) {
     const cwds = [...new Set([cwd, ...entries.flatMap((entry) => entry.status === "live" ? [entry.record.cwd] : [])])];
     const fs = options.registrationFs ?? nodeRegistrationFs;
     const home = env.HOME && env.HOME.trim() !== "" ? env.HOME : homedir();
-    checks.registration = worst(cwds.map((dir) => {
+    const platform = options.platform ?? process.platform;
+    let userName = options.userName;
+    if (userName === undefined) {
+        try {
+            userName = (options.lookupUserName ?? (() => userInfo().username))() || undefined;
+        }
+        catch {
+            userName = undefined;
+        }
+    }
+    const verdicts = cwds.map((dir) => {
         try {
-            return judgeRegistration(harness, { cwd: dir, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? "/etc/claude-code" });
+            return judgeRegistration(harness, { cwd: dir, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? defaultClaudeManagedDir(platform),
+                platform, userName, regQuery: options.regQuery });
         }
         catch (error) {
             return check("undetermined", codeOf(error, "registration_unreadable"));
         }
-    }));
+    });
+    // `cwds[0]` is doctor's own cwd: the pin and the report are about it.
+    verdicts[0] = pinCheck(verdicts[0], entries, cwd, fs);
+    const registration = worst(verdicts);
+    checks.registration = check(registration.status, registration.reason);
     const ordered = Object.fromEntries(DOCTOR_CHECKS.map((name) => [name, checks[name]]));
     const statuses = Object.values(ordered).map((item) => item.status);
     const exit = statuses.every((status) => status === "pass") ? 0 : statuses.includes("fail") ? 1 : 2;
-    return { harness, exit, checks: ordered };
+    const report = { harness, exit, checks: ordered };
+    const here = verdicts[0];
+    if (harness === "claude") {
+        const plugin = here.plugin;
+        report.plugin = {
+            installed: plugin?.installed ?? false,
+            installed_version: reportable(plugin?.version ?? null),
+            pinned_mcp_version: reportable(plugin?.pinnedMcpVersion ?? null),
+            source_ref: reportable(plugin?.sourceRef ?? null),
+            auto_update: plugin ? { effective: plugin.autoUpdate.effective, source: plugin.autoUpdate.source } : { effective: false, source: "undetermined" },
+        };
+        if (here.hookCounts)
+            report.registration = { hook_counts: { SessionStart: here.hookCounts.SessionStart, FileChanged: here.hookCounts.FileChanged } };
+        if (here.managedPolicy) {
+            report.managed_policy = {
+                checked: [...here.managedPolicy.checked], evidence: [...here.managedPolicy.evidence],
+                unreadable_sources_possible: here.managedPolicy.unreadableSourcesPossible, platform: here.managedPolicy.platformLabel,
+            };
+        }
+    }
+    return report;
 }
 /** Human-readable form; `--json` prints the report object itself. */
 export function formatDoctorReport(report) {
     const lines = DOCTOR_CHECKS.map((name) => `${report.checks[name].status.padEnd(12)} ${name}: ${report.checks[name].reason}`);
+    if (report.plugin) {
+        const { plugin } = report;
+        const counts = report.registration?.hook_counts;
+        lines.push([
+            `${"plugin".padEnd(12)} installed=${plugin.installed ? "yes" : "no"}`,
+            `version=${plugin.installed_version ?? "none"}`,
+            `pinned_mcp=${plugin.pinned_mcp_version ?? "none"}`,
+            `ref=${plugin.source_ref ?? "none"}`,
+            `auto_update=${plugin.auto_update.effective ? "on" : "off"}(${plugin.auto_update.source})`,
+            counts ? `hooks SessionStart=${counts.SessionStart} FileChanged=${counts.FileChanged}` : "hooks undetermined",
+        ].join(" "));
+    }
+    if (report.managed_policy) {
+        const policy = report.managed_policy;
+        lines.push([
+            `${"admin policy".padEnd(12)} checked ${policy.checked.join(",") || "none"}`,
+            policy.evidence.length > 0 ? `; found ${policy.evidence.join(",")}` : "",
+            policy.unreadable_sources_possible ? `; ${policy.platform} MDM profiles not fully readable` : "",
+        ].join(""));
+    }
     return [`agent-board doctor --harness ${report.harness}`, ...lines, `exit ${report.exit}`].join("\n");
 }

package/dist/doctor_scopes.d.ts

@@ -5,7 +5,28 @@ export declare const OPENCODE_PLUGIN_PACKAGE = "@consiliency/agent-board-opencod
 export declare const PI_PACKAGE = "npm:@consiliency/agent-board-pi";
 /** Claude Code events that each need exactly one `wake-hook.sh` hook (`docs/local-wake-signal.md`). */
 export declare const CLAUDE_REQUIRED_HOOK_EVENTS: readonly ["SessionStart", "FileChanged"];
+/** A wake hook is a command with a token whose BASENAME is this (see `namesWakeHook`). */
 export declare const WAKE_HOOK_MARKER = "wake-hook.sh";
+export declare const CLAUDE_PLUGIN_ID = "agent-board@message-board";
+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";
+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";
+export declare const CLAUDE_PLUGIN_HOOK_COMMANDS: Readonly<Record<string, string>>;
+/** The stanza a plugin of version `version` must carry: the pin IS the plugin version. */
+export declare function claudePluginStanza(version: string): {
+    command: string;
+    args: string[];
+};
+/**
+ * Whether a hook command names the wake hook. The tokenizer is frozen: split on whitespace, strip
+ * quotes, no comment handling; a token matches when its basename is exactly `wake-hook.sh`, so
+ * `codex-wake-hook.sh` does not. Floor: a hook that never names the basename is invisible.
+ */
+export declare function namesWakeHook(command: string): boolean;
 export interface ScopeContext {
     cwd: string;
     home: string;
@@ -13,6 +34,12 @@ export interface ScopeContext {
     /** Claude Code's managed directory (Linux `/etc/claude-code`); injectable for tests. */
     claudeManagedDir: string;
     fs: RegistrationFs;
+    /** The OS, for the managed (MDM) sources doctor probes. Absent → treated as Linux. */
+    platform?: NodeJS.Platform;
+    /** The login name the macOS per-user managed plist is keyed by. */
+    userName?: string;
+    /** Registry probe for the Windows policy keys; default `nodeRegQuery`. */
+    regQuery?: RegQuery;
 }
 /** The filesystem reads registration makes; everything is read-only. */
 export interface RegistrationFs {
@@ -26,6 +53,8 @@ export interface RegistrationFs {
         isFile: boolean;
     } | null;
     exists(path: string): boolean;
+    /** The canonical path (every symlink resolved), or null when it does not exist. */
+    realpath(path: string): string | null;
     getuid(): number;
 }
 export declare const nodeRegistrationFs: RegistrationFs;
@@ -58,10 +87,27 @@ export interface McpEntry {
     fields: Readonly<Record<string, unknown>>;
     shape: McpShape;
 }
+export interface HookEntry {
+    /** The handler's `type` (`command`, `http`, `prompt`, `agent`, `mcp_tool`); a non-string type is "". */
+    type: string;
+    /** A command handler's command; null for every other handler (its url or prompt is never kept). */
+    command: string | null;
+    /** Claude Code's `asyncRewake`: only a literal `true` counts. */
+    asyncRewake: boolean;
+    /**
+     * The group has a matcher that filters (round-2 F029): anything but absent or "". A SessionStart
+     * matcher filters on the start source, a FileChanged one on basename(file_path) (binary). The
+     * matcher text itself is never kept.
+     */
+    hasMatcher: boolean;
+    /** The handler's and its group's own key NAMES (never values), for the exact freeze. */
+    handlerKeys: string[];
+    groupKeys: string[];
+}
 export interface ScopeContribution {
     mcp: McpEntry[];
-    /** Claude hooks: event → the command strings registered for it. */
-    hooks: Record<string, string[]>;
+    /** Claude hooks: event → the hooks registered for it. */
+    hooks: Record<string, HookEntry[]>;
     /** opencode `plugin` / pi `packages` specs. */
     packages: string[];
 }
@@ -69,6 +115,8 @@ export interface ScopeFile {
     row: string;
     path: string;
     contribution: ScopeContribution;
+    /** A synthetic plugin file's plugin id (for the managed-plugin hook exemption); never echoed. */
+    pluginId?: string;
 }
 type Parser = "json" | "json_or_empty" | "jsonc" | "toml";
 export interface ScopeRow {
@@ -103,6 +151,110 @@ export declare const HARNESS_CONFIG_SCOPES: Readonly<Record<IdentityHarness, rea
  * their value is never used.
  */
 export declare const MCP_LAYER_MERGE: Readonly<Record<IdentityHarness, "replace" | "fields">>;
+/** Synthetic row names: authored, so no plugin id, marketplace name or path reaches a reason. */
+export declare const CLAUDE_PLUGIN_ROW = "claude_plugin";
+export declare const CLAUDE_FOREIGN_PLUGIN_ROW = "claude_plugin_foreign";
+export type AutoUpdateSource = "env_disabled" | "config_disabled" | "settings" | "known_marketplaces" | "default" | "undetermined";
+/** What doctor learned about OUR plugin. Values are raw; the report sanitises them. */
+export interface ClaudePluginSummary {
+    installed: boolean;
+    /** Our plugin's board server is registered in this cwd (not turned off by `disabledMcpServers`). */
+    serverActive: boolean;
+    version: string | null;
+    pinnedMcpVersion: string | null;
+    sourceRef: string | null;
+    autoUpdate: {
+        effective: boolean;
+        source: AutoUpdateSource;
+    };
+}
+export interface ClaudePluginRead {
+    /** One synthetic file per enabled plugin read, ranked above user settings. */
+    files: ScopeFile[];
+    unparseable: string[];
+    /** An installPath (or a file under it) resolved outside the cache: nothing beyond it was read. */
+    untrusted: boolean;
+    failures: string[];
+    summary: ClaudePluginSummary;
+    hookPolicy: ClaudeHookPolicy;
+}
+/**
+ * Which hooks Claude Code runs (round-2 F027/F028; see the header's `hook policy`): settings
+ * hooks from every scope, from managed settings only, or none; plugin hooks from every plugin,
+ * only from plugins managed settings enable, or none.
+ */
+export interface ClaudeHookPolicy {
+    settings: "all" | "managed_only" | "none";
+    plugins: "all" | "managed_only" | "none";
+    /** Plugin ids managed settings enable (`enabledPlugins[id] === true`), for `managed_only`. */
+    managedPluginIds: ReadonlySet<string>;
+    /** The managed-plugin set comes from somewhere doctor cannot read (managed `prependPlugins`/`appendPlugins`). */
+    unjudgeable: boolean;
+    /**
+     * The managed tier may not be the file doctor reads (round-3 N1): a server-managed or MDM source
+     * replaces the file tier entirely ("first-wins"), and doctor reads neither. True when the probe
+     * found evidence of one, or could not complete.
+     */
+    managedTierUnreadable: boolean;
+    probe: ManagedPolicyProbe;
+}
+export declare const CLAUDE_REMOTE_SETTINGS_FILE = "remote-settings.json";
+/**
+ * Storage-v5 (round 4): the binary writes the server-managed payload to its state store
+ * (`Re.state("remote-settings")`, a `state` namespace in the config home) and a signed-cache
+ * sidecar beside the json path. The store's exact on-disk name is not recoverable from strings,
+ * so every candidate is probed; any one present is evidence.
+ */
+export declare const CLAUDE_REMOTE_SETTINGS_STATE_CANDIDATES: readonly string[];
+export declare const CLAUDE_REMOTE_SETTINGS_SIDECARS: readonly string[];
+export declare const MACOS_MANAGED_PREFERENCES = "/Library/Managed Preferences";
+export declare const MACOS_POLICY_PLIST = "com.anthropic.claudecode.plist";
+export declare const WINDOWS_POLICY_KEYS: Readonly<{
+    hklm: "HKLM\\SOFTWARE\\Policies\\ClaudeCode";
+    hkcu: "HKCU\\SOFTWARE\\Policies\\ClaudeCode";
+}>;
+export declare const WINDOWS_POLICY_VALUE = "Settings";
+/** Where WSL's Windows interop puts reg.exe; the binary reads HKLM policy through this path. */
+export declare const WSL_REG_EXE = "/mnt/c/Windows/System32/reg.exe";
+export declare const WSL_WINDOWS_MANAGED_DIR = "/mnt/c/Program Files/ClaudeCode";
+export type RegQueryOutcome = {
+    kind: "present";
+} | {
+    kind: "absent";
+} | {
+    kind: "error";
+    cause: "reg_unavailable" | "reg_timeout" | "reg_failed";
+};
+/** `reg query <key> /v Settings`, read-only. */
+export type RegQuery = (regExe: string, key: string) => RegQueryOutcome;
+/**
+ * The binary's own query: `reg query <key> /v Settings`, an argv array, no shell, 5 s. Exit 0 →
+ * the value is there; reg's "unable to find" → not there (the binary's own test); anything else —
+ * no reg.exe, a timeout, another failure — is an error, never "absent".
+ */
+export declare function regQueryWith(timeoutMs: number): RegQuery;
+export declare const nodeRegQuery: RegQuery;
+/** What doctor looked at for admin policy: authored source names only. */
+export interface ManagedPolicyProbe {
+    checked: string[];
+    /** Sources that exist: each means a tier doctor cannot read replaces the managed file. */
+    evidence: string[];
+    /** Authored causes of probes that could not finish (`reg_unavailable`, `reg_timeout`, `reg_failed`, `login_unavailable`). */
+    errors: string[];
+    /** The platform has admin sources doctor checks only by presence (macOS, Windows, WSL). */
+    unreadableSourcesPossible: boolean;
+    platformLabel: "Linux" | "macOS" | "Windows" | "WSL";
+}
+export declare function probeManagedPolicy(ctx: ScopeContext): ManagedPolicyProbe;
+/** Evidence of (or an unfinished probe for) a tier that replaces the managed settings FILE. */
+export declare const managedFileTierReplaced: (probe: ManagedPolicyProbe) => boolean;
+/**
+ * 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.
+ */
+export declare function readClaudePluginScopes(ctx: ScopeContext): ClaudePluginRead;
 /** A package spec's identity without its version: `@scope/name@1.2.3` → `@scope/name`. */
 export declare function packageIdentity(spec: string): string;
 interface BoardEntryVerdict {
@@ -114,6 +266,12 @@ export declare function judgeMcpEntry(entry: McpEntry, fs: RegistrationFs): Boar
 export interface RegistrationVerdict {
     status: "pass" | "fail" | "undetermined";
     reason: string;
+    /** claude only: what doctor learned about our plugin, for the report and the pin check. */
+    plugin?: ClaudePluginSummary;
+    /** claude only: wake hooks per required event, across settings and plugins. */
+    hookCounts?: Record<(typeof CLAUDE_REQUIRED_HOOK_EVENTS)[number], number>;
+    /** claude only: which admin-policy sources were probed, for the report. */
+    managedPolicy?: ManagedPolicyProbe;
 }
 /**
  * Read every scope row of `harness` for `cwd`. A file that fails to parse is reported, not guessed.
@@ -123,6 +281,8 @@ export declare function readScopes(harness: IdentityHarness, ctx: ScopeContext):
     files: ScopeFile[];
     unparseable: string[];
 };
+/** The `.claude.json` `projects` key Claude Code uses for `cwd`: the git root of its realpath, else the realpath. */
+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 {};