Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* `o2b install` CLI verb.
*
* o2b install # detect-only table
* o2b install --json # detect-only as JSON
* o2b install --target X # plan-only
* o2b install --target X --apply # execute the plan
* o2b install --target X --check # verify
* o2b install --check # verify every known target
* o2b install --target generic --out <p|-> # generic adapter only
* o2b install --target generic --format json|yaml
* o2b install --friction # capability matrix, every runtime
* o2b install --friction --target X # one runtime
* o2b install --friction --base A --compare B # only what differs
*
* Exit codes ({@link INSTALL_EXIT}):
* 0 success / no drift
* 1 I/O / runtime error
* 2 usage error (unknown target, bad flag)
* 3 --check found drift
* 4 user-modified-block conflict on apply (use --force to override)
* 5 --check found a runtime it proved unreachable
* 6 apply refused for want of consent in non-interactive mode (use --yes)
*
* Code 5 exists because 0 was wrong. `--check` used to exit 0 for both
* `not-installed` and `mcp-unreachable`, so `o2b install --check` reported
* success for a runtime whose own adapter had just failed to reach it -
* the one verify state backed by a live query rather than a file read.
* The two are not the same answer and no longer share a code.
*/
import { parseFlags } from "../argparse.ts";
import { ok } from "../output.ts";
import { readSingleLine } from "../brain/helpers.ts";
import type { LaneConsentVerdict } from "../../core/brain/diagnostics.ts";
import { defaultConfigPath, discoverConfig, resolveVault } from "../../core/config.ts";
import { defaultRegistry } from "../../core/install/registry.ts";
import { VAULT_NOT_CONFIGURED_REASON, buildInstallEnv } from "../../core/install/env.ts";
// The canonical adapter set registers itself into `defaultRegistry` at
// module-load time via this barrel (single source of the adapter list).
import "../../core/install/adapters/all.ts";
import { buildPayload, PayloadError } from "../../core/install/payload.ts";
import {
buildFrictionMatrix,
diffFrictionRows,
FRICTION_DIMENSIONS,
frictionRowFor,
type FrictionInput,
} from "../../core/install/friction.ts";
import { isInstallTargetId, type InstallTargetId } from "../../core/runtime/host-facts.ts";
import { renderDataOwnership } from "../../core/install/ownership.ts";
import type { DataOwnership } from "../../core/install/ownership.ts";
import { measureDataOwnership } from "../../core/install/ownership-measure.ts";
import { InstallError, type InstallPlan, type InstallStep } from "../../core/install/types.ts";
import type { ApplyOpts, InstallEnv, VerifyResult } from "../../core/install/types.ts";
import {
applyInstructionBlock,
instructionBlockTargetFor,
instructionStepNoPrecedenceReason,
planInstructionBlock,
} from "../../core/install/instruction-block.ts";
import type { InstructionBlockPlan } from "../../core/install/instruction-block.ts";
import { RULES_BLOCK_ERROR_KIND, RulesBlockError } from "../../core/install/rules-block.ts";
import {
renderApplyJson,
type ApplyInstructionBlockOutcome,
renderApplyResult,
renderDetectJson,
renderDetectTable,
renderFrictionDiff,
renderFrictionDiffJson,
renderFrictionJson,
renderFrictionTable,
renderPlan,
renderPlanJson,
renderVerifyJson,
renderVerifyTable,
} from "./render.ts";
/**
* Every code this verb can return, named once so the docblock above, the
* returns below and the tests all read the same table.
*/
export const INSTALL_EXIT = Object.freeze({
ok: 0,
runtimeError: 1,
usage: 2,
drift: 3,
userModifiedBlock: 4,
mcpUnreachable: 5,
consentRefused: 6,
} as const);
interface ParsedInstallArgs {
readonly target: string | null;
readonly apply: boolean;
readonly yes: boolean;
readonly check: boolean;
readonly friction: boolean;
readonly base: string | null;
readonly compare: string | null;
readonly dryRun: boolean;
readonly force: boolean;
readonly json: boolean;
readonly out: string | null;
readonly format: "json" | "yaml" | null;
readonly vault: string | null;
readonly config: string;
}
function parseInstallArgs(argv: string[]): ParsedInstallArgs {
const { flags } = parseFlags(argv, {
target: { type: "string" },
apply: { type: "boolean" },
yes: { type: "boolean" },
check: { type: "boolean" },
friction: { type: "boolean" },
base: { type: "string" },
compare: { type: "string" },
"dry-run": { type: "boolean" },
force: { type: "boolean" },
json: { type: "boolean" },
out: { type: "string" },
format: { type: "string" },
vault: { type: "string" },
config: { type: "string" },
});
const fmtRaw = flags["format"] as string | undefined;
let format: "json" | "yaml" | null = null;
if (fmtRaw) {
if (fmtRaw !== "json" && fmtRaw !== "yaml") {
throw new UsageError(`--format must be json or yaml, got: ${fmtRaw}`);
}
format = fmtRaw;
}
return {
target: (flags["target"] as string | undefined) ?? null,
apply: Boolean(flags["apply"]),
yes: Boolean(flags["yes"]),
check: Boolean(flags["check"]),
friction: Boolean(flags["friction"]),
base: (flags["base"] as string | undefined) ?? null,
compare: (flags["compare"] as string | undefined) ?? null,
dryRun: Boolean(flags["dry-run"]),
force: Boolean(flags["force"]),
json: Boolean(flags["json"]),
out: (flags["out"] as string | undefined) ?? null,
format,
vault: (flags["vault"] as string | undefined) ?? null,
config: (flags["config"] as string | undefined) ?? defaultConfigPath(),
};
}
class UsageError extends Error {}
/**
* The vault this verb installs FOR, resolved through the one chain the
* rest of the CLI uses.
*
* `--vault` comes first because it is the operator naming the directory in
* the same breath as the command; everything below it is
* {@link resolveVault} verbatim - `VAULT_DIR`, the project pointer, the
* active profile, then the config `vault` key - so the path written into
* an agent's MCP entry is the path every other verb operates on.
*
* This verb used to carry its own chain (`--vault` then the config key
* then `VAULT_DIR`), which put `VAULT_DIR` LAST where the canonical
* resolver puts it FIRST and consulted neither pointers nor profiles. On a
* machine with both settings the installer wrote one vault into the MCP
* config while `o2b status` read another, and nothing reported the split.
*
* The absent case stays the empty string rather than `null`: every caller
* here refuses it by name (`runCheck`, {@link loadPayload}) and an
* `InstallEnv.vault` is typed `string`.
*/
export function resolveInstallVault(explicitVault: string | null, configPath: string): string {
return explicitVault ?? resolveVault(configPath) ?? "";
}
/**
* The `InstallEnv` this run's adapters see.
*
* The construction itself lives in `core/install/env.ts`, shared with
* the MCP `second_brain_wiring` hosts view so the two surfaces cannot
* describe different machines. This wrapper is the CLI's argument
* resolution: `--vault` then the canonical resolver, and the `--config`
* the whole run is parameterised by.
*/
function installEnvForArgs(args: ParsedInstallArgs): InstallEnv {
return buildInstallEnv({
vault: resolveInstallVault(args.vault, args.config),
configPath: args.config,
});
}
function buildApplyOpts(
args: ParsedInstallArgs,
stdout: NodeJS.WriteStream,
stderr: NodeJS.WriteStream,
): ApplyOpts {
return {
dryRun: args.dryRun,
force: args.force,
stdout,
stderr,
...(args.out !== null ? { outPath: args.out } : {}),
...(args.format !== null ? { format: args.format } : {}),
};
}
function loadPayload(args: ParsedInstallArgs, env: InstallEnv) {
const cfg = discoverConfig(args.config).data;
// `env.vault` is already {@link resolveInstallVault}'s answer, and that
// chain ends on the same `vault` config key this used to re-read as a
// fallback. Keeping the second read would mean an empty `env.vault`
// could still produce a payload built against a key the canonical
// resolver had just declined - a third precedence, in one function.
const vault = env.vault;
if (!vault) {
throw new UsageError(
"o2b install: vault not configured. Pass --vault <path>, set VAULT_DIR, or run `o2b init`.",
);
}
return buildPayload({
vault,
agent_name: cfg["agent_name"] ?? process.env["VAULT_AGENT_NAME"] ?? null,
timezone: cfg["timezone"] ?? process.env["VAULT_TIMEZONE"] ?? null,
});
}
/**
* The data-ownership close, for a run that established something.
*
* Built here rather than inside a renderer so BOTH surfaces consume one
* value: the human block and the `data_ownership` JSON field are two views
* of this record, which is what stops them being added separately - the
* failure mode the install verb already had, where the human `--check`
* table is pinned byte-for-byte against the install documents and the JSON
* twin was pinned by nothing.
*
* Every measurement the statement needs is taken by
* {@link measureDataOwnership}, which the onboarding checklist calls too -
* the two surfaces cannot disagree about where the index landed or which
* outbound integrations are configured, because they ask the same
* function. This verb supplies only what it alone owns: the resolved vault
* and the live adapter registry.
*/
function ownershipFor(env: InstallEnv, configPath: string): DataOwnership {
return measureDataOwnership({
vault: env.vault,
configPath,
adapterTargets: defaultRegistry.targets(),
});
}
export async function cmdInstall(argv: string[]): Promise<number> {
let args: ParsedInstallArgs;
try {
args = parseInstallArgs(argv);
} catch (e) {
if (e instanceof UsageError) {
process.stderr.write(`error: ${e.message}\n`);
return INSTALL_EXIT.usage;
}
throw e;
}
// `--friction` is a report over the registry rather than an operation
// on one target, so it is settled before `--target` is read as "act on
// this runtime".
if (args.friction) return runFriction(args);
// `--check` is its own mode — runs verify per target.
if (args.check) return runCheck(args);
// No --target → detect-only mode.
if (!args.target) return runDetect(args);
// --target X with or without --apply.
return await runTarget(args);
}
function runDetect(args: ParsedInstallArgs): number {
const env = installEnvForArgs(args);
const results = defaultRegistry.detectAll(env);
if (args.json) {
process.stdout.write(renderDetectJson(results));
} else {
process.stdout.write(renderDetectTable(results));
}
return INSTALL_EXIT.ok;
}
/**
* Refuse a runtime nobody registered, by name and with the spelling.
*
* One function because three flags now accept a target, and an operator
* who mistyped one is owed the same answer whichever they mistyped.
*/
function refuseUnknownTarget(flag: string, value: string): number {
process.stderr.write(
`error: unknown ${flag}: ${value}. Available: ${defaultRegistry.targets().join(", ")}\n`,
);
return INSTALL_EXIT.usage;
}
/**
* The registered target `value` names, or `null`.
*
* Both halves are required: the registry answers whether an adapter
* exists, the guard answers whether the id is a member of the closed
* vocabulary the fact table is keyed by. A value that passes one and not
* the other is the contradiction
* `tests/core/architecture/host-facts-census.test.ts` exists to prevent,
* and it is refused here rather than indexed into the table.
*/
function resolveTarget(value: string): InstallTargetId | null {
if (defaultRegistry.get(value) === undefined) return null;
return isInstallTargetId(value) ? value : null;
}
/**
* `o2b install --friction` - what each host costs, side by side.
*
* A report, so it never returns a non-zero code for what it FOUND: the
* matrix has no notion of a bad answer, only of an honest one. The only
* refusals are usage refusals, and each one names the flag and the
* spelling it wanted.
*/
function runFriction(args: ParsedInstallArgs): number {
const wantsDiff = args.base !== null || args.compare !== null;
if (wantsDiff && args.target !== null) {
process.stderr.write(
"error: --friction takes either --target <t> or --base <a> --compare <b>, not both\n",
);
return INSTALL_EXIT.usage;
}
if (wantsDiff && (args.base === null || args.compare === null)) {
const missing = args.base === null ? "--base" : "--compare";
process.stderr.write(
`error: --friction diff needs both --base and --compare; ${missing} is missing\n`,
);
return INSTALL_EXIT.usage;
}
for (const [flag, value] of [
["--target", args.target],
["--base", args.base],
["--compare", args.compare],
] as const) {
if (value !== null && resolveTarget(value) === null) return refuseUnknownTarget(flag, value);
}
const env = installEnvForArgs(args);
let payload;
try {
payload = loadPayload(args, env);
} catch (e) {
if (e instanceof UsageError || e instanceof PayloadError) {
process.stderr.write(`error: ${e.message}\n`);
return INSTALL_EXIT.usage;
}
throw e;
}
const input: FrictionInput = { env, payload, adapters: defaultRegistry.list() };
if (wantsDiff) {
const diff = diffFrictionRows(
frictionRowFor(resolveTarget(args.base!)!, input),
frictionRowFor(resolveTarget(args.compare!)!, input),
);
process.stdout.write(args.json ? renderFrictionDiffJson(diff) : renderFrictionDiff(diff));
return INSTALL_EXIT.ok;
}
const matrix =
args.target === null
? buildFrictionMatrix(input)
: {
dimensions: FRICTION_DIMENSIONS,
rows: [frictionRowFor(resolveTarget(args.target)!, input)],
};
process.stdout.write(args.json ? renderFrictionJson(matrix) : renderFrictionTable(matrix));
return INSTALL_EXIT.ok;
}
/**
* The instruction step a target's plan gains, or null when the target
* installs no agent-instruction file (a named skip renders as a
* postNote instead, see {@link augmentPlanWithInstructionStep}).
*
* The step rides the same `runTarget` lane the adapter writes do - one
* plan render, ONE consent verdict above both writes, one apply - so
* there is nothing new to consent to twice (t_ba41a78a B3). The kind is
* the existing `managed-block` member; no new step vocabulary.
*/
function instructionStepFor(
env: InstallEnv,
target: InstallTargetId,
): { step: InstallStep; plan: InstructionBlockPlan } | null {
if (instructionBlockTargetFor(target) === null) return null;
const plan = planInstructionBlock(env, target);
const preview =
plan.changed === true
? `install the Open Second Brain write-gate managed block in ${plan.path}` +
(plan.note === null ? "" : ` (${plan.note})`)
: `${plan.path} already carries the current write-gate managed block (no change)`;
const step: InstallStep = {
kind: "managed-block",
path: plan.path,
preview,
...(plan.diff !== "" ? { diff: plan.diff } : {}),
};
return { step, plan };
}
/**
* Append the instruction step (or its named skip) to a rendered plan.
* Pure over the given plan: the original plan still goes to the adapter,
* and the augmented copy is what the operator consents to.
*/
function augmentPlanWithInstructionStep(
plan: InstallPlan,
target: InstallTargetId,
step: InstallStep | null,
): InstallPlan {
if (step === null) {
return {
...plan,
postNotes: [
...plan.postNotes,
`instruction block: skipped for ${target} - the host reads no agent-instruction file in HOST_INSTRUCTION_PRECEDENCE`,
],
};
}
return { ...plan, steps: [...plan.steps, step] };
}
async function runTarget(args: ParsedInstallArgs): Promise<number> {
const adapter = defaultRegistry.get(args.target!);
if (!adapter) return refuseUnknownTarget("--target", args.target!);
const env = installEnvForArgs(args);
let payload;
try {
payload = loadPayload(args, env);
} catch (e) {
if (e instanceof UsageError) {
process.stderr.write(`error: ${e.message}\n`);
return INSTALL_EXIT.usage;
}
if (e instanceof PayloadError) {
process.stderr.write(`error: ${e.message}\n`);
return INSTALL_EXIT.usage;
}
throw e;
}
const opts = buildApplyOpts(
args,
process.stdout as NodeJS.WriteStream,
process.stderr as NodeJS.WriteStream,
);
const plan = adapter.plan(payload, env);
// t_ba41a78a B3: the instruction step rides this lane. The pure plan
// computes now (reads only); the apply below re-derives it from the
// live disk and refuses if the bytes moved since this render, so what
// the operator consents to is exactly what gets written. A refusal at
// plan time (a symbolic link, malformed markers, an unreadable file)
// must be the named error, never an unhandled rejection: nothing has
// been consented to or written yet, so the run ends here with the
// named message and the runtime exit.
let instruction: ReturnType<typeof instructionStepFor>;
try {
instruction = instructionStepFor(env, args.target as InstallTargetId);
} catch (e) {
if (e instanceof RulesBlockError) {
process.stderr.write(`error: ${e.message}\n`);
return INSTALL_EXIT.runtimeError;
}
throw e;
}
const renderedPlan =
instruction === null
? augmentPlanWithInstructionStep(plan, args.target as InstallTargetId, null)
: augmentPlanWithInstructionStep(plan, args.target as InstallTargetId, instruction.step);
// Plan-only (no --apply, no --check) — print and return.
if (!args.apply) {
if (args.json) {
process.stdout.write(renderPlanJson(renderedPlan));
} else {
process.stdout.write(renderPlan(renderedPlan));
}
return INSTALL_EXIT.ok;
}
// t_b6bcd984: fail-closed consent above the write lane, the canonical
// ladder of `brain upgrade --apply`. Without --yes, a --json or
// non-TTY run refuses before anything is written (the drift guard
// below still fires on an explicit yes); an interactive run sees the
// plan with the file diff and is asked once. A consent gate sits
// above the write guard and never gates dry runs - this path only
// runs with --apply.
if (!args.yes) {
if (args.json || !process.stdin.isTTY) {
const refusal =
`error: o2b install --target ${args.target} --apply requires --yes in ` +
"non-interactive mode (--json or non-TTY stdin); nothing was written";
// M4: under --json the refusal is a JSON envelope on the payload
// stream carrying the reserved `headless-refused` verdict, so a
// headless consumer reads the answer from the channel it parses.
if (args.json) {
process.stdout.write(
JSON.stringify(
{ consent: "headless-refused", written: false, error: refusal.replace(/^error: /, "") },
null,
2,
) + "\n",
);
} else {
process.stderr.write(refusal + "\n");
}
return INSTALL_EXIT.consentRefused;
}
// M15: the consent-time plan renders to stderr, where the prompt
// already rides - stdout is the payload stream, and for
// `--target generic --out -` the plan prefixed the snippet made it
// unparsable. The header drops the dry-run wording: this render is
// asking for apply consent, not previewing a dry run. The plain
// print-only plan (no --apply) keeps its stdout dry-run render
// below.
process.stderr.write(renderPlan(renderedPlan, { consent: true }));
process.stderr.write("Proceed? [y/N] ");
const ans = await readSingleLine();
if (ans.toLowerCase() !== "y" && ans.toLowerCase() !== "yes") {
ok("install cancelled");
return INSTALL_EXIT.ok;
}
}
// M3: the verdict is derived from what happened, not hard-coded - a
// `--yes` consent and an interactive yes stay distinguishable, in the
// same vocabulary protect/unprotect/doctor record.
const consent: LaneConsentVerdict = args.yes ? "yes-flag" : "interactive-yes";
let instructionApply: ReturnType<typeof applyInstructionBlock> | null = null;
try {
const result = adapter.apply(plan, payload, env, opts);
// t_ba41a78a B3: the instruction write runs after the adapter apply,
// under the SAME consent verdict - the prompt above covered both
// writes. A refusal here (hand-edited block, preview drift, symlink)
// leaves the adapter write in place and exits non-zero; a re-run
// converges because the step is idempotent and bound to a fresh
// plan. The approved binding is the plan this run rendered.
if (instruction !== null) {
instructionApply = applyInstructionBlock(env, {
dryRun: opts.dryRun,
force: opts.force,
approved: instruction.plan,
});
}
// An apply that returned changed the machine, so the close fires
// unconditionally here - unlike verify, where exit 0 also covers a
// runtime nobody installed.
const ownership = ownershipFor(env, args.config);
if (args.json) {
// The instruction-block outcome rides the apply payload (the
// uninstall payload has carried the same-named field since its step
// shipped): a headless consumer that consented to a plan whose JSON
// showed the managed-block step reads what that step did from the
// receipt on the stream it parses, not only from the human line.
const instructionBlock: ApplyInstructionBlockOutcome =
instruction === null
? {
file: null,
created: false,
changed: false,
backup_path: null,
skipped_reason: instructionStepNoPrecedenceReason(args.target as InstallTargetId),
}
: {
file: instruction.plan.path,
created: instructionApply?.created ?? false,
changed: instructionApply?.changed ?? false,
backup_path: instructionApply?.backupPath ?? null,
skipped_reason: null,
};
process.stdout.write(renderApplyJson(result, ownership, consent, instructionBlock));
} else {
process.stdout.write(renderApplyResult(result, consent));
// The instruction write is invisible in the adapter's own summary
// (its step count is the adapter's), so one line says what this
// lane did with the operator's consent. The line is derived from
// what the apply actually did - a first install CREATES the file
// and takes no backup, so `backupPath` alone cannot tell created
// from already-current, and claiming "already carries" right after
// creating would be false.
if (instructionApply !== null && !opts.dryRun) {
const path = instruction?.plan.path ?? "";
process.stdout.write(
instructionApply.created
? `instruction block: ${path} created with the write-gate block\n`
: instructionApply.changed
? `instruction block: ${path} now carries the write-gate block\n`
: `instruction block: ${path} already carries the current write-gate block\n`,
);
}
process.stdout.write(renderDataOwnership(ownership));
}
return INSTALL_EXIT.ok;
} catch (e) {
if (e instanceof InstallError && e.kind === "user-modified-block") {
process.stderr.write(`error: ${e.message}\n`);
if (e.hint) process.stderr.write(`hint: ${e.hint}\n`);
return INSTALL_EXIT.userModifiedBlock;
}
if (e instanceof InstallError) {
process.stderr.write(`error: ${e.message}\n`);
if (e.hint) process.stderr.write(`hint: ${e.hint}\n`);
return INSTALL_EXIT.runtimeError;
}
// The instruction step's refusals ride the same exit vocabulary: a
// hand-edited block IS a user-modified-block (exit 4, --force is the
// documented override); every other kind is a named runtime error.
if (e instanceof RulesBlockError) {
process.stderr.write(`error: ${e.message}\n`);
return e.kind === RULES_BLOCK_ERROR_KIND.userModifiedBlock
? INSTALL_EXIT.userModifiedBlock
: INSTALL_EXIT.runtimeError;
}
process.stderr.write(`error: ${(e as Error).message}\n`);
return INSTALL_EXIT.runtimeError;
}
}
function runCheck(args: ParsedInstallArgs): number {
const env = installEnvForArgs(args);
// `verify()` reads the per-vault sidecar manifest. With an unset vault,
// every adapter would silently report "not-installed" off a bogus path
// and the operator gets no signal that the vault is unconfigured.
if (!env.vault) {
process.stderr.write(`error: ${VAULT_NOT_CONFIGURED_REASON}\n`);
return INSTALL_EXIT.usage;
}
const targets = args.target
? defaultRegistry.get(args.target)
? [defaultRegistry.get(args.target)!]
: []
: defaultRegistry.list();
if (args.target && targets.length === 0) {
process.stderr.write(
`error: unknown --target: ${args.target}. ` +
`Available: ${defaultRegistry.targets().join(", ")}\n`,
);
return INSTALL_EXIT.usage;
}
const results: VerifyResult[] = [];
for (const a of targets) results.push(a.verify(env));
// Exit 0 is NOT the trigger. `not-installed` is also 0, deliberately -
// the operator never asked for that runtime - so a close fired on the
// code would be the entire output of a run where the install did
// nothing, congratulating an operator on a brain nothing points at.
const ownership = results.some((r) => r.status === "ok") ? ownershipFor(env, args.config) : null;
if (args.json) {
process.stdout.write(renderVerifyJson(results, ownership));
} else {
process.stdout.write(renderVerifyTable(results));
if (ownership !== null) process.stdout.write(renderDataOwnership(ownership));
}
return exitCodeForVerify(results);
}
/**
* The exit code a `--check` run over `results` earns.
*
* Drift outranks unreachable deliberately, and the order is the operator's
* repair order rather than a severity ranking: a runtime may be unreachable
* BECAUSE its config drifted, so re-running `--apply` is the first move and
* a liveness verdict taken over a wrong config means nothing. `not-installed`
* stays 0 - the operator never asked for that runtime - which is exactly the
* bucket `mcp-unreachable` was wrongly sharing.
*
* Exported for the exit-code tests: `mcp-unreachable` is reachable only from
* an adapter that shells out to a runtime CLI, which a CLI-level test cannot
* stage without also staging that runtime.
*/
export function exitCodeForVerify(results: ReadonlyArray<VerifyResult>): number {
if (results.some((r) => r.status === "drift")) return INSTALL_EXIT.drift;
if (results.some((r) => r.status === "mcp-unreachable")) return INSTALL_EXIT.mcpUnreachable;
return INSTALL_EXIT.ok;
}