@consiliency/agent-board-cli 1.25.0 → 1.26.0

package/claude-marketplace/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "message-board",
+  "description": "Consiliency Message Board plugins for Claude Code.",
+  "owner": {
+    "name": "Consiliency"
+  },
+  "plugins": [
+    {
+      "name": "agent-board",
+      "source": "./plugins/agent-board",
+      "description": "The agent-board MCP server, pinned, and the local wake hook that nudges an idle session."
+    }
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "name": "agent-board",
+  "version": "1.31.1",
+  "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"
+  },
+  "mcpServers": {
+    "agent-board": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@consiliency/agent-board-mcp@1.31.1",
+        "--harness",
+        "claude"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wake-hook.sh\" SessionStart"
+          }
+        ]
+      }
+    ],
+    "FileChanged": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/wake-hook.sh\" FileChanged",
+            "asyncRewake": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-marketplace/plugins/agent-board/hooks/wake-hook.sh

@@ -0,0 +1,288 @@
+#!/usr/bin/env bash
+# The Claude Code side of the local wake signal (Consiliency/message-board#319), shipped as the
+# `agent-board` plugin's hook (CCPLUGIN, IF-0-CCPLUGIN-1). `hooks/hooks.json` runs it as
+#
+#     bash "${CLAUDE_PLUGIN_ROOT}/hooks/wake-hook.sh" SessionStart
+#     bash "${CLAUDE_PLUGIN_ROOT}/hooks/wake-hook.sh" FileChanged        (asyncRewake: true)
+#
+# It lived at `scripts/wake/wake-hook.sh` and was installed by hand into settings; it moved here so a
+# plugin install carries it, and this is the only tracked copy.
+#
+# THE WAKE SHAPE IS B, MEASURED (plans/CCPLUGIN-SPIKE.md, 2026-09-26, Claude Code 2.1.283). The
+# FileChanged hook is registered with `asyncRewake`, so Claude Code runs it in the background and, when
+# it exits 2, wakes the model with its STDERR as a system reminder -- framed by the harness as
+# `Stop hook blocking error from command "FileChanged": <stderr>`; "error" is the harness's label, not
+# ours. A synchronous `additionalContext` on stdout (what this hook used to print) starts no turn in an
+# idle session. So on FileChanged:
+#
+#   * a nudge  -> exactly the frozen sentence (WAKE_NUDGE, IF-0-WAKESELF-2) on stderr, nothing on
+#                 stdout, exit 2;
+#   * silence  -> nothing on either stream, exit 0.
+#
+# SessionStart is unchanged in shape: synchronous, exit 0, the registration JSON on stdout.
+#
+# NOTHING THE HOOK IS HANDED REACHES WHAT IT EMITS (EC-CCPLUGIN-4). A woken model reads stderr as an
+# instruction, and the payload, the environment and the working directory are not ours. Every emission
+# below is a fixed literal; the only interpolations anywhere are the JSON-escaped signal path in
+# `watchPaths` and the log line's timestamp, event (`$1`) and `armed=` fields. A test scans this file
+# for any other expanded printf/echo and fails by line.
+#
+# WHAT THIS REPLACES. The wake spike wired two hooks as
+#
+#     bash .claude/wake-spike/probe.sh SessionStart && printf '{"hookSpecificOutput":{...watchPaths...}}'
+#
+# and then `probe.sh` was deleted. `.claude/wake-spike/` is GITIGNORED (.gitignore:30), so nothing
+# preserved the script and nothing noticed it go; the missing file exited 127, the `&&`
+# short-circuited, and THE REGISTRATION WAS NEVER PRINTED. No watch registered means `FileChanged`
+# could never fire either -- one deleted file silently disabled both hooks. So this file is
+# tracked, and SessionStart prints its registration (or a named refusal) and always exits 0. The `&&`
+# is not reordered, it is gone. (FileChanged's exit 2 is the wake itself, not a failure.)
+#
+# WHY THIS WATCHES ONE FILE AND NOT THE WAKE ROOT -- a review board caught this and it is the
+# whole point of the path layout. `wakeSignalPath` is per (machine, agent, session) precisely so
+# "one identity running two sessions must not share a signal, or an item for one blocks the other"
+# (#319). An earlier version of this script registered the shared ROOT and then emitted attention
+# on ANY FileChanged with no path filter, which threw that isolation away at the only consumer that
+# exists: every session watching the root woke on every other session's item. Distinct filenames
+# isolate nothing if the consumer watches their common parent.
+#
+# Registering the EXACT signal file makes the isolation structural rather than a filter someone
+# must maintain -- a session cannot be woken by a path it is not watching. It also removes the
+# question of whether `watchPaths` recurses into subdirectories, which is unverified here.
+set -uo pipefail
+
+EVENT="${1:-unknown}"
+ARMED=no
+# THE LOG IS WRITTEN FROM AN EXIT TRAP, so every path -- the nudge's `exit 2` included -- leaves exactly
+# one line. It used to be written after the `case`, which an early exit skips (a review seat on the
+# CCPLUGIN plan caught that the nudge path would log nothing). Fields: timestamp, event, armed=; the
+# write is best-effort and silent, because a failing log must never become output or a missed wake.
+on_exit() {
+  local LOG="${MESSAGE_BOARD_WAKE_LOG:-}"
+  [ -n "$LOG" ] || return 0
+  { printf '%s\t%s\tarmed=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$EVENT" "$ARMED" >> "$LOG"; } 2>/dev/null || true
+}
+trap on_exit EXIT
+WAKE_DIR="${MESSAGE_BOARD_WAKE_DIR:-$HOME/.message-board/wake}"
+# STRIP TRAILING SLASHES so this end and the producer agree as STRINGS, not merely as paths.
+# The producer builds its path with Node's `join()`, which normalises `a//b` to `a/b`; this script
+# interpolates, which does not. A `MESSAGE_BOARD_WAKE_DIR` ending in `/` therefore produced
+# `…/wake//claw/…` here against `…/wake/claw/…` there. The kernel collapses the doubled slash so the
+# WATCH still binds — but the FileChanged arm below compares the delivered `file_path` against
+# `$SIGNAL` for whole-string equality, and its documented answer to a present-but-non-matching
+# `file_path` is SILENCE. So the session would look armed and never wake. Found by a review board on
+# the PR that first made anything raise. A bare "/" is left alone rather than emptied.
+while [ "${WAKE_DIR}" != "/" ] && [ "${WAKE_DIR%/}" != "${WAKE_DIR}" ]; do
+  WAKE_DIR="${WAKE_DIR%/}"
+done
+# THE MACHINE ID IS DERIVED, like the session id, and for the same two reasons: requiring an export
+# is a launch-time demand the board's harness-agnostic principle forbids, and a hook that refuses to
+# arm without one ships the feature DARK on a default install.
+#
+# SHORT FORM, to agree with the producer BYTE FOR BYTE. Node's `os.hostname()` may return an FQDN
+# where `hostname -s` returns the short name; the producer strips everything after the first dot and
+# so does this, because a one-segment disagreement is a signal raised where nothing is watching.
+# TRUNCATE ONLY A DERIVED VALUE. A DECLARATION IS VERBATIM.
+#
+# The first version of this stripped unconditionally, and that reintroduced — on the declared
+# branch — the exact divergence it was written to fix. The producer returns a declared
+# MESSAGE_BOARD_WAKE_MACHINE_ID untouched, so declaring `box.example.com` gave the producer
+# `box.example.com` and this end `box`: two paths, both ends reporting armed, nobody woken. A review
+# board reproduced it against the shipped artifacts. It is the fourth time in this feature that a
+# value derived independently on two sides has diverged, and the first where the fix for one
+# divergence created the next.
+#
+# So the rule is per-BRANCH and identical on both ends: a declared value is used exactly as given
+# (an operator who writes a dotted name meant it, and the charset permits dots); only the host name
+# this end reads for itself is truncated at the first dot, because `os.hostname()` and `hostname`
+# disagree about FQDNs.
+if [ -n "${MESSAGE_BOARD_WAKE_MACHINE_ID:-}" ]; then
+  MACHINE_ID="$MESSAGE_BOARD_WAKE_MACHINE_ID"
+else
+  MACHINE_ID="$(hostname 2>/dev/null || true)"
+  MACHINE_ID="${MACHINE_ID%%.*}"
+fi
+# NO AGENT SEGMENT. It used to be required here, from MESSAGE_BOARD_WAKE_AGENT_ID, and that was the
+# last launch-time export this feature demanded — forbidden by the board's harness-agnostic
+# principle, and the reason a mismatch with the producer's own `whoami`-derived id was a permanent
+# silent no-wake with BOTH ends reporting armed. The segment carried no addressing information: a
+# session belongs to one agent, so the session segment already separates every case.
+# See `specs/wake-signal-contract.md` §2.
+# SESSION IDENTITY IS DERIVED IN-SESSION, not exported by an operator.
+#
+# This used to read the explicit variable alone, and `docs/local-wake-signal.md` told the operator
+# to `export MESSAGE_BOARD_WAKE_SESSION_ID=<something unique>`. Two things are wrong with that, and
+# the second is the serious one:
+#
+#   1. It is a LAUNCH-TIME ask, which the board's governing principle forbids — the board is
+#      harness-agnostic and may not demand per-session flags, env vars or wrapper scripts. An
+#      INSTALL-time ask (adding this hook) is legitimate; "remember to export this every time you
+#      start a session" is not.
+#   2. A human asked to invent "a value unique to THIS session" reuses one, and two sessions from
+#      one shell then COLLAPSE TO ONE ADDRESSEE — they share a signal path, so each wakes on the
+#      other's items. Session identity is the ADDRESSING UNIT; sharing it is not a limitation, it
+#      is a misdelivery.
+#
+# MEASURED 2026-09-09, inside a live Claude Code session: `CLAUDE_CODE_SESSION_ID` is set and is a
+# 36-character UUID, alongside `CLAUDECODE=1`. The value we needed was already inside the session,
+# so no operator has to produce it.
+#
+# The explicit variable still WINS when set — it is the declaration path for a harness whose own
+# session id we cannot read (roadmap Tier 2), and it is what the tests drive. What changes is that
+# Claude Code no longer needs it.
+#
+# Keyed on a POSITIVE, harness-specific marker rather than a vendor prefix: the same measurement
+# found an ambient `CODEX_SSH_SKIP_APP_SERVER_BOOT` in a session codex did not launch, so a
+# prefix-sniffing detector would have misidentified it.
+SESSION_ID="${MESSAGE_BOARD_WAKE_SESSION_ID:-}"
+if [ -z "$SESSION_ID" ] && [ -n "${CLAUDECODE:-}" ]; then
+  SESSION_ID="${CLAUDE_CODE_SESSION_ID:-}"
+fi
+
+# Identity is REQUIRED to register a watch. Falling back to the shared root is exactly the defect
+# described above, so the fallback is "register nothing", never "register everything".
+#
+# THE SEGMENT CHARSET IS THE SAME RULE THE PRODUCER ENFORCES, stated once on each side.
+# `assertSafeSegment` in wake_signal.ts refuses anything outside [A-Za-z0-9._-]+ (and refuses "."
+# and ".."), so before this check the two layers DISAGREED, in both damaging directions:
+#
+#   * a segment containing `..` made the hook create and register a file OUTSIDE $WAKE_DIR — an
+#     advisor board demonstrated `CLAUDE_CODE_SESSION_ID='../../../escaped'` doing exactly that;
+#   * any segment with a `/`, a space or a quote produced a watch on a path the producer can NEVER
+#     raise, because the producer would throw on the same value. That is a permanent, silent
+#     no-wake: the session looks armed and can never be woken.
+#
+# Refusing here rather than sanitising is deliberate and matches the producer: a sanitised identity
+# is a DIFFERENT identity, and silently watching someone else's path is the defect this whole file
+# exists to prevent. `case` with a glob, not a regex, so it works in any POSIX shell.
+safe_segment() {
+  case "$1" in
+    "" | "." | ".." ) return 1 ;;
+    *[!A-Za-z0-9._-]* ) return 1 ;;
+    * ) return 0 ;;
+  esac
+}
+
+if safe_segment "$MACHINE_ID" && safe_segment "$SESSION_ID"; then
+  SIGNAL="$WAKE_DIR/$MACHINE_ID/$SESSION_ID/inbox"
+  ARMED=yes
+else
+  SIGNAL=""
+fi
+
+# THE SIGNAL PATH, JSON-ESCAPED. A wake dir containing `"` or `\` would otherwise emit malformed JSON,
+# and a malformed registration fails the same silent way the `&&` did. Escapes `\` first, then `"`.
+# Parameter expansion rather than the `printf | sed` pipe it used to be: the hook runs under bash by
+# contract (hooks.json), and keeping every printf in this file an EMITTER is what lets the
+# interpolation scan judge them all without a "piped printf is fine" exemption.
+SIGNAL_JSON="${SIGNAL//\\/\\\\}"
+SIGNAL_JSON="${SIGNAL_JSON//\"/\\\"}"
+# A control character cannot be carried faithfully by that escaping (it would be `\uXXXX` in JSON and
+# raw here), so both branches below treat it specially.
+SIGNAL_HAS_CNTRL=no
+case "$SIGNAL" in *[[:cntrl:]]*) SIGNAL_HAS_CNTRL=yes ;; esac
+
+case "$EVENT" in
+  SessionStart)
+    if [ -n "$SIGNAL" ] && [ "$SIGNAL_HAS_CNTRL" = yes ]; then
+      # REGISTRATION MUST BE VALID JSON OR IT IS SILENTLY NOTHING, and the two branches of this
+      # script disagreed about that: FileChanged already refuses to trust an exact comparison on a
+      # path containing a control character (see below), while SessionStart escaped only `"` and
+      # `\` and emitted the rest raw. A tab or newline in MESSAGE_BOARD_WAKE_DIR therefore produced
+      # malformed JSON, the registration failed, and NOTHING was watched — the
+      # silent-registration-failure this file's header exists to prevent, reached through the one
+      # branch that had no guard. Found by two review seats on PR #453.
+      #
+      # Refuse rather than emit: a control character in a wake dir is an operator mistake, and an
+      # armed-looking session that watches nothing is worse than a named refusal. The asymmetry with
+      # FileChanged (which WAKES on the same condition) is deliberate and is the fail-safe direction
+      # on each side — registration failing closed means "you are not armed, and here is why";
+      # delivery failing open means "a wasted turn beats a missed wake". Logged as armed=no: nothing
+      # was registered.
+      ARMED=no
+      printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"Message Board wake signal is NOT armed: the wake directory contains a control character, which cannot be registered as a watch path. Set MESSAGE_BOARD_WAKE_DIR to a path without control characters."}}\n'
+    elif [ -n "$SIGNAL" ]; then
+      # Ensure the watch target exists before it is registered: a watch on a path that does not
+      # exist yet may never bind. Created empty and only when absent, so this never bumps the
+      # mtime of a signal a running daemon already raised.
+      mkdir -p "$(dirname "$SIGNAL")" 2>/dev/null || true
+      [ -e "$SIGNAL" ] || : > "$SIGNAL" 2>/dev/null || true
+      printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","watchPaths":["%s"]}}\n' "$SIGNAL_JSON"
+    else
+      printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"Message Board wake signal is NOT armed: the machine and session ids are both derived in-session on Claude Code; set MESSAGE_BOARD_WAKE_MACHINE_ID or MESSAGE_BOARD_WAKE_SESSION_ID only on a harness whose own values cannot be read. Refusing to watch the shared wake root, which would wake this session on another session'"'"'s items."}}\n'
+    fi
+    exit 0
+    ;;
+  FileChanged)
+    # DEFENCE IN DEPTH ON THE CONSUMER SIDE. Registering the exact signal file fixes what this
+    # session SUBSCRIBES to; it does not filter what is DELIVERED. A red-team seat pointed out that
+    # another watcher registered in the same session would route its unrelated events through this
+    # same handler, and this arm would announce inbox items on every one of them. So the delivered
+    # path is checked here as well.
+    #
+    # THE TWO FAILURE DIRECTIONS ARE NOT SYMMETRIC, and that decides the fallback. Emitting when we
+    # should not costs the agent a turn on a canonical fetch that finds nothing. Staying silent
+    # when we should not means the agent is NEVER woken -- which is the silent-disable failure this
+    # whole change exists to remove, reappearing one layer further in. So:
+    #
+    #   * unarmed (no identity, nothing registered)  -> ALWAYS silent. Any event reaching an
+    #     unarmed session is certainly not ours, because we asked for nothing.
+    #   * a payload naming a path that is not ours   -> silent.
+    #
+    # THE DELIVERED PATH IS COMPARED FOR EXACT EQUALITY, in its JSON-ESCAPED form, against the
+    # `file_path` key. Two review rounds moved this comparison, and each move was found to be
+    # wrong one layer further out:
+    #
+    #   * round 4: `$SIGNAL` is a DECODED path but arrives inside JSON where `"` and `\` are
+    #     escaped, so comparing the decoded form never matched and a wake dir like /tmp/a"b
+    #     suppressed every wake. The fix compared the raw form OR the escaped form.
+    #   * round 5: both of those were SUBSTRING matches. A red-team seat showed a payload naming
+    #     `$SIGNAL.extra` or `$SIGNAL/child` woke the session, and that the raw form had an
+    #     encoding collision -- a dir with two literal backslashes matched the JSON of a dir with
+    #     one. Measured before fixing: all three false-positives reproduced against the shipped
+    #     script.
+    #
+    # So: the payload's `"file_path"` value (the key Claude Code sends -- verified in the harness
+    # binary, `hook_event_name:"FileChanged",file_path:n,event:r`) is matched as the WHOLE quoted
+    # string `"file_path":"<escaped SIGNAL>"`. The closing quote is what rejects a suffix or
+    # sub-path; escaping only one side is what removes the collision. Optional whitespace around
+    # the colon is normalised first so a pretty-printed payload cannot turn a match into silence.
+    #
+    # THE FAILURE DIRECTIONS ARE STILL ASYMMETRIC, and the fallbacks follow that:
+    #   * a payload we cannot judge -- empty, or without a `file_path` key at all -- NUDGES. The
+    #     subscription is already narrowed to one file, so the residual risk is a wasted turn.
+    #   * a signal path this script cannot escape faithfully NUDGES on every delivery: the escaping
+    #     handles `"` and `\` only, and a control character in the wake dir would be `\uXXXX`
+    #     in the payload but raw here, so exact comparison would be silently false. Such a dir is
+    #     pathological; it is handled by never letting it produce silence.
+    #   * a `file_path` that is present and is NOT this session's signal -> silent.
+    #
+    # EVERY NUDGE IS THE SAME SENTENCE (outcome B). The fail-open cases used to append their reason
+    # ("the delivered payload carried no file_path…", "this wake dir contains a control character…")
+    # to an additionalContext. They now converge on the one frozen sentence: a woken model needs to
+    # know THAT there is something and where to read it, and one fixed string is the whole of what
+    # EC-CCPLUGIN-4 has to prove about stderr.
+    PAYLOAD="$(cat 2>/dev/null || true)"
+    WANT="\"file_path\":\"$SIGNAL_JSON\""
+    NUDGE=no
+    if [ -z "$SIGNAL" ]; then
+      : # unarmed: this session registered no watch, so this event belongs to someone else.
+    elif [ -z "$PAYLOAD" ] || ! grep -qF '"file_path"' <<<"$PAYLOAD" 2>/dev/null; then
+      NUDGE=yes # nothing to judge on: prefer a wasted turn over a missed wake.
+    elif [ "$SIGNAL_HAS_CNTRL" = yes ]; then
+      NUDGE=yes # the exact comparison cannot be trusted for this path; never let that become silence.
+    elif sed -e 's/"file_path"[[:space:]]*:[[:space:]]*"/"file_path":"/g' <<<"$PAYLOAD" 2>/dev/null | grep -qF "$WANT" 2>/dev/null; then
+      NUDGE=yes
+    fi
+    if [ "$NUDGE" = yes ]; then
+      # The one emitter of the wake. The signal is zero bytes by construction and is never read
+      # here, so nothing that could carry a message body or a bearer secret reaches the model.
+      # SHARED WITH packages/agent-board-client/src/nudge.ts (WAKE_NUDGE), pinned by W34.
+      printf 'Message Board: this session has unhandled inbox items. Read them with the canonical fetch (agent_board.v_agent_wake_recovery) before acting.\n' >&2
+      exit 2
+    fi
+    exit 0
+    ;;
+esac
+
+exit 0

