@the-librarian/cli 1.0.0-rc.5 → 1.0.0-rc.51

package/README.md

@@ -1,16 +1,26 @@
 # `@the-librarian/cli` — the `librarian` installer
 
-A small cross-harness CLI that installs, updates, and tracks
-[The Librarian](https://github.com/JimJafar/the-librarian)'s integrations across
-all your harnesses and machines. Think of it as the package manager for your
-Librarian setup: one tool you keep, driving each harness's **native** install
-path rather than hand-editing five config formats.
+A small CLI that does two jobs for
+[The Librarian](https://github.com/JimJafar/the-librarian): it **wires it into
+your AI agents** (installs/updates the integration for each harness, across all
+your machines) and **self-hosts the server** they talk to (`server up` /
+`update`). Think of it as the package manager for your Librarian setup: one tool
+you keep, driving each harness's **native** install path rather than hand-editing
+five config formats.
 
-Harnesses it manages: **Claude Code, Codex, OpenCode, Hermes, Pi.**
+Harnesses it manages: **Claude Code, Codex, OpenCode, Hermes, Pi.** For the
+server side, see [Self-host the server](#self-host-the-server).
 
 ## Install
 
-Install the CLI globally, then run the interactive setup:
+Run it straight from npm with `npx` — no global install needed:
+
+```sh
+npx @the-librarian/cli install
+```
+
+Prefer a persistent command? Install it globally once and call `librarian`
+directly:
 
 ```sh
 npm i -g @the-librarian/cli
@@ -36,6 +46,12 @@ librarian config                 Show or set MCP URL, token, server URL
 librarian self-update            Update the CLI itself (coming in a later release)
 librarian report                 Push this machine's state to the server
                                   (coming in a later release)
+
+librarian server up              Self-host the server with Docker; prints the
+                                  MCP URL + agent token to paste into `install`
+librarian server update          Upgrade the server to the latest release
+                                  (your data is preserved)
+librarian server down|status|logs  Stop / inspect / tail the running server
 ```
 
 Useful flags: `--mcp-url <url>`, `--token <token>` (never printed),
@@ -44,6 +60,36 @@ Useful flags: `--mcp-url <url>`, `--token <token>` (never printed),
 harness whose CLI isn't installed is reported `not-detected` and skipped — not
 an error.
 
+## Self-host the server
+
+The Librarian needs a server to talk to. `server up` stands one up with Docker —
+it builds the all-in-one image, mints your secrets, waits for health, and prints
+the MCP URL + agent token to paste into `librarian install`:
+
+```sh
+npx @the-librarian/cli server up
+```
+
+By default the vault lives in a Docker-managed named volume (`librarian_data`).
+To keep your data at a path **you** choose — so you can back it up, put it on a
+specific disk, or move it between hosts — pass `--data-dir`:
+
+```sh
+npx @the-librarian/cli server up --data-dir /srv/librarian
+```
+
+With `--data-dir`, the server bind-mounts that directory at `/data` and runs the
+container **as the directory's owner**, so the vault stays owned by — and
+writable by — you, not a container user. The directory is created if it doesn't
+exist, and `server update` reuses it automatically. (`--data-dir` and
+`--data-volume` are mutually exclusive.)
+
+Other server commands: `server update` (upgrade to the latest release, preserving
+your data), `server down` / `status` / `logs`, and `server enable-boot` (Linux
+systemd) to start it on boot. Run it on a private network / behind a VPN, or
+expose it with auth — see the
+[deployment guide](https://github.com/JimJafar/the-librarian/blob/main/DEPLOYMENT.md).
+
 ## What it writes to your environment
 
 The CLI keeps everything under `~/.librarian/`:

package/dist/archive.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract `subPath` (a POSIX path *inside* the repo root, e.g.
+ * `integrations/codex`) out of a codeload `.tar.gz` and return the absolute
+ * path to it. The returned directory's CONTENTS are the subtree's contents —
+ * matching the old `--strip-components` semantics, so callers copy from the
+ * returned path unchanged.
+ *
+ * @param tarball  path to the downloaded `.tar.gz`
+ * @param work     scratch dir to extract into (caller owns its lifecycle)
+ * @param subPath  POSIX subtree path inside the repo root, e.g. `integrations/codex`
+ * @throws if tar exits non-zero, the tarball layout is unexpected, or the
+ *         requested subtree is absent — with a message safe to show the user.
+ */
+export declare function extractAdapterSubtree(tarball: string, work: string, subPath: string): Promise<string>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/archive.js

@@ -0,0 +1,58 @@
+// Portable extraction of a single integration subtree out of a GitHub
+// codeload tarball.
+//
+// The harness capture adapters (Codex / OpenCode / Hermes) don't ship inside
+// their plugin packages — the installer downloads the pinned release tarball
+// from codeload and copies one `integrations/<harness>/…` subtree out of it.
+//
+// History: the original approach selected members directly with
+//   tar -xzf t -C out --strip-components=N --wildcards '*/integrations/<h>/*'
+// That is GNU-tar-only. BSD/libarchive tar (the `/usr/bin/tar` on macOS)
+// rejects the flag outright — `tar: Option --wildcards is not supported` —
+// and busybox tar lacks it too, so the Codex/OpenCode/Hermes steps failed on
+// every non-GNU box. (GNU tar needs `--wildcards` to glob member names on
+// extract; BSD tar globs by default and has no such flag — there is no single
+// flag set that means "glob members" on both.)
+//
+// Fix: extract the whole archive using only the universally-supported
+// `-xzf`/`-C` flags, then locate the wanted subtree with the filesystem. No
+// `--wildcards`, no `--strip-components`, no tar-flavour detection.
+import fs from "node:fs";
+import path from "node:path";
+import { run } from "./exec.js";
+/**
+ * Extract `subPath` (a POSIX path *inside* the repo root, e.g.
+ * `integrations/codex`) out of a codeload `.tar.gz` and return the absolute
+ * path to it. The returned directory's CONTENTS are the subtree's contents —
+ * matching the old `--strip-components` semantics, so callers copy from the
+ * returned path unchanged.
+ *
+ * @param tarball  path to the downloaded `.tar.gz`
+ * @param work     scratch dir to extract into (caller owns its lifecycle)
+ * @param subPath  POSIX subtree path inside the repo root, e.g. `integrations/codex`
+ * @throws if tar exits non-zero, the tarball layout is unexpected, or the
+ *         requested subtree is absent — with a message safe to show the user.
+ */
+export async function extractAdapterSubtree(tarball, work, subPath) {
+    const raw = path.join(work, "raw");
+    fs.mkdirSync(raw, { recursive: true });
+    // Only `-xzf`/`-C` — supported by GNU tar, BSD/libarchive tar, and busybox.
+    const extract = await run("tar", ["-xzf", tarball, "-C", raw]);
+    if (extract.code !== 0) {
+        throw new Error((extract.stderr || "").trim() || `tar exited with code ${extract.code}`);
+    }
+    // codeload wraps everything in a single top-level dir whose name depends on
+    // the ref (GitHub strips a leading `v` from tags: `v1.2.3` → `…-1.2.3`), so
+    // discover it rather than hardcode it.
+    const tops = fs.readdirSync(raw).filter((e) => !e.startsWith("."));
+    const top = tops.length === 1 ? tops[0] : tops.find((e) => e.startsWith("the-librarian-"));
+    if (!top) {
+        throw new Error(`unexpected tarball layout (top-level entries: ${tops.join(", ") || "none"})`);
+    }
+    const dir = path.join(raw, top, ...subPath.split("/"));
+    if (!fs.existsSync(dir)) {
+        throw new Error(`adapter path '${subPath}' not found under '${top}' in tarball`);
+    }
+    return dir;
+}
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,oBAAoB;AACpB,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,EAAE;AACF,gEAAgE;AAChE,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,8EAA8E;AAC9E,+CAA+C;AAC/C,EAAE;AACF,sEAAsE;AACtE,4EAA4E;AAC5E,oEAAoE;AAEpE,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAe,EACf,IAAY,EACZ,OAAe;IAEf,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,4EAA4E;IAC5E,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,wBAAwB,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3F,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,iDAAiD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,iBAAiB,OAAO,sBAAsB,GAAG,cAAc,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/harnesses/codex.d.ts

@@ -1,3 +1,16 @@
 import type { HarnessModule } from "./types.js";
+export declare const CODEX_CAPTURE_PINNED_REF: string;
+/**
+ * Fetches the Codex capture integration for a pinned ref and returns the absolute
+ * path to a directory whose contents ARE the integration (the equivalent of
+ * `integrations/codex/`, i.e. holding `scripts/**` and `hooks/codex-hooks.json`).
+ * The caller copies from there. Injectable so tests substitute a local fixture
+ * instead of the network.
+ */
+export type CaptureFetcher = (ref: string) => Promise<string>;
+/** Override the capture-adapter fetcher (tests inject a local-fixture fetcher). */
+export declare function setCodexCaptureFetcher(next: CaptureFetcher): void;
+/** Restore the default (network) capture-adapter fetcher (tests). */
+export declare function resetCodexCaptureFetcher(): void;
 export declare const codex: HarnessModule;
 //# sourceMappingURL=codex.d.ts.map

package/dist/harnesses/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/harnesses/codex.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,YAAY,CAAC;AA6F/D,eAAO,MAAM,KAAK,EAAE,aAuDnB,CAAC"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/harnesses/codex.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,YAAY,CAAC;AA0C/D,eAAO,MAAM,wBAAwB,QAAqB,CAAC;AAsF3D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AA0B9D,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAEjE;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AA4HD,eAAO,MAAM,KAAK,EAAE,aAiDnB,CAAC"}

package/dist/harnesses/codex.js

@@ -16,9 +16,12 @@
 // it resolves the value at request time. We pass `cfg.mcpUrl` (not the
 // token) on the CLI, so nothing secret is ever logged.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { extractAdapterSubtree } from "../archive.js";
 import { run, which } from "../exec.js";
-import { codexConfigPath } from "../paths.js";
+import { codexCaptureDir, codexConfigPath, codexHooksPath } from "../paths.js";
+import { cliVersion } from "../version.js";
 const CLI = "codex";
 const SERVER_ID = "librarian";
 const TOKEN_ENV_VAR = "LIBRARIAN_AGENT_TOKEN";
@@ -27,6 +30,37 @@ const TABLE_HEADER = "[mcp_servers.librarian]";
 // though TOML carries no native version for an MCP entry.
 const CONFIG_VERSION = "1";
 const VERSION_MARKER = "# librarian-config-version =";
+// ── Auto-capture hooks wiring (spec 2026-06-16-harness-auto-capture, Phase 2A) ─
+//
+// Codex fires the same command-hook events as Claude (UserPromptSubmit / Stop /
+// SessionEnd). Codex discovers lifecycle hooks ONLY at ~/.codex/hooks.json (no
+// plugin host auto-wires them), so — mirroring mem0's install_codex_hooks.py — we
+// MERGE our entries into that file (creating it if absent) and surface the
+// `codex_hooks = true` feature-flag requirement. The merge is idempotent: entries
+// we own are identified by an owner marker in the command string and stripped
+// before fresh ones are added, so re-install/upgrade leaves no duplicates.
+//
+// The capture-adapter scripts (integrations/codex/scripts/**) do NOT ship with
+// the published installer (it ships only dist/), so — exactly like the Hermes
+// adapter — we FETCH them from the pinned release tarball and copy them under
+// ~/.librarian/codex-capture; the merged hook commands point their
+// ${LIBRARIAN_CODEX_ROOT} placeholder at that dir.
+//
+// ASSUMPTION (the one genuine unknown): the assumed hook events + payload shape
+// are derived from mem0's proven Codex wiring + the Claude payload (documented in
+// integrations/codex/scripts/lib/transcript.mjs). SC1 (true e2e against a running
+// Codex) is DEFERRED — there is no codex CLI on the build machine to confirm.
+// The placeholder in hooks/codex-hooks.json, rewritten to the absolute scripts
+// install dir at merge time. Matches the env var the entry shell reads.
+const ROOT_PLACEHOLDER = "${LIBRARIAN_CODEX_ROOT}";
+// Substring that identifies entries THIS installer owns (stable across install
+// paths), so the merge can strip + re-add idempotently. Mirrors mem0's
+// OWNER_MARKER = "mem0-plugin".
+const HOOKS_OWNER_MARKER = "the-librarian-codex";
+// The pinned monorepo release we fetch the adapter from: the tag matching this
+// CLI's own version. DERIVED (not hardcoded) so it can't drift — same rationale
+// as the Hermes adapter's PINNED_REF.
+export const CODEX_CAPTURE_PINNED_REF = `v${cliVersion()}`;
 /** Read config.toml, or "" if it doesn't exist yet. */
 function readConfig() {
     try {
@@ -106,6 +140,133 @@ function writeConfig(content) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, content, "utf8");
 }
+/** The default fetcher: codeload tarball → `tar` extract → integration dir. */
+const defaultCaptureFetcher = async (ref) => {
+    const url = `https://codeload.github.com/JimJafar/the-librarian/tar.gz/refs/tags/${ref}`;
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "librarian-codex-fetch-"));
+    const tarball = path.join(work, "src.tar.gz");
+    const res = await fetch(url, { redirect: "error" });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch Codex capture adapter (${ref}): HTTP ${res.status}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(tarball, buf);
+    // codeload nests the integration at `the-librarian-<ref>/integrations/codex/**`;
+    // the returned dir holds its contents (`scripts/` + `hooks/`), which is what
+    // the caller copies into ~/.librarian/.
+    try {
+        return await extractAdapterSubtree(tarball, work, "integrations/codex");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to extract Codex capture adapter: ${msg}`);
+    }
+};
+let captureFetcher = defaultCaptureFetcher;
+/** Override the capture-adapter fetcher (tests inject a local-fixture fetcher). */
+export function setCodexCaptureFetcher(next) {
+    captureFetcher = next;
+}
+/** Restore the default (network) capture-adapter fetcher (tests). */
+export function resetCodexCaptureFetcher() {
+    captureFetcher = defaultCaptureFetcher;
+}
+/** Recursively copy a directory tree, overwriting any prior copy (idempotent). */
+function copyDir(from, to) {
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.cpSync(from, to, { recursive: true });
+}
+/** Read ~/.codex/hooks.json, or an empty shape if absent/unparseable. */
+function readHooksFile() {
+    try {
+        const raw = fs.readFileSync(codexHooksPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // absent / unreadable / malformed — start from an empty shape
+    }
+    return { hooks: {} };
+}
+function writeHooksFile(config) {
+    const file = codexHooksPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+/** Does this entry belong to us (owner marker in any command string)? */
+function isOwnedEntry(entry) {
+    return (entry.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes(HOOKS_OWNER_MARKER));
+}
+/** Remove every entry we own from a hooks file (so a re-merge can't duplicate). */
+function stripOwnedEntries(config) {
+    const hooks = config.hooks ?? {};
+    for (const event of Object.keys(hooks)) {
+        hooks[event] = (hooks[event] ?? []).filter((e) => !isOwnedEntry(e));
+        if (hooks[event].length === 0)
+            delete hooks[event];
+    }
+    config.hooks = hooks;
+    return config;
+}
+/**
+ * Load our hooks template, rewrite the ${LIBRARIAN_CODEX_ROOT} placeholder to the
+ * absolute scripts dir, and return the parsed shape. The template lives in the
+ * fetched integration dir alongside the scripts it points at.
+ */
+function loadTemplate(integrationDir, scriptsRoot) {
+    const raw = fs.readFileSync(path.join(integrationDir, "hooks", "codex-hooks.json"), "utf8");
+    // JSON-string-escape the path so a backslash (Windows) can't break the JSON.
+    const safe = JSON.stringify(scriptsRoot).slice(1, -1);
+    const rewritten = raw.split(ROOT_PLACEHOLDER).join(safe);
+    return JSON.parse(rewritten);
+}
+/** Merge template entries onto a (stripped) config, appending per event. */
+function mergeTemplate(config, template) {
+    const hooks = (config.hooks ??= {});
+    for (const [event, entries] of Object.entries(template.hooks ?? {})) {
+        // Only `template.hooks` is iterated, so the template's top-level "//" doc key
+        // (a sibling of `hooks`, not inside it) is never carried over — excluded
+        // structurally, no filtering needed here.
+        (hooks[event] ??= []).push(...entries);
+    }
+    return config;
+}
+/** True iff `codex_hooks = true` is set under [features] in config.toml. */
+function captureFeatureFlagEnabled(config) {
+    for (const line of config.split("\n")) {
+        // Strip an inline comment, then collapse whitespace, so `codex_hooks = true`
+        // (any spacing) matches but a `# codex_hooks = true` comment does not.
+        const stripped = (line.split("#", 1)[0] ?? "").trim().replace(/\s+/g, "");
+        if (stripped === "codex_hooks=true")
+            return true;
+    }
+    return false;
+}
+/**
+ * Wire (or re-wire) the per-turn capture hooks: fetch + copy the adapter scripts,
+ * then idempotently merge our entries into ~/.codex/hooks.json. Returns whether
+ * the user still needs to enable the `codex_hooks` feature flag (so the caller can
+ * surface the hint, mirroring mem0's print_feature_flag_hint).
+ */
+async function installCaptureHooks() {
+    const integrationDir = await captureFetcher(CODEX_CAPTURE_PINNED_REF);
+    const scriptsRoot = codexCaptureDir();
+    copyDir(integrationDir, scriptsRoot);
+    const template = loadTemplate(integrationDir, scriptsRoot);
+    const config = stripOwnedEntries(readHooksFile());
+    writeHooksFile(mergeTemplate(config, template));
+    return { featureFlagNeeded: !captureFeatureFlagEnabled(readConfig()) };
+}
+/** Remove our capture wiring: strip owned hook entries + delete the scripts dir. */
+function uninstallCaptureHooks() {
+    if (fs.existsSync(codexHooksPath())) {
+        writeHooksFile(stripOwnedEntries(readHooksFile()));
+    }
+    fs.rmSync(codexCaptureDir(), { recursive: true, force: true });
+}
 export const codex = {
     id: "codex",
     displayName: "Codex",
@@ -117,32 +278,20 @@ export const codex = {
         return { installed: true, version };
     },
     async install(cfg) {
-        if (await which(CLI)) {
-            // Idempotent: if our table is already present, do nothing.
-            if (hasTable(readConfig()))
-                return;
-            const result = await run(CLI, [
-                "mcp",
-                "add",
-                SERVER_ID,
-                "--url",
-                cfg.mcpUrl,
-                "--bearer-token-env-var",
-                TOKEN_ENV_VAR,
-            ]);
-            if (result.code !== 0) {
-                throw new Error(`codex mcp add failed: ${oneLine(result.stderr || result.stdout)}`);
-            }
-            // Stamp our config-shape version alongside the CLI-written table so
-            // detect can report it (the CLI doesn't write the marker comment).
-            stampVersionIfMissing();
-            return;
+        // Two independently-idempotent halves: (1) the MCP server table (the tools +
+        // primer surface) and (2) the per-turn auto-capture hooks. Both run on every
+        // install so a second install repairs either half if only one is present.
+        await installMcpTable(cfg);
+        const { featureFlagNeeded } = await installCaptureHooks();
+        // Codex won't FIRE lifecycle hooks until `codex_hooks = true` is set under
+        // [features] in config.toml (mirrors mem0's print_feature_flag_hint). We can't
+        // edit a TOML table the user owns safely from here, so we SURFACE the one-time
+        // requirement on stderr. Fail-soft: this is a hint, never a hard failure.
+        if (featureFlagNeeded) {
+            process.stderr.write(`\nCodex auto-capture is wired, but Codex won't run the hooks until you enable the\n` +
+                `feature flag. Add this to ${codexConfigPath()}:\n\n` +
+                `  [features]\n  codex_hooks = true\n\nThen restart Codex.\n`);
         }
-        // Fallback: no `codex` on PATH. We can still write the config file.
-        const config = readConfig();
-        if (hasTable(config))
-            return; // idempotent
-        writeConfig(withTable(config, cfg));
     },
     async uninstall() {
         if (await which(CLI)) {
@@ -155,12 +304,47 @@ export const codex = {
         if (hasTable(config) || parseConfigVersion(config) !== undefined) {
             writeConfig(withoutTable(config));
         }
+        // Remove the auto-capture wiring (owned hook entries + the scripts dir).
+        uninstallCaptureHooks();
     },
     async update(cfg) {
         // Re-applying is idempotent; install short-circuits when present.
         await this.install(cfg);
     },
 };
+/**
+ * Install/repair just the MCP server table — the original Codex wiring. Prefers
+ * the native `codex` CLI; falls back to editing config.toml directly when the CLI
+ * isn't on PATH. Idempotent (a present table is a no-op).
+ */
+async function installMcpTable(cfg) {
+    if (await which(CLI)) {
+        // Idempotent: if our table is already present, do nothing.
+        if (hasTable(readConfig()))
+            return;
+        const result = await run(CLI, [
+            "mcp",
+            "add",
+            SERVER_ID,
+            "--url",
+            cfg.mcpUrl,
+            "--bearer-token-env-var",
+            TOKEN_ENV_VAR,
+        ]);
+        if (result.code !== 0) {
+            throw new Error(`codex mcp add failed: ${oneLine(result.stderr || result.stdout)}`);
+        }
+        // Stamp our config-shape version alongside the CLI-written table so
+        // detect can report it (the CLI doesn't write the marker comment).
+        stampVersionIfMissing();
+        return;
+    }
+    // Fallback: no `codex` on PATH. We can still write the config file.
+    const config = readConfig();
+    if (hasTable(config))
+        return; // idempotent
+    writeConfig(withTable(config, cfg));
+}
 /** If the table exists but our version marker doesn't, add the marker. */
 function stampVersionIfMissing() {
     const config = readConfig();

package/dist/harnesses/codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/harnesses/codex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/harnesses/codex.ts"],"names":[],"mappings":"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"}

package/dist/harnesses/hermes.d.ts

@@ -1,5 +1,5 @@
 import type { HarnessModule } from "./types.js";
-export declare const PINNED_REF = "v1.0.0-rc.5";
+export declare const PINNED_REF: string;
 /**
  * Fetches the Hermes adapter for a pinned ref and returns the absolute
  * path to a directory whose contents ARE the adapter (the equivalent of

package/dist/harnesses/hermes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hermes.d.ts","sourceRoot":"","sources":["../../src/harnesses/hermes.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,YAAY,CAAC;AAK/D,eAAO,MAAM,UAAU,gBAAgB,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAqC9D,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAE5D;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAoDD,eAAO,MAAM,MAAM,EAAE,aA+CpB,CAAC"}
+{"version":3,"file":"hermes.d.ts","sourceRoot":"","sources":["../../src/harnesses/hermes.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,YAAY,CAAC;AAQ/D,eAAO,MAAM,UAAU,QAAqB,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AA2B9D,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAE5D;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAsED,eAAO,MAAM,MAAM,EAAE,aAkDpB,CAAC"}

package/dist/harnesses/hermes.js

@@ -5,9 +5,11 @@
 //   - set `memory.provider = librarian` in `~/.hermes/config.json`.
 //
 //   detect    plugin dir present AND provider set to "librarian"
-//             version comes from the adapter's `plugin.yaml`
+//             version is read from the installed `plugin.yaml`, which install
+//             stamps with the CLI version (the fetched tag's value is a static
+//             placeholder) so status/update can compare installed-vs-latest
 //   uninstall remove the plugin dir + unset the provider key
-//   update    re-fetch + re-copy the adapter (idempotent)
+//   update    re-fetch + re-copy the adapter, re-stamping the version (idempotent)
 //
 // ARTIFACT SOURCING. On a user's machine the adapter does NOT live in the
 // repo — the CLI must fetch it from a pinned release. We download a tarball
@@ -20,12 +22,16 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { run } from "../exec.js";
+import { extractAdapterSubtree } from "../archive.js";
 import { hermesConfigPath, hermesHomeDir, hermesPluginDir } from "../paths.js";
+import { cliVersion } from "../version.js";
 const PROVIDER_ID = "librarian";
-// The pinned monorepo release we fetch the adapter from. Default to the
-// repo's current release tag; the phase gate owns version bumps.
-export const PINNED_REF = "v1.0.0-rc.5";
+// The pinned monorepo release we fetch the adapter from: the tag matching this
+// CLI's own version. DERIVED (not hardcoded) so it can't drift — the published
+// package's version is stamped from the root at publish (scripts/stamp-version.mjs),
+// and the matching `vX.Y.Z` tag exists before the package is published. A
+// hardcoded literal here silently froze at rc.5 once before.
+export const PINNED_REF = `v${cliVersion()}`;
 /** The default fetcher: codeload tarball → `tar` extract → adapter dir. */
 const defaultFetcher = async (ref) => {
     const url = `https://codeload.github.com/JimJafar/the-librarian/tar.gz/refs/tags/${ref}`;
@@ -39,24 +45,15 @@ const defaultFetcher = async (ref) => {
     fs.writeFileSync(tarball, buf);
     // codeload nests the adapter at
     //   the-librarian-<ref>/integrations/hermes/librarian/**
-    // — four leading path components. Strip all four so the adapter's own
-    // files (plugin.yaml, …) land at the extraction root, which is what the
-    // caller copies into `~/.hermes/plugins/librarian/`.
-    const out = path.join(work, "adapter");
-    fs.mkdirSync(out, { recursive: true });
-    const extract = await run("tar", [
-        "-xzf",
-        tarball,
-        "-C",
-        out,
-        "--strip-components=4",
-        "--wildcards",
-        "*/integrations/hermes/librarian/*",
-    ]);
-    if (extract.code !== 0) {
-        throw new Error(`Failed to extract Hermes adapter: ${(extract.stderr || "").trim()}`);
+    // the returned dir holds its contents (the adapter's own files: plugin.yaml,
+    // …), which is what the caller copies into `~/.hermes/plugins/librarian/`.
+    try {
+        return await extractAdapterSubtree(tarball, work, "integrations/hermes/librarian");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to extract Hermes adapter: ${msg}`);
     }
-    return out;
 };
 let fetcher = defaultFetcher;
 /** Override the adapter fetcher (tests inject a local-fixture fetcher). */
@@ -110,6 +107,25 @@ function copyDir(from, to) {
     fs.mkdirSync(path.dirname(to), { recursive: true });
     fs.cpSync(from, to, { recursive: true });
 }
+/**
+ * Overwrite the copied plugin.yaml's `version:` with the CLI version, so the
+ * INSTALLED adapter reports the version that installed it. The fetched tag's
+ * source `version` is a static placeholder; `librarian status`/`update` need the
+ * real version to compare installed-vs-latest honestly. Fail-soft: a missing or
+ * odd plugin.yaml is left as-is (detect just reports no version).
+ */
+function stampAdapterVersion(pluginDir, version) {
+    const file = path.join(pluginDir, "plugin.yaml");
+    try {
+        const raw = fs.readFileSync(file, "utf8");
+        const next = raw.replace(/^(\s*version\s*:).*$/m, `$1 ${version}`);
+        if (next !== raw)
+            fs.writeFileSync(file, next, "utf8");
+    }
+    catch {
+        // no plugin.yaml / unreadable — nothing to stamp.
+    }
+}
 export const hermes = {
     id: "hermes",
     displayName: "Hermes",
@@ -126,6 +142,9 @@ export const hermes = {
         // so re-running is idempotent.
         const adapterDir = await fetcher(PINNED_REF);
         copyDir(adapterDir, hermesPluginDir());
+        // Stamp the installed plugin.yaml with the CLI version (the fetched tag's
+        // source value is a static placeholder) so detect() reports it honestly.
+        stampAdapterVersion(hermesPluginDir(), cliVersion());
         // Set memory.provider = librarian, preserving any other config keys.
         const config = readHermesConfig() ?? {};
         const memory = (config.memory && typeof config.memory === "object" ? config.memory : {});