@consiliency/agent-board-cli 1.26.0 → 1.27.0

package/claude-marketplace/plugins/agent-board/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-board",
-  "version": "1.31.1",
+  "version": "1.31.2",
   "description": "Message Board for Claude Code: the agent-board MCP server and the local wake hook that nudges an idle session when its inbox has unhandled items.",
   "author": {
     "name": "Consiliency"
@@ -10,7 +10,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@consiliency/agent-board-mcp@1.31.1",
+        "@consiliency/agent-board-mcp@1.31.2",
         "--harness",
         "claude"
       ]

package/dist/assets.json

@@ -1,6 +1,6 @@
 {
-  "mcpVersion": "1.31.1",
-  "piVersion": "0.4.1",
-  "opencodeVersion": "0.2.1",
-  "releaseTag": "v1.54.0"
+  "mcpVersion": "1.31.2",
+  "piVersion": "0.4.2",
+  "opencodeVersion": "0.2.2",
+  "releaseTag": "v1.55.0"
 }

package/dist/doctor.d.ts

@@ -1,4 +1,4 @@
-import { type IdentityHarness, type OperationSuccess, type OsKeychainExec, type SessionRecordEntry, type TrustOptions } from "@consiliency/agent-board-client";
+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"];
@@ -147,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";
@@ -176,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" };
         }
@@ -190,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") };
         }
     };

package/dist/setup_storage.d.ts

@@ -110,6 +110,18 @@ export declare function repairKeyDir(env: NodeJS.ProcessEnv, uid: number): {
     problems: string[];
     root: string | null;
 };
