@consiliency/agent-board-cli 1.28.0 → 1.29.0

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-board",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "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.32.0",
+        "@consiliency/agent-board-mcp@1.33.0",
         "--harness",
         "claude"
       ]

package/dist/assets.json

@@ -1,6 +1,6 @@
 {
-  "mcpVersion": "1.32.0",
-  "piVersion": "0.4.2",
-  "opencodeVersion": "0.2.2",
-  "releaseTag": "v1.57.0"
+  "mcpVersion": "1.33.0",
+  "piVersion": "0.4.3",
+  "opencodeVersion": "0.2.3",
+  "releaseTag": "v1.58.0"
 }

package/dist/cli.d.ts

@@ -1,7 +1,8 @@
 import { Command } from "commander";
-import { createAgentBoardClient, type EnrollKeystore, type EnrollmentIntent, type FleetOnboardingIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt, resolveCredentials } from "@consiliency/agent-board-client";
+import { createAgentBoardClient, type EnrollKeystore, type EnrollmentIntent, type FleetOnboardingIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt, resolveCredentials, type MyBoardRequest } from "@consiliency/agent-board-client";
 import { type DoctorOptions, type DoctorReport } from "./doctor.js";
 import { type SetupEnroller, type SetupRunner } from "./setup.js";
+import { type SetupAllRunner } from "./setup_all.js";
 import { DevicePendingEnrollmentStore } from "./enroll_runtime.js";
 type JsonObject = Record<string, unknown>;
 export interface CliIo {
@@ -64,6 +65,7 @@ interface ClientLike {
     }>;
     revokeInviteLink(input: JsonObject): Promise<unknown>;
     redeemInviteLink(input: JsonObject): Promise<unknown>;
+    listMyBoardRequests(): Promise<MyBoardRequest[]>;
     listBoardMembers(input: JsonObject): Promise<unknown>;
     listBoardPendingMemberships(input: JsonObject): Promise<unknown>;
     resolveAgentHandle(input: JsonObject): Promise<unknown>;
@@ -333,13 +335,14 @@ export interface CredentialSelection {
  * for the same reason. Without it: `resolveCredentials(descriptor, env)`, exactly as before.
  */
 export declare function fileAwareCredentials(selection: CredentialSelection, env?: NodeJS.ProcessEnv): (descriptor?: Parameters<typeof resolveCredentials>[0]) => Promise<import("@consiliency/agent-board-client").ResolvedCredentials>;
-export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner, selection?: CredentialSelection, setup?: SetupRunner): Command;
+export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner, selection?: CredentialSelection, setup?: SetupRunner, setupAll?: SetupAllRunner): Command;
 export interface RunCliOptions {
     /** The env the default client's credential resolver reads. Default `process.env`. */
     env?: NodeJS.ProcessEnv;
     /** Extra options for the DEFAULT client (tests: a `dataSourceFactory`); never its resolver. */
     clientOptions?: Omit<NonNullable<Parameters<typeof createAgentBoardClient>[0]>, "resolveCredentials">;
     setup?: SetupRunner;
+    setupAll?: SetupAllRunner;
 }
 export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner, doctor?: DoctorRunner, options?: RunCliOptions): Promise<void>;
 export {};

package/dist/cli.js

@@ -3,9 +3,10 @@ import { createHash, randomUUID } from "node:crypto";
 import * as nodeFs from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, assertIdentityHarness, identityFilePath, resolveHostSegment, identityConfigRoot, walkTrustedDirectory, IDENTITY_HARNESSES, CredentialResolutionError, readIdentityFile, resolveCredentials, } from "@consiliency/agent-board-client";
