@bli-cockpit/cli 0.2.49 → 0.2.50

package/dist/commands/memory-install.js

@@ -0,0 +1,378 @@
+/**
+ * `cockpit memory install` / `cockpit memory status` (BLI-3580).
+ *
+ * BLI Memory replaces hosted Supermemory: our own table, our own doors, and an
+ * MCP server (`@bli-cockpit/memory-mcp`, bin `bli-memory-mcp`) that both agent
+ * hosts talk to. Nothing about that reaches an intern's machine unless
+ * something puts it there — the vendor plugin never had a fleet install path,
+ * which is why every machine was configured by hand. This is that path, and it
+ * does not ask: `do-everything` runs it, and the sync tick re-runs it at most
+ * once a day so a machine converges without anyone typing anything.
+ *
+ * What it writes, and where, is in the two halves:
+ *   memory-install-claude.ts   ~/.claude.json (user-scope MCP) + ~/.claude/settings.json (hooks, allow-list)
+ *   memory-install-codex.ts    ~/.codex/config.toml (one table) + ~/.codex/skills/bli-memory/
+ *
+ * What this module owns is the decisions around them:
+ *
+ * - **Where the server is.** `bli-memory-mcp` ships as a DEPENDENCY of
+ *   `@bli-cockpit/cli`, so the canonical lookup is the `node_modules/.bin` on
+ *   the way up from this CLI's own entry point; PATH is the fallback. Nobody
+ *   ever installs a second global package. See `resolveMemoryMcpBin`.
+ * - **No server, no write.** If the bin does not resolve, not one file is
+ *   opened and the outcome is `skipped bin_missing` — see `no_bin_no_write`
+ *   below for why a written-but-inert registration is the worse option.
+ * - **Which config shape.** `bli-memory-mcp --print-config --claude` wins when
+ *   the bin answers it; the built-in template of the same shape is the
+ *   fallback for an older server, and it is only ever used with a bin that
+ *   actually resolved.
+ * - **Never throw at the caller.** The sync tick calls this. A failure is a
+ *   named receipt, never an exception that could cost a machine its
+ *   collection tick.
+ * - **Never claim an install it did not read back** (BLI-2541). Both halves
+ *   re-read and re-parse; this module only aggregates what they proved.
+ */
+import os from "node:os";
+import path from "node:path";
+import { writeLine } from "./cli-io.js";
+import { builtinMemoryInstallConfig, isUnsafeBinPath, MEMORY_MCP_BIN, parsePrintedMemoryInstallConfig, } from "./memory-install-contract.js";
+import { defaultMemoryFileIo, } from "./memory-install-files.js";
+import { installClaudeMemoryIntegration, inspectClaudeMemoryIntegration, } from "./memory-install-claude.js";
+import { installCodexMemoryIntegration, inspectCodexMemoryIntegration, } from "./memory-install-codex.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
+export async function runMemoryInstall(command, io, deps = {}) {
+    const outcome = command.action === "status"
+        ? await inspectMemoryIntegration(command, io, deps)
+        : await installMemoryIntegration(command, io, deps);
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(outcome, null, 2));
+    }
+    else {
+        for (const line of memoryOutcomeLines(outcome))
+            writeLine(io.stdout, line);
+    }
+    return outcome.status === "failed" ? 1 : 0;
+}
+export async function installMemoryIntegration(command, io, deps = {}) {
+    const homeDir = deps.homeDir ?? command.homeDir ?? os.homedir();
+    const platform = deps.platform ?? process.platform;
+    const fileIo = deps.io ?? defaultMemoryFileIo();
+    const resolved = await resolveMemoryConfig(command, io, platform, deps);
+    const targets = [resolved.binTarget];
+    // `no_bin_no_write`: with no resolved server there is nothing safe to
+    // register, so not one file is opened. The bin target carries the reason.
+    if (resolved.config) {
+        targets.push(...(await installClaudeMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            dryRun: command.dryRun,
+            io: fileIo,
+        })));
+        targets.push(...(await installCodexMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            dryRun: command.dryRun,
+            io: fileIo,
+        })));
+    }
+    const outcome = {
+        action: "install",
+        ...aggregate(targets),
+        config_source: resolved.source,
+        bin_found: resolved.config !== null,
+        ...(resolved.bin_source ? { bin_source: resolved.bin_source } : {}),
+        targets,
+    };
+    logMemoryOutcome(outcome, platform);
+    return outcome;
+}
+export async function inspectMemoryIntegration(command, io, deps = {}) {
+    const homeDir = deps.homeDir ?? command.homeDir ?? os.homedir();
+    const platform = deps.platform ?? process.platform;
+    const fileIo = deps.io ?? defaultMemoryFileIo();
+    const resolved = await resolveMemoryConfig(command, io, platform, deps);
+    const targets = [resolved.binTarget];
+    // Without a resolved server there is no shape to compare the stored config
+    // against, so `status` says the one true thing — the server is not here —
+    // rather than reporting four targets against a shape we invented.
+    if (resolved.config) {
+        targets.push(...(await inspectClaudeMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            io: fileIo,
+        })));
+        targets.push(...(await inspectCodexMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            io: fileIo,
+        })));
+    }
+    return {
+        action: "status",
+        ...aggregate(targets),
+        config_source: resolved.source,
+        bin_found: resolved.config !== null,
+        ...(resolved.bin_source ? { bin_source: resolved.bin_source } : {}),
+        targets,
+    };
+}
+/**
+ * **`no_bin_no_write`.** When `bli-memory-mcp` cannot be resolved, this command
+ * writes NOTHING — not the MCP entry, not the hooks, not the Codex table, not
+ * the skills.
+ *
+ * An earlier revision wrote the registration anyway, on the reasoning that a
+ * correct shape waiting for the package is better than nothing. It is not:
+ * Claude Code RUNS a registered hook. Three hooks pointing at a binary that
+ * does not exist would print a hook failure on every SessionStart, every
+ * prompt and every Stop, on every intern machine, until the package shipped —
+ * a self-inflicted outage in the one surface people look at all day.
+ *
+ * So an absent bin is `skipped bin_missing`: a receipt, not a write. The daily
+ * self-heal retries tomorrow, and the first tick after the package lands does
+ * the whole registration at once.
+ */
+async function resolveMemoryConfig(command, io, platform, deps) {
+    const dashboardUrl = await resolveDashboardUrl(command, deps);
+    const found = await resolveMemoryMcpBin({
+        env: envWithNodeRuntimeOnPath(io.env ?? process.env),
+        platform,
+        fileExists: deps.fileExists,
+        cliEntryPoint: deps.cliEntryPoint,
+    });
+    if (!found) {
+        return {
+            config: null,
+            source: "none",
+            binTarget: {
+                target: "bin",
+                status: "skipped",
+                reason: "bin_missing",
+                detail: `${MEMORY_MCP_BIN} is not installed beside this CLI or on PATH; nothing was written, and the next daily run will try again`,
+            },
+        };
+    }
+    if (isUnsafeBinPath(found.path)) {
+        // A hook command is a shell string by the platform's design. A path that
+        // cannot be quoted safely is not escaped cleverly, and it is not swapped
+        // for a bare name that may resolve to something else either — the install
+        // refuses and says why.
+        return {
+            config: null,
+            source: "none",
+            binTarget: {
+                target: "bin",
+                status: "failed",
+                reason: "bin_path_unsafe",
+                detail: "the resolved bin path contains characters that cannot appear in a hook command; nothing was written",
+            },
+            bin_source: found.source,
+        };
+    }
+    const printed = await printedMemoryConfig(io, found.path);
+    if (printed) {
+        return {
+            config: printed,
+            source: "bin",
+            binTarget: { target: "bin", status: "already", reason: "bin_printed_config" },
+            bin_source: found.source,
+        };
+    }
+    return {
+        config: builtinMemoryInstallConfig({
+            binPath: found.path,
+            platform,
+            dashboardUrl,
+        }),
+        source: "template",
+        binTarget: {
+            target: "bin",
+            status: "already",
+            reason: "bin_present_template_used",
+            detail: "the bin did not print a usable --print-config; the built-in shape was used",
+        },
+        bin_source: found.source,
+    };
+}
+/**
+ * Asks the server for its own shape. Arguments go as an ARRAY — nothing is
+ * interpolated into a command line — and on Windows the captured runner routes
+ * a `.cmd` shim through ComSpec with its own escaping (process-runner.ts).
+ */
+async function printedMemoryConfig(io, binPath) {
+    const exec = io.exec;
+    if (!exec)
+        return null;
+    try {
+        const result = await exec(binPath, ["--print-config", "--claude"]);
+        if (result.code !== 0)
+            return null;
+        return parsePrintedMemoryInstallConfig(result.stdout);
+    }
+    catch {
+        // Deliberately silent here: the caller reports
+        // `bin_present_template_used`, which is the same information with a name
+        // on it, and this path is reached on every machine that has an older bin.
+        return null;
+    }
+}
+/**
+ * Two steps, in this order, and the first is the canonical one.
+ *
+ * **1. Beside the CLI that is running.** `bli-memory-mcp` ships as a DEPENDENCY
+ * of `@bli-cockpit/cli`, so installing the CLI installs the server, and npm
+ * links its bin into a `node_modules/.bin` on the path from this entry point up
+ * to the install root — `…/@bli-cockpit/cli/node_modules/.bin` when it is
+ * nested, `…/lib/node_modules/.bin` when npm hoists it. Walking up from
+ * `process.argv[1]` finds it either way, and it is the ONLY lookup that cannot
+ * find somebody else's `bli-memory-mcp`. Nobody ever runs `npm i -g` for a
+ * second package.
+ *
+ * **2. PATH, as a fallback**, for a linked checkout or a hand-installed server.
+ * Done in this process rather than through `which`/`where`: it spawns nothing,
+ * behaves the same on both host families, and is testable without a fixture
+ * binary. The npm global bin sits beside the running node binary in the
+ * standard layouts, which is why the caller passes a PATH that already includes
+ * it (`envWithNodeRuntimeOnPath`) — the launchd tick's PATH is otherwise
+ * `/usr/bin:/bin:/usr/sbin:/sbin` and would find nothing.
+ */
+export async function resolveMemoryMcpBin(options) {
+    const exists = options.fileExists ?? defaultFileExists;
+    const beside = await resolveBesideCli(options, exists);
+    if (beside)
+        return { path: beside, source: "cli_dependency" };
+    const onPath = await resolveOnPath(options, exists);
+    return onPath ? { path: onPath, source: "path" } : null;
+}
+async function resolveBesideCli(options, exists) {
+    const entry = options.cliEntryPoint ?? process.argv[1];
+    if (!entry)
+        return null;
+    const platformPath = options.platform === "win32" ? path.win32 : path.posix;
+    const extensions = binExtensions(options.platform);
+    let directory = platformPath.dirname(platformPath.resolve(entry));
+    // Bounded walk: deep enough for `…/node_modules/@scope/pkg/dist/cli.js` plus
+    // a hoisted root above it, and it stops at the filesystem root anyway.
+    for (let depth = 0; depth < 12; depth += 1) {
+        for (const extension of extensions) {
+            const candidate = platformPath.join(directory, "node_modules", ".bin", `${MEMORY_MCP_BIN}${extension}`);
+            if (await exists(candidate))
+                return candidate;
+        }
+        const parent = platformPath.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return null;
+}
+async function resolveOnPath(options, exists) {
+    // The TARGET platform's path rules, not the running one's. On a real machine
+    // they are the same; asking for them explicitly is what lets the Windows
+    // lookup be tested from a Mac, which is the only Windows proof this repo
+    // gets before a release (AGENTS.md, supported fleet).
+    const platformPath = options.platform === "win32" ? path.win32 : path.posix;
+    const entries = (options.env["PATH"] ?? options.env["Path"] ?? "")
+        .split(platformPath.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const entry of entries) {
+        for (const extension of binExtensions(options.platform)) {
+            const candidate = platformPath.join(entry, `${MEMORY_MCP_BIN}${extension}`);
+            if (await exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** npm writes `.cmd` (and `.ps1`) shims on Windows; POSIX gets the bare name. */
+function binExtensions(platform) {
+    return platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+}
+async function defaultFileExists(file) {
+    const { stat } = await import("node:fs/promises");
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveDashboardUrl(command, deps) {
+    if (command.dashboardUrl)
+        return command.dashboardUrl;
+    const paths = getCollectorRuntimePaths(deps.homeDir ?? command.homeDir);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    return config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
+}
+function aggregate(targets) {
+    const failed = targets.filter((target) => target.status === "failed");
+    if (failed.length > 0) {
+        return {
+            status: "failed",
+            // The first named reason, not a count: an operator needs the reason, and
+            // the per-target list beside it carries the rest.
+            reason: failed[0]?.reason ?? "unknown_failure",
+        };
+    }
+    if (targets.some((target) => target.status === "would_install")) {
+        return { status: "would_install", reason: "dry_run" };
+    }
+    if (targets.some((target) => target.status === "installed")) {
+        return { status: "installed", reason: "wrote_entry" };
+    }
+    if (targets.some((target) => target.status === "mismatch" || target.status === "missing")) {
+        return { status: "missing", reason: "entry_absent" };
+    }
+    const skipped = targets.find((target) => target.status === "skipped");
+    if (skipped) {
+        // Not a failure and not a success: nothing was written, on purpose, and
+        // the next daily run will try again. `bin_missing` is the only one today.
+        return { status: "skipped", reason: skipped.reason };
+    }
+    return { status: "already", reason: "already_current" };
+}
+/**
+ * Both branches log, and neither carries a path — a home directory names a
+ * person, and this line ends up in `sync.err.log` on every machine.
+ */
+function logMemoryOutcome(outcome, platform) {
+    const fields = {
+        status: outcome.status,
+        reason: outcome.reason,
+        config_source: outcome.config_source,
+        bin_found: outcome.bin_found,
+        platform,
+        installed_count: outcome.targets.filter((target) => target.status === "installed").length,
+        already_count: outcome.targets.filter((target) => target.status === "already").length,
+        failed: outcome.targets
+            .filter((target) => target.status === "failed")
+            .map((target) => `${target.target}:${target.reason}`),
+    };
+    // stderr on both branches: launchd captures it to sync.err.log, and stdout is
+    // reserved for `--json`.
+    console.error(outcome.status === "failed"
+        ? "[memory-install] BLI Memory is not fully registered on this machine"
+        : "[memory-install] BLI Memory registration converged", JSON.stringify(fields));
+}
+export function memoryOutcomeLines(outcome) {
+    const headline = outcome.status === "installed"
+        ? "BLI Memory registered on this machine."
+        : outcome.status === "already"
+            ? "BLI Memory is already registered on this machine."
+            : outcome.status === "would_install"
+                ? "BLI Memory would be registered (dry run; nothing was written)."
+                : outcome.status === "missing"
+                    ? "BLI Memory is not registered on this machine."
+                    : outcome.status === "skipped"
+                        ? "BLI Memory was not registered and nothing was written: the bli-memory-mcp server is not on this machine yet."
+                        : `BLI Memory is not fully registered: ${outcome.reason}.`;
+    const lines = [headline];
+    for (const target of outcome.targets) {
+        const where = target.path ? ` ${target.path}` : "";
+        const detail = target.detail ? ` — ${target.detail}` : "";
+        lines.push(`  ${target.target}: ${target.status} (${target.reason})${where}${detail}`);
+    }
+    return lines;
+}

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.49");
+    writeLine(io?.stdout ?? process.stdout, "0.2.50");
     return 0;
   }
 

package/dist/commands/sync-followups.js

@@ -1,4 +1,19 @@
+/**
+ * What the sync tick does AFTER collection's own outcome is decided and
+ * reported: keep this machine's CLI current on npm `latest` (BLI-2601), put a
+ * broken scheduler registration back (BLI-2721), and keep BLI Memory
+ * registered with both agent hosts (BLI-3580).
+ *
+ * Split out of commands/sync.ts (BLI-3578), moved verbatim. They belong
+ * together because they share one rule, and it is the reason both are called
+ * last: a follow-up may never block, delay or fail collection. Every error path
+ * here is swallowed on purpose and reported as its own named receipt — an
+ * `update` step, or an autostart repair step — never as a `sync` failure.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
 import { resolveAutostartRoots } from "./autostart-command.js";
+import { installMemoryIntegration, } from "./memory-install.js";
 import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { runSelfUpdate, SelfUpdateError } from "./install-update.js";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
@@ -78,6 +93,96 @@ async function reportAutostartSelfHealOutcome(command, io, dashboardUrl, result)
         io,
     });
 }
+export const MEMORY_INSTALL_THROTTLE_MARKER = ".last-memory-install";
+const MEMORY_INSTALL_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * BLI-3580: BLI Memory's registration converges on its own.
+ *
+ * Nobody is going to be asked to install a hook. `do-everything` registers it
+ * on the way through, and this puts it back if a host config is edited,
+ * replaced, or restored from a machine that never had it — at most once a day,
+ * because the steady state is "already current" and re-proving that every
+ * fifteen minutes is four file reads a tick for no new information.
+ *
+ * Same rule as the two follow-ups above: it runs only once collection's own
+ * outcome has been decided and reported, it never throws, and its outcome is
+ * its own named receipt rather than a sync failure.
+ */
+export async function runMemoryInstallAfterSync(command, io, dashboardUrl, options = {}) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const now = options.now ?? new Date();
+    const marker = path.join(paths.state_dir, MEMORY_INSTALL_THROTTLE_MARKER);
+    const lastAttempt = await fs.stat(marker).catch(() => null);
+    if (lastAttempt &&
+        now.getTime() - lastAttempt.mtimeMs < MEMORY_INSTALL_MIN_INTERVAL_MS) {
+        return;
+    }
+    // Written for the ATTEMPT, not the outcome — the same idiom the self-update
+    // and autostart repair use, so a machine that cannot write a host config does
+    // not retry it every fifteen minutes.
+    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
+    await fs.writeFile(marker, now.toISOString()).catch(() => undefined);
+    let event;
+    try {
+        const outcome = await installMemoryIntegration({
+            kind: "memory",
+            action: "install",
+            homeDir: command.homeDir,
+            dashboardUrl,
+            dryRun: false,
+            json: command.json,
+        }, io);
+        event = memoryInstallEvent(outcome);
+    }
+    catch (error) {
+        event = {
+            step: "memory_install",
+            status: "fail",
+            error_code: "memory_install_threw",
+            error_detail: redactedSyncErrorDetail(error),
+        };
+    }
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [event],
+        json: command.json,
+        io,
+    });
+}
+/**
+ * Target names and reason labels only. A target's `path` names a person's home
+ * directory and a `write_failed` detail can carry one, so neither travels: the
+ * receipt says `claude_hooks:read_back_mismatch`, which is the part an operator
+ * can act on.
+ */
+function memoryInstallEvent(outcome) {
+    const detail = [
+        `source=${outcome.config_source}`,
+        ...outcome.targets.map((target) => `${target.target}:${target.status}/${target.reason}`),
+    ].join("; ");
+    if (outcome.status === "failed") {
+        return {
+            step: "memory_install",
+            status: "fail",
+            error_code: outcome.reason,
+            error_detail: detail,
+        };
+    }
+    if (outcome.status === "skipped") {
+        // Nothing was written, on purpose (`no_bin_no_write`). A fleet-wide
+        // `bin_missing` is the receipt that says the server package has not
+        // reached the machines yet — a fact, not a fault.
+        return {
+            step: "memory_install",
+            status: "skipped",
+            error_code: outcome.reason,
+            error_detail: detail,
+        };
+    }
+    return { step: "memory_install", status: "ok", error_detail: detail };
+}
 /**
  * BLI-2601: the fleet keeps itself current on npm `latest` without anyone
  * re-running `npm i -g @bli-cockpit/cli` by hand after day 0. This always

package/dist/commands/sync.js

@@ -5,7 +5,7 @@ import { discoverCommandWorktrees } from "./local-discovery.js";
 import { sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
 import { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { runAttributedWorktreeSync, } from "./session-sync.js";
-import { runAutostartSelfHealAfterSync, runScheduledSelfUpdateAfterSync, } from "./sync-followups.js";
+import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, } from "./sync-followups.js";
 import { describeError } from "../health-detail.js";
 import { inspectBackfillLock } from "../backfill-lock.js";
 import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
@@ -49,6 +49,9 @@ export async function runSync(command, io) {
         // already decided and reported, win or lose. See the function doc.
         await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
         await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
+        // BLI-3580: BLI Memory's registration converges the same way — after
+        // collection, at most once a day, its own receipt either way.
+        await runMemoryInstallAfterSync(command, io, dashboardUrl);
         return result.exitCode;
     }
     catch (error) {
@@ -77,6 +80,9 @@ export async function runSync(command, io) {
         });
         await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
         await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
+        // BLI-3580: BLI Memory's registration converges the same way — after
+        // collection, at most once a day, its own receipt either way.
+        await runMemoryInstallAfterSync(command, io, dashboardUrl);
         throw error;
     }
 }

package/dist/local-state-attributed-target.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { normalizeGitOrigin, repoFingerprintFromLocalRoot, repoFingerprintFromOrigin, repoLabelFromOrigin, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
+import { isSamePath } from "./root-normalization.js";
+/**
+ * A transcript-attributed target is an identity a CALLER built — for a wrapper
+ * folder or a repo that no longer exists on disk — so every field of it is
+ * re-derived here before a single byte of context state is written. Nothing
+ * downstream can tell an invented fingerprint from a real one.
+ *
+ * The checks run in a fixed order and each throws its own sentence, so the
+ * first thing wrong is the thing the operator is told about.
+ */
+export async function validateAttributedTargetIdentity(requestedRepoRoot, identity) {
+    const canonicalRoot = await stableWorktreeRoot(requestedRepoRoot);
+    const identityRoot = await stableWorktreeRoot(identity.repo_root);
+    const identityRequestedPath = await stableWorktreeRoot(identity.requested_path);
+    if (!isSamePath(canonicalRoot, identityRoot) ||
+        !isSamePath(canonicalRoot, identityRequestedPath)) {
+        throw new Error("Attributed target identity paths do not match the requested repo root.");
+    }
+    const expectedWorktreeFingerprint = stableWorktreeFingerprint(canonicalRoot);
+    if (identity.worktree_fingerprint !== expectedWorktreeFingerprint) {
+        throw new Error("Attributed target worktree fingerprint does not match its repo root.");
+    }
+    const expectedWorktreeLabel = path.basename(canonicalRoot) || "workspace";
+    if (identity.worktree_label !== expectedWorktreeLabel) {
+        throw new Error("Attributed target worktree label does not match its repo root.");
+    }
+    if (identity.repo_origin_url) {
+        assertRepoFieldsMatchOrigin(identity, identity.repo_origin_url);
+    }
+    else {
+        assertRepoFieldsMatchLocalRoot(identity, canonicalRoot, expectedWorktreeLabel);
+    }
+    return {
+        ...identity,
+        requested_path: canonicalRoot,
+        repo_root: canonicalRoot,
+    };
+}
+/**
+ * An origin-derived target is a repo reconstructed from transcript
+ * provenance, so it may not claim to be the live primary worktree of anything.
+ */
+function assertRepoFieldsMatchOrigin(identity, repoOriginUrl) {
+    const normalizedOrigin = normalizeGitOrigin(repoOriginUrl);
+    if (normalizedOrigin !== repoOriginUrl) {
+        throw new Error("Attributed target repo origin is not normalized.");
+    }
+    if (identity.repo_fingerprint !== repoFingerprintFromOrigin(normalizedOrigin)) {
+        throw new Error("Attributed target repo fingerprint does not match its origin.");
+    }
+    if (identity.repo_label !== repoLabelFromOrigin(normalizedOrigin)) {
+        throw new Error("Attributed target repo label does not match its origin.");
+    }
+    if (identity.worktree_is_primary) {
+        throw new Error("Origin-derived attributed targets cannot claim a primary live worktree.");
+    }
+}
+/**
+ * Without an origin the only thing an identity can honestly be derived from is
+ * the local root, so the fingerprint, the label and primacy all follow from it.
+ */
+function assertRepoFieldsMatchLocalRoot(identity, canonicalRoot, expectedWorktreeLabel) {
+    if (identity.repo_fingerprint !==
+        repoFingerprintFromLocalRoot(canonicalRoot)) {
+        throw new Error("Attributed target repo fingerprint does not match its local root.");
+    }
+    if (identity.repo_label !== expectedWorktreeLabel) {
+        throw new Error("Attributed target repo label does not match its local root.");
+    }
+    if (!identity.worktree_is_primary) {
+        throw new Error("Local attributed targets must use their primary local identity.");
+    }
+}