+/**
+ * Why the macOS login keychain did not round-trip, from the probe's classification (#554). Only a
+ * LOCKED keychain is told to unlock: before #554 every cause got that fix, including the
+ * write-permission failure an SSH session produced by writing to System.keychain, where unlocking
+ * the login keychain changed nothing.
+ */
+/** A path as one POSIX shell word: bare when it is plainly safe, else single-quoted ('\'' for a quote). */
+export declare function shellWord(value: string): string;
+export declare function macosKeychainRefusal(probe: OsKeychainProbeResult | null): {
+    reason: string;
+    fix: string;
+};
 /**
  * IF-0-SETUP-3: the key storage, measured, in the IF-0-KEYSEAL-6 order. Never throws for a host
  * condition; a refusal carries the fix.

package/dist/setup_storage.js

@@ -23,7 +23,7 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { chmodSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
-import { probeOsKeychainRoundTrip } from "@consiliency/agent-board-client";
+import { OS_KEYCHAIN_SERVICE, probeOsKeychainRoundTrip } from "@consiliency/agent-board-client";
 import { resolveKeyslotDir } from "./assets.js";
 export const SLOT_RE = /^[a-z][a-z0-9-]{0,31}$/;
 const REFERENCE_LINE = /^agent_socket:\/\S+#[A-Za-z0-9_-]{43}$/;
@@ -347,6 +347,48 @@ function externalAgent(agentSocket, env, uid, machineIdFile, repairs) {
         return { storage: "external", reason: "external_declared", keyReference: reference, repairs };
     return refused(problems.includes("missing") ? "external_undeclared" : "external_declaration_mismatch", EXTERNAL_FIX(declaration), repairs);
 }
+const OR_EXTERNAL = "or pass --agent-socket <ref> with an external-agent declaration";
+/**
+ * Why the macOS login keychain did not round-trip, from the probe's classification (#554). Only a
+ * LOCKED keychain is told to unlock: before #554 every cause got that fix, including the
+ * write-permission failure an SSH session produced by writing to System.keychain, where unlocking
+ * the login keychain changed nothing.
+ */
+/** A path as one POSIX shell word: bare when it is plainly safe, else single-quoted ('\'' for a quote). */
+export function shellWord(value) {
+    return /^[A-Za-z0-9_\/.,:@%+=-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function macosKeychainRefusal(probe) {
+    // Printed for pasting into a shell: a real path is quoted; the fallback keeps `~` unquoted so it expands.
+    const kc = probe?.keychain !== undefined ? shellWord(probe.keychain) : "~/Library/Keychains/login.keychain-db";
+    switch (probe?.failure) {
+        case "keychain_locked":
+            return { reason: "macos_keychain_locked", fix: `the login keychain is locked, and this session cannot show an unlock prompt: run \`security unlock-keychain ${kc}\` and re-run setup` };
+        case "write_denied":
+            return { reason: "macos_keychain_write_denied", fix: `the keychain refused the write (errSecWrPerm) to ${kc}: check that it is your login keychain and that you own it (ls -l ${kc}), ${OR_EXTERNAL}` };
+        case "login_keychain_absent":
+            return { reason: "macos_login_keychain_absent", fix: `there is no login keychain in ~/Library/Keychains (login.keychain-db or login.keychain): log in once at this Mac's console, which creates it, ${OR_EXTERNAL}` };
+        case "item_outside_login_keychain": {
+            // Setup only ever sees its PROBE: the item found outside the login keychain is the probe's own
+            // throwaway, not this harness's key (a harness key held elsewhere surfaces at enrollment, and in
+            // doctor as key_outside_login_keychain). So say that, and offer only the throwaway's cleanup.
+            const holder = probe?.heldBy !== undefined ? shellWord(probe.heldBy) : null;
+            const cleanup = holder !== null && probe?.handle !== undefined
+                ? `; remove the test item with \`security delete-generic-password -s ${OS_KEYCHAIN_SERVICE} -a ${probe.handle} ${holder}\``
+                : "";
+            return { reason: "macos_keychain_item_elsewhere", fix: `setup's throwaway test item was found outside the login keychain, in ${holder ?? "another keychain on your search list"}, after it was deleted from the login keychain, so this account's keychain search list or default keychain is unusual: check \`security list-keychains -d user\` and \`security default-keychain -d user\`${cleanup}, then re-run setup, ${OR_EXTERNAL}` };
+        }
+        case "item_search_undetermined":
+            return { reason: "macos_keychain_search_undetermined", fix: "a keychain on your search list could not be searched (it may be locked): unlock it or remove it from the search list (security list-keychains -d user), then re-run setup" };
+        case "login_keychain_untrusted":
+        case "login_keychain_path_unsafe":
+            return { reason: "macos_login_keychain_unusable", fix: `${kc} is not usable: it must be a regular file you own (not a symlink) at a path with no whitespace, quotes or backslashes; fix it, ${OR_EXTERNAL}` };
+        default: {
+            const detail = probe ? `${probe.outcome}${probe.failure ? `, ${probe.failure}` : ""}` : "the probe did not answer";
+            return { reason: "macos_keychain_unavailable", fix: `the login keychain did not complete a round trip (${detail}): run setup from a logged-in session, ${OR_EXTERNAL}` };
+        }
+    }
+}
 /**
  * IF-0-SETUP-3: the key storage, measured, in the IF-0-KEYSEAL-6 order. Never throws for a host
  * condition; a refusal carries the fix.
@@ -378,7 +420,7 @@ export async function selectKeyStorage(ctx) {
     let gate = null;
     if (platform !== "linux") {
         gate = platform === "darwin"
-            ? { reason: "macos_keychain_unavailable", fix: "the login keychain did not complete a round trip: unlock it (security unlock-keychain) in a logged-in session and re-run setup" }
+            ? macosKeychainRefusal(keychain)
             : { reason: "platform_unsupported", fix: "setup's key storage supports Linux and macOS; on Windows run setup inside WSL, or pass --agent-socket <ref> with an external-agent declaration" };
     }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@consiliency/agent-board-client": "1.40.0",
+    "@consiliency/agent-board-client": "1.41.0",
     "commander": "^14.0.1"
   },
   "license": "Apache-2.0",