+import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, beginDeviceEnrollment, completeDeviceEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, EnrollmentCommandError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, buildFleetHarnessTemplate, finalizeFleetHarnessTemplate, normalizePublishableKeyFieldReference, normalizeFleetTupleValue, normalizeKeyReference, enrollCommitMarker, assertPresentationSafe, FLEET_TEMPLATE_FAILURE_MESSAGE, PROHIBITED_PRESENTATION_REMOVE_CLASS, buildAgentJoinInstructions, nodeFetchAdapter, buildEnrollKeystore, AUTHORED_CAUSE_CODES, codeProvenance, markAuthoredCode, assertIdentityHarness, identityFilePath, resolveHostSegment, identityConfigRoot, walkTrustedDirectory, IDENTITY_HARNESSES, CredentialResolutionError, readIdentityFile, resolveCredentials, parseInviteInput, } from "@consiliency/agent-board-client";
 import { fileIdentityEnv, formatDoctorReport, runDoctor } from "./doctor.js";
 import { addSetupCommand, runSetup } from "./setup.js";
+import { runSetupAll, setupAllCommand } from "./setup_all.js";
 import { identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, } from "./identity_writer.js";
 import { DevicePendingEnrollmentStore, FilePendingEnrollmentStore, FleetDeviceContinuationStore, makeBrowserOpener, prepareFleetRuntimeOutput, publishFinalizedFleetTemplate, } from "./enroll_runtime.js";
 function isRuntimeStatus(value) {
@@ -2900,7 +2901,12 @@ function renderDevicePrompt(prompt) {
     lines.push("");
     return `${lines.join("\n")}\n`;
 }
-/** Read a single-line auth code from a piped stdin (A5). Returns undefined on a TTY. */
+/**
+ * Read a single-line code from a piped stdin (A5), trimmed. Returns undefined on a TTY. Its callers
+ * are the OAuth authorization code (not an invite) and the fleet onboarding invite code, which
+ * IF-0-ONBOARD-2 keeps out of the invite parser (a fleet invite has no designated field). A room
+ * invite is read by `readInviteFromStdin` and parsed.
+ */
 async function readCodeFromStdin() {
     if (process.stdin.isTTY)
         return undefined;
@@ -2911,6 +2917,17 @@ async function readCodeFromStdin() {
     const text = Buffer.concat(chunks).toString("utf8").trim();
     return text.length > 0 ? text : undefined;
 }
+/** All of a piped stdin, unparsed (a room invite message is several lines). undefined on a TTY. */
+async function readInviteFromStdin() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    const text = Buffer.concat(chunks).toString("utf8");
+    return text.trim().length > 0 ? text : undefined;
+}
 function addRoomsCommands(program, client, io) {
     const rooms = program
         .command("rooms")
@@ -3094,17 +3111,27 @@ function addRoomsCommands(program, client, io) {
         .description("Redeem an invite link by code, joining as the agent identity resolved from this host's env credentials. The code is a BEARER SECRET — prefer piping it on stdin.")
         .option("--code <code>", "the invite code (prefer stdin; argv leaks via /proc/<pid>/cmdline and shell history)")
         .action(async (o) => {
-        let code = o.code;
-        if (!code) {
-            code = await readCodeFromStdin();
-        }
-        if (!code) {
-            io.writeStderr("link-redeem needs an invite code: pipe it on stdin (e.g. `agent-board rooms link-redeem <<'MB_INVITE_CODE'` ... `MB_INVITE_CODE`) or pass --code (which leaks the bearer code via /proc and shell history).\n");
+        // IF-0-ONBOARD-2: the code, or the whole invite message on stdin, goes through the ONE
+        // shared parser, which reads only the designated invite-code field. Neither form is a
+        // terminal read (a TTY stdin is not read at all), so a message is accepted from either.
+        const text = o.code ?? (await readInviteFromStdin());
+        if (!text) {
+            io.writeStderr("link-redeem needs an invite code: pipe it (or the whole invite message) on stdin (e.g. `agent-board rooms link-redeem <<'MB_INVITE_CODE'` ... `MB_INVITE_CODE`) or pass --code (which leaks the bearer code via /proc and shell history).\n");
             process.exitCode = 1;
             return;
         }
-        return runHandler(io, "agent_board.redeem_invite_link", () => client.redeemInviteLink({ p_code: code }));
+        return runHandler(io, "agent_board.redeem_invite_link", () => client.redeemInviteLink({ p_code: parseInviteInput(text, { tty: false }).code }));
     });
+    // IF-0-ONBOARD-4: the caller's OWN join requests as they stand now (the RPC takes no identity:
+    // the session is the requester).
+    rooms
+        .command("my-requests")
+        .description("List your own join requests and where each stands (requested, joined, left, …; expired by age)")
+        .action(() => runHandler(io, "agent_board.list_my_board_requests", async () => ({
+        ok: true,
+        operation: "agent_board.list_my_board_requests",
+        data: await client.listMyBoardRequests(),
+    })));
 }
 function addInviteCommands(program, client, io) {
     const invite = program.command("invite").description("create bounded fleet onboarding invites");
@@ -3229,7 +3256,7 @@ export function fileAwareCredentials(selection, env = process.env) {
         return resolveCredentials(undefined, fileIdentityEnv(env, values));
     };
 }
-export function createProgram(client, io, enrollment = defaultEnrollmentRunner(), doctor = runDoctor, selection = {}, setup) {
+export function createProgram(client, io, enrollment = defaultEnrollmentRunner(), doctor = runDoctor, selection = {}, setup, setupAll) {
     const program = new Command()
         .name("agent-board")
         .description("Thin CLI surface for the agent_board RPC and canonical read contracts")
@@ -3260,7 +3287,7 @@ export function createProgram(client, io, enrollment = defaultEnrollmentRunner()
     addInviteCommands(program, client, io);
     addEnrollCommands(program, io, enrollment);
     addDoctorCommand(program, io, doctor);
-    addSetupCommand(program, io, setup ?? ((options) => runSetup(options, { enroll: setupEnroller })));
+    addSetupCommand(program, io, setup ?? ((options) => runSetup(options, { enroll: setupEnroller })), setupAllCommand(setupAll ?? ((options) => runSetupAll(options, { enroll: setupEnroller })), io));
     return program;
 }
 export async function runCli(argv, io = {
@@ -3273,6 +3300,6 @@ export async function runCli(argv, io = {
         ...options.clientOptions,
         resolveCredentials: fileAwareCredentials(selection, options.env ?? process.env),
     });
-    const program = createProgram(resolved, io, enrollment, doctor, selection, options.setup);
+    const program = createProgram(resolved, io, enrollment, doctor, selection, options.setup, options.setupAll);
     await program.parseAsync(argv, { from: "user" });
 }

package/dist/doctor.d.ts

@@ -1,5 +1,5 @@
-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";
+import { type HarnessProcess, 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, type ScopeFile } from "./doctor_scopes.js";
 import { type ScanBudgets, type StorageRunner } from "./keyslot_status.js";
 export type DoctorStatus = "pass" | "fail" | "undetermined";
 export declare const DOCTOR_CHECKS: readonly ["identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime"];
@@ -8,6 +8,19 @@ export interface DoctorCheck {
     status: DoctorStatus;
     reason: string;
 }
+/**
+ * ONBOARD IF-0-ONBOARD-3 — `runtime`'s informational hint. It never changes `runtime`'s status or
+ * reason, or the exit code (pinned in `doctor_runtime_hint.test.ts`'s exit-invariance cases); where
+ * it overlaps `registration`'s existing `plugin_pin_mismatch`, that reason stays and the hint only
+ * explains it. Precedence when more than one applies: `session_predates_install`, then `no_session`
+ * (zero live records, and no pre-install process found either), then `stale_session_version`, then
+ * `no_target_first_session`, then `none`. `session_predates_install` is checked FIRST, ahead of
+ * `no_session`, because the motivating case (a harness that wrote no record at all before setup
+ * finished — the macmini claude case) has zero live records: a `no_session`-first order would
+ * mask it.
+ */
+export declare const RUNTIME_HINTS: readonly ["no_session", "stale_session_version", "session_predates_install", "no_target_first_session", "none"];
+export type RuntimeHint = (typeof RUNTIME_HINTS)[number];
 /**
  * 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
@@ -49,6 +62,12 @@ export interface DoctorReport {
     harness: IdentityHarness;
     exit: 0 | 1 | 2;
     checks: Record<DoctorCheckName, DoctorCheck>;
+    /**
+     * ONBOARD IF-0-ONBOARD-3 — informational only; omitted (not `"none"`) when nothing was found, so
+     * `Object.keys(report)` for a report with no `installedAt`/`installedVersion` evidence carried in
+     * is byte-unchanged from before this field existed.
+     */
+    runtime_hint?: RuntimeHint;
     /** keyslot identities only (IF-552-3). */
     key_storage_scan?: KeyStorageScanReport;
     /** claude only. */
@@ -149,6 +168,35 @@ export interface DoctorOptions {
     statusBudgets?: Partial<ScanBudgets>;
     /** key_storage: the clock the carry's validity window reads, epoch seconds. Default now. */
     nowSeconds?: () => number;
+    /**
+     * ONBOARD IF-0-ONBOARD-3 — when this harness's board package was last installed or upgraded.
+     * Overrides the default (`defaultInstallEvidence`, derived from doctor's own registration scan:
+     * claude's plugin verdict, or the winning scope file's mtime for every other harness). Where
+     * neither an override nor the default can prove one, `runtime_hint` never fires
+     * `session_predates_install`/`stale_session_version` from it — never fabricated from a guess.
+     */
+    installedAt?: Date;
+    /**
+     * ONBOARD IF-0-ONBOARD-3 — the version setup just installed or upgraded a package to, by that
+     * package's `packageName` (a live record's own field, since one harness's live records can carry
+     * more than one package — e.g. pi's own `wake_producer` plus mcp's `tools_only`, R-2). Overrides
+     * the default the same way `installedAt` does; null (or omitted entirely) makes no claim.
+     */
+    installedVersion?: (packageName: string) => string | null;
+    /**
+     * ONBOARD IF-0-ONBOARD-3 — this harness's own running processes, for `session_predates_install`.
+     * Default: the client's `listHarnessProcesses`. Test injection only needs to honour
+     * `startedBefore` when it cares about the cutoff; production always passes it.
+     */
+    harnessProcesses?: (harness: IdentityHarness, options: {
+        startedBefore?: Date;
+    }) => HarnessProcess[];
+    /**
+     * ONBOARD IF-0-ONBOARD-3 — the default `installedAt` derivation's own file-mtime read, for the
+     * config/plugin-source file that named a package's pinned version. Default: `fs.statSync(path).mtime`.
+     * Unrelated to `registrationFs.lstat`, which carries no mtime.
+     */
+    statMtime?: (path: string) => Date | null;
 }
 /** The key step's clean fresh scan, as setup carries it to its own doctor (IF-552-3). */
 export interface SetupScan {
@@ -218,6 +266,38 @@ interface FileIdentity {
 }
 /** IF-0-CREDPATH-4 runtime, over already-read records. Exported for its fixtures. */
 export declare function judgeRuntime(harness: IdentityHarness, entries: readonly SessionRecordEntry[], identity: FileIdentity | null): DoctorCheck;
+/**
+ * ONBOARD IF-0-ONBOARD-3 — `runtime_hint`, over the SAME already-read `entries` `judgeRuntime` saw.
+ * Exported for its fixtures. Never reads `checks.runtime`'s own verdict, and never influences it:
+ * this is purely informational (see `RUNTIME_HINTS`'s doc comment for the precedence).
+ */
+export declare function judgeRuntimeHint(harness: IdentityHarness, entries: readonly SessionRecordEntry[], fs: Pick<RegistrationFs, "realpath">, options: Pick<DoctorOptions, "installedAt" | "installedVersion" | "harnessProcesses">): RuntimeHint;
+export interface DefaultInstallEvidence {
+    installedAt?: Date;
+    installedVersion: (packageName: string) => string | null;
+}
+/**
+ * ONBOARD IF-0-ONBOARD-3 — the default `installedAt`/`installedVersion`, derived ONLY from what
+ * doctor already reads for its own `registration` check (never a new probe): each scope file's
+ * board-identified mcp entry (codex/grok/agy, and claude's own non-plugin mcp registrations — an
+ * `npx -y @consiliency/agent-board-mcp@<version> …` stanza) and `packages`/`plugin` spec (pi,
+ * opencode — a pinned `<package>@<version>` entry). `files` is in ascending precedence (SAME as
+ * `readScopes` returns it), so a later file's match for the same package overrides an earlier
+ * one's, exactly as the harness itself would resolve it.
+ *
+ * For claude, the plugin verdict `pinCheck` already computed and trusts (never an unvalidated
+ * directory source) is preferred over a raw config scan, per its own `versionFrom`/`sourceKind`
+ * guard — the same one `pinCheck` applies.
+ *
+ * `installedAt` is the LATEST mtime among every file that named a version this way: several files
+ * naming different packages (pi's own `packages` row plus an unrelated mcp row) both count, since
+ * either being freshly written is evidence this harness's board setup was just touched. A file (or
+ * a claude directory source) whose mtime cannot be read contributes nothing — not an error, and
+ * never lowers the claim to "no evidence at all" by itself.
+ *
+ * Exported for its fixtures.
+ */
+export declare function defaultInstallEvidence(harness: IdentityHarness, plugin: ClaudePluginSummary | undefined, files: readonly ScopeFile[], fs: RegistrationFs, statMtime: (path: string) => Date | null): DefaultInstallEvidence;
 export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
 /** Human-readable form; `--json` prints the report object itself. */
 export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/doctor.js

@@ -10,17 +10,32 @@
 // 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 { readdirSync } from "node:fs";
+import { readdirSync, statSync } 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, osKeychainFailureOf, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
-import { judgeRegistration, nodeRegistrationFs, } from "./doctor_scopes.js";
+import { AUTHORED_CAUSE_CODES, AgentSocketSelectionError, GENERIC_SUPABASE_FIELDS, IDENTITY_FILE_KEYS, IDENTITY_TRIGGER_FIELDS, KeystoreUnavailableError, assertIdentityHarness, codeProvenance, createAgentBoardClient, createOsKeychainBackend, expectedWakeTier, listHarnessProcesses, normalizeKeyReference, osKeychainFailureOf, readIdentityFile, readSessionRecords, resolveCredentials, selectAgentSocketIdentity, } from "@consiliency/agent-board-client";
+import { compareVersions } from "./claude_marketplace.js";
+import { CLAUDE_PLUGIN_MCP_PACKAGE, judgeMcpEntry, judgeRegistration, nodeRegistrationFs, packageIdentity, readScopes, } from "./doctor_scopes.js";
 import { resolveKeyslotDir } from "./assets.js";
 import { cacheStateOf, measureKeyslot, progressText, scanOf, scanSourceOf, STATUS_SCAN_TIMEOUT_MS, } from "./keyslot_status.js";
 import { SLOT_RE, externalDeclarationProblems, fileIdentity, keyslotSocketDir, machineIdOf, resolveAgentSocketPath, unsealedOptinProblems, } from "./setup_storage.js";
 export const DOCTOR_CHECKS = Object.freeze([
     "identity_file", "keystore_key", "key_storage", "whoami", "board_membership", "registration", "runtime",
 ]);
+/**
+ * ONBOARD IF-0-ONBOARD-3 — `runtime`'s informational hint. It never changes `runtime`'s status or
+ * reason, or the exit code (pinned in `doctor_runtime_hint.test.ts`'s exit-invariance cases); where
+ * it overlaps `registration`'s existing `plugin_pin_mismatch`, that reason stays and the hint only
+ * explains it. Precedence when more than one applies: `session_predates_install`, then `no_session`
+ * (zero live records, and no pre-install process found either), then `stale_session_version`, then
+ * `no_target_first_session`, then `none`. `session_predates_install` is checked FIRST, ahead of
+ * `no_session`, because the motivating case (a harness that wrote no record at all before setup
+ * finished — the macmini claude case) has zero live records: a `no_session`-first order would
+ * mask it.
+ */
+export const RUNTIME_HINTS = Object.freeze([
+    "no_session", "stale_session_version", "session_predates_install", "no_target_first_session", "none",
+]);
 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
@@ -591,6 +606,120 @@ export function judgeRuntime(harness, entries, identity) {
         return check("undetermined", unique(unknowns));
     return check("pass", "wake_producer_live");
 }
+/**
+ * ONBOARD IF-0-ONBOARD-3 — `runtime_hint`, over the SAME already-read `entries` `judgeRuntime` saw.
+ * Exported for its fixtures. Never reads `checks.runtime`'s own verdict, and never influences it:
+ * this is purely informational (see `RUNTIME_HINTS`'s doc comment for the precedence).
+ */
+export function judgeRuntimeHint(harness, entries, fs, options) {
+    const live = entries.filter((entry) => entry.status === "live")
+        .map((entry) => entry.record);
+    if (options.installedAt) {
+        // Checked even with ZERO live records (the macmini claude case: the harness wrote no record at
+        // all): an empty `live` makes every candidate process uncovered by construction, exactly as it
+        // should. Checking this before the `live.length === 0` fallback below is load-bearing — that
+        // fallback would otherwise short-circuit the one case IF-0-ONBOARD-3 names first.
+        //
+        // The same real-path comparison `pinCheck` uses for a record's cwd against doctor's own: a
+        // process is covered by a live record that is EITHER that process's own writer (pid-equal,
+        // true for pi/opencode's in-process plugin) OR launched from the same directory (true for the
+        // mcp child claude/codex/grok/agy launch, whose own pid never matches the harness's). Two
+        // uncovered sessions sharing one cwd is a stated false negative of the cwd half.
+        const real = (path) => fs.realpath(path) ?? resolve(path);
+        const recordPids = new Set(live.map((record) => record.pid));
+        const recordCwds = new Set(live.map((record) => real(record.cwd)));
+        const installedAt = options.installedAt;
+        const raw = (options.harnessProcesses ?? listHarnessProcesses)(harness, { startedBefore: installedAt });
+        // `startedBefore` is passed through as an optimisation hint to the injected/real lister; this
+        // cutoff is enforced here too, so an injected function that ignores it cannot fabricate a hint.
+        const processes = raw.filter((process) => process.startedAt.getTime() < installedAt.getTime());
+        const uncovered = processes.some((process) => !recordPids.has(process.pid) && !(process.cwd !== null && recordCwds.has(real(process.cwd))));
+        if (uncovered)
+            return "session_predates_install";
+    }
+    if (live.length === 0)
+        return "no_session";
+    if (options.installedVersion) {
+        const stale = live.some((record) => {
+            const installed = options.installedVersion(record.packageName);
+            return installed !== null && (compareVersions(record.packageVersion, installed) ?? 0) < 0;
+        });
+        if (stale)
+            return "stale_session_version";
+    }
+    if (harness === "opencode"
+        && live.some((record) => record.role === "wake_producer" && record.wake.tier === "tier0" && record.wake.reason === "no_target")) {
+        return "no_target_first_session";
+    }
+    return "none";
+}
+/** Default `statMtime`: a file that cannot be stat'd proves nothing, never an error. */
+function defaultStatMtime(path) {
+    try {
+        return statSync(path).mtime;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ONBOARD IF-0-ONBOARD-3 — the default `installedAt`/`installedVersion`, derived ONLY from what
+ * doctor already reads for its own `registration` check (never a new probe): each scope file's
+ * board-identified mcp entry (codex/grok/agy, and claude's own non-plugin mcp registrations — an
+ * `npx -y @consiliency/agent-board-mcp@<version> …` stanza) and `packages`/`plugin` spec (pi,
+ * opencode — a pinned `<package>@<version>` entry). `files` is in ascending precedence (SAME as
+ * `readScopes` returns it), so a later file's match for the same package overrides an earlier
+ * one's, exactly as the harness itself would resolve it.
+ *
+ * For claude, the plugin verdict `pinCheck` already computed and trusts (never an unvalidated
+ * directory source) is preferred over a raw config scan, per its own `versionFrom`/`sourceKind`
+ * guard — the same one `pinCheck` applies.
+ *
+ * `installedAt` is the LATEST mtime among every file that named a version this way: several files
+ * naming different packages (pi's own `packages` row plus an unrelated mcp row) both count, since
+ * either being freshly written is evidence this harness's board setup was just touched. A file (or
+ * a claude directory source) whose mtime cannot be read contributes nothing — not an error, and
+ * never lowers the claim to "no evidence at all" by itself.
+ *
+ * Exported for its fixtures.
+ */
+export function defaultInstallEvidence(harness, plugin, files, fs, statMtime) {
+    const found = new Map();
+    const VERSIONED = /^\d+[\w.+-]*$/;
+    // A live record's own `packageName` (written by the package itself, e.g. pi's `extension.ts`
+    // `PACKAGE_NAME`) is always bare — never carries a source scheme. pi's OWN config spec does
+    // (`npm:@consiliency/agent-board-pi@<v>`, pi's install-manifest convention); opencode's does not.
+    // Strip the scheme here so both key the same way a live record does.
+    const bare = (identity) => (identity.startsWith("npm:") ? identity.slice("npm:".length) : identity);
+    for (const file of files) {
+        for (const entry of file.contribution.mcp) {
+            if (!judgeMcpEntry(entry, fs).board)
+                continue;
+            for (const word of [entry.command ?? "", ...entry.args]) {
+                const identity = packageIdentity(word);
+                const version = word.slice(identity.length + 1);
+                if (identity !== word && VERSIONED.test(version))
+                    found.set(bare(identity), { version, path: file.path });
+            }
+        }
+        for (const spec of file.contribution.packages) {
+            const identity = packageIdentity(spec);
+            const version = spec.slice(identity.length + 1);
+            if (identity !== spec && VERSIONED.test(version))
+                found.set(bare(identity), { version, path: file.path });
+        }
+    }
+    if (harness === "claude" && plugin?.installed && plugin.version
+        && !(plugin.sourceKind === "directory" && plugin.versionFrom !== "source")) {
+        found.set(CLAUDE_PLUGIN_MCP_PACKAGE, { version: plugin.version, path: plugin.sourceKind === "directory" ? plugin.sourcePath : null });
+    }
+    const installedVersion = (packageName) => found.get(packageName)?.version ?? null;
+    const mtimes = [...found.values()]
+        .map((candidate) => (candidate.path ? statMtime(candidate.path) : null))
+        .filter((mtime) => mtime !== null);
+    const installedAt = mtimes.length > 0 ? new Date(Math.max(...mtimes.map((mtime) => mtime.getTime()))) : undefined;
+    return { installedAt, installedVersion };
+}
 function worst(checks) {
     return checks.find((item) => item.status === "fail")
         ?? checks.find((item) => item.status === "undetermined")
@@ -642,17 +771,23 @@ export async function runDoctor(options) {
             checks.board_membership = check("undetermined", "whoami_not_passed");
         }
     }
+    const fs = options.registrationFs ?? nodeRegistrationFs;
     let entries = [];
+    // ONBOARD IF-0-ONBOARD-3: `runtime_hint` is computed further down, once records were read
+    // without throwing (a caught `records_unreadable` must never be misread as `no_session` from the
+    // empty `entries` the catch leaves behind) AND registration has been read (its scope files and
+    // claude's plugin verdict are the default install evidence).
+    let recordsReadable = false;
     try {
         entries = readSessionRecords(harness, { ...trust, env, isAlive: options.isAlive });
         checks.runtime = judgeRuntime(harness, entries, values && { handle: values[HANDLE_KEY], fingerprint: values[FINGERPRINT_KEY] });
+        recordsReadable = true;
     }
     catch (error) {
         checks.runtime = check("undetermined", codeOf(error, "records_unreadable"));
     }
     // Registration is read for this directory and for every live record's.
     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();
     const platform = options.platform ?? process.platform;
     let userName = options.userName;
@@ -678,10 +813,39 @@ export async function runDoctor(options) {
     verdicts[0] = pinCheck(verdicts[0], entries, cwd, fs);
     const registration = worst(verdicts);
     checks.registration = check(registration.status, registration.reason);
+    // ONBOARD IF-0-ONBOARD-3: `runtime_hint`, now that registration (this cwd's scope files and
+    // claude's plugin verdict) has been read — the default install evidence, unless a caller
+    // overrides either half. Computing the default is best-effort: a throw here (an unreadable
+    // scope file, say) leaves both unset rather than failing the whole report.
+    let runtimeHint = "none";
+    if (recordsReadable) {
+        let defaultInstalledAt;
+        let defaultInstalledVersion;
+        if (options.installedAt === undefined || options.installedVersion === undefined) {
+            try {
+                const { files } = readScopes(harness, { cwd, home, env, fs, claudeManagedDir: options.claudeManagedDir ?? defaultClaudeManagedDir(platform),
+                    platform, userName, regQuery: options.regQuery, claudeMarketplacePackaged: options.claudeMarketplacePackaged,
+                    claudeMarketplaceTrust: options.claudeMarketplaceTrust });
+                const evidence = defaultInstallEvidence(harness, verdicts[0].plugin, files, fs, options.statMtime ?? defaultStatMtime);
+                defaultInstalledAt = evidence.installedAt;
+                defaultInstalledVersion = evidence.installedVersion;
+            }
+            catch {
+                // Leave both unset: the hint degrades to what it can prove, never a guess.
+            }
+        }
+        runtimeHint = judgeRuntimeHint(harness, entries, fs, {
+            installedAt: options.installedAt ?? defaultInstalledAt,
+            installedVersion: options.installedVersion ?? defaultInstalledVersion,
+            harnessProcesses: options.harnessProcesses,
+        });
+    }
     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;
     const report = { harness, exit, checks: ordered };
+    if (runtimeHint !== "none")
+        report.runtime_hint = runtimeHint;
     if (keyStorageScan)
         report.key_storage_scan = keyStorageScan;
     const here = verdicts[0];
@@ -721,6 +885,8 @@ function ago(seconds) {
 /** 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.runtime_hint)
+        lines.push(`${"runtime_hint".padEnd(12)} ${report.runtime_hint}`);
     if (report.plugin) {
         const { plugin } = report;
         const counts = report.registration?.hook_counts;

package/dist/identity_writer.d.ts

@@ -1,46 +1 @@
-import { type EnrollmentOutcome } from "@consiliency/agent-board-client";
-export interface OwnerOnlyWriteOptions {
-    syncDirectory?: (path: string) => Promise<void>;
-}
-/** Create `path` exclusively (never following a planted link) at 0600, write, fsync. */
-export declare function writeOwnerOnlyFile(path: string, content: string): Promise<void>;
-/**
- * Write `content` to `path` so a reader sees the old file or the whole new one, never a
- * part: an exclusive 0600 temp beside it, fsync'd, renamed over it, then the directory
- * fsync'd. On any throw before the rename the temp is removed.
- */
-export declare function writeOwnerOnlyFileAtomic(path: string, content: string, options?: OwnerOnlyWriteOptions): Promise<void>;
-export interface IdentityDeployment {
-    boardUrl: string;
-    sessionUrl: string;
-    publishableKey: string;
-}
-/**
- * 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. 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;
-/**
- * The identity file's values for an enrolled agent. The URLs and publishable key come only
- * from `deployment`; everything else from the outcome. Validated by the client's serializer
- * before it is returned.
- */
-export declare function identityValuesFromEnrollment(outcome: EnrollmentOutcome, deployment: IdentityDeployment): Record<string, string>;
-/**
- * Write `harness`'s identity file for this host. Every refusal (bad harness, relative root,
- * invalid host, bad value) fires before the first filesystem change. The directory is then
- * put through the reader's own trusted walk, so the writer never produces a file the loader
- * would refuse to open. Returns the path written.
- */
-export declare function writeIdentityFile(harness: string, values: Readonly<Record<string, string>>, env: NodeJS.ProcessEnv, options?: OwnerOnlyWriteOptions): Promise<string>;
+export { DEPLOYMENT_ENV_NAMES, identityValuesFromEnrollment, resolveIdentityDeployment, writeIdentityFile, writeOwnerOnlyFile, writeOwnerOnlyFileAtomic, type IdentityDeployment, type OwnerOnlyWriteOptions, } from "@consiliency/agent-board-client";