package/dist/assets.d.ts

@@ -16,7 +16,11 @@ export declare class BakedAssetsError extends Error {
 }
 export declare const ASSETS_URL: URL;
 export declare const KEYSLOT_URL: URL;
+/** The packaged Claude Code marketplace (#549): `.claude-plugin/marketplace.json` + `plugins/agent-board/**`. */
+export declare const CLAUDE_MARKETPLACE_URL: URL;
 /** The build's baked versions and release tag, validated field by field. */
 export declare function bakedAssets(file?: string | URL): BakedAssets;
 /** The packaged keyslot directory (no trailing slash). Throws when the build did not copy it. */
 export declare function resolveKeyslotDir(url?: URL): string;
+/** The packaged marketplace directory (no trailing slash). Throws when the build did not copy it. */
+export declare function resolveMarketplaceDir(url?: URL): string;

package/dist/assets.js

@@ -22,6 +22,8 @@ export class BakedAssetsError extends Error {
 }
 export const ASSETS_URL = new URL("../dist/assets.json", import.meta.url);
 export const KEYSLOT_URL = new URL("../keyslot/", import.meta.url);
+/** The packaged Claude Code marketplace (#549): `.claude-plugin/marketplace.json` + `plugins/agent-board/**`. */
+export const CLAUDE_MARKETPLACE_URL = new URL("../claude-marketplace/", import.meta.url);
 /** The build's baked versions and release tag, validated field by field. */
 export function bakedAssets(file = ASSETS_URL) {
     let raw;
@@ -59,3 +61,10 @@ export function resolveKeyslotDir(url = KEYSLOT_URL) {
         throw new BakedAssetsError("keyslot/ is absent: the cli build did not copy the keyslot scripts");
     return dir;
 }
+/** The packaged marketplace directory (no trailing slash). Throws when the build did not copy it. */
+export function resolveMarketplaceDir(url = CLAUDE_MARKETPLACE_URL) {
+    const dir = fileURLToPath(url).replace(/\/+$/, "");
+    if (!existsSync(`${dir}/.claude-plugin/marketplace.json`))
+        throw new BakedAssetsError("claude-marketplace/ is absent: the cli build did not copy the Claude Code marketplace");
+    return dir;
+}

package/dist/assets.json

@@ -2,5 +2,5 @@
   "mcpVersion": "1.31.1",
   "piVersion": "0.4.1",
   "opencodeVersion": "0.2.1",
-  "releaseTag": "v1.53.0"
+  "releaseTag": "v1.54.0"
 }

package/dist/claude_marketplace.d.ts

@@ -0,0 +1,117 @@
+/** The manifest's key in a tree read by `readTree`: always `/`-separated. */
+export declare 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 declare function claudeMarketplaceDir(env: Record<string, string | undefined>, home: string): string;
+/** A declared directory path is ours when it resolves to `claudeMarketplaceDir` for this env. */
+export declare function isOurMarketplacePath(path: unknown, env: Record<string, string | undefined>, home: string): boolean;
+export interface TreeFile {
+    bytes: Buffer;
+    executable: boolean;
+}
+export type TreeRead = {
+    kind: "missing";
+} | {
+    kind: "unusable";
+}
+/** Round 5: an entry inside the tree is owned by another uid or writable by others (`path` is it). */
+ | {
+    kind: "untrusted";
+    path: string;
+} | {
+    kind: "ok";
+    files: Map<string, TreeFile>;
+};
+/** The owner and mode rule for every entry INSIDE a tree that runs (the materialised marketplace). */
+export interface TreeTrust {
+    uid: number;
+    platform?: NodeJS.Platform;
+    /** Injectable for tests: ownership a test cannot create without root. Default `fs.lstatSync`. */
+    lstat?: (path: string) => Pick<TrustStats, "uid" | "mode">;
+}
+/**
+ * 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 declare function readTree(dir: string, trust?: TreeTrust): TreeRead;
+/** Same file set, same bytes, same exec bit. */
+export declare function sameTree(a: ReadonlyMap<string, TreeFile>, b: ReadonlyMap<string, TreeFile>): boolean;
+export type TrustCause = "symlink" | "not_directory" | "foreign_owner" | "writable" | "symlink_loop";
+export interface TrustProblem {
+    path: string;
+    cause: TrustCause;
+    /** Ours (the directory or its parent) and only too permissive: setup may tighten it, doctor may not. */
+    tightenable: boolean;
+    /** For `writable`: the command that removes the write bit named. */
+    command?: string;
+}
+/** What `checkTrustChain` needs to see of one path: an injectable subset of `fs.Stats`. */
+export interface TrustStats {
+    uid: number;
+    gid: number;
+    mode: number;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+export interface TrustOptions {
+    uid: number;
+    platform?: NodeJS.Platform;
+    /** This process's primary gid (default `process.getgid()`). */
+    gid?: number;
+    /** This user's login name (default `os.userInfo().username`). */
+    userName?: string;
+    /** The text of `/etc/group` (default: read it; unreadable → no group is proven private). */
+    groupFile?: string | null;
+    /** The text of `/etc/passwd` (default: read it; unreadable → no group is proven private). */
+    passwdFile?: string | null;
+    /** Injectable for tests: ownership a test cannot create without root. Default `fs.lstatSync`. */
+    lstat?: (path: string) => TrustStats;
+    /** Injectable for tests. Default `fs.readlinkSync`. */
+    readlink?: (path: string) => string;
+}
+/** Symlinks followed before a path is refused as a loop (Linux's MAXSYMLINKS). */
+export declare const MAX_SYMLINK_HOPS = 40;
+/**
+ * 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 declare function isPrivateGroup(gid: number, options: Pick<TrustOptions, "uid" | "gid" | "userName" | "groupFile" | "passwdFile">): boolean;
+/** One directory the resolver entered, with its identity: the pins setup re-checks. */
+export interface VisitedDirectory {
+    path: string;
+    dev: number;
+    ino: number;
+    /** The marketplace directory itself, its `agent-board` parent, or an ancestor. */
+    role: "dir" | "parent" | "ancestor";
+}
+/**
+ * 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 declare function resolveTrustChain(dir: string, options: TrustOptions): {
+    problem: TrustProblem | null;
+    visited: VisitedDirectory[];
+};
+/** The first untrusted path, or null (see `resolveTrustChain`). */
+export declare function checkTrustChain(dir: string, options: TrustOptions): TrustProblem | null;
+/** The human words for a trust problem, for a `fix`. */
+export declare function describeTrustProblem(problem: TrustProblem): string;
+/** The version in a marketplace tree's `plugins/agent-board/.claude-plugin/plugin.json`, or null. */
+export declare function pluginVersionIn(files: ReadonlyMap<string, TreeFile>): string | null;
+/** `x.y.z` numeric comparison (sign), or null when either side is not a plain release version. */
+export declare function compareVersions(a: string | null, b: string | null): number | null;