@rightkit/release 0.2.65 → 0.2.67

package/progress-control.test.mjs

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { cancelAndReapManagedRequest, firstManagedRequestId, latestManagedRequestId, releaseProgressLimits, terminalResultFromOutput } from "./progress-control.mjs";
+
+test("release progress stays bounded without killing a healthy long native build at 90 minutes", () => {
+  assert.deepEqual(releaseProgressLimits({}), { inactivityMs: 600_000, absoluteMs: 14_400_000 });
+  assert.deepEqual(releaseProgressLimits({ RIGHT_RELEASE_STALL_MS: "1000", RIGHT_RELEASE_ABSOLUTE_MS: "5000" }), { inactivityMs: 1_000, absoluteMs: 5_000 });
+  assert.throws(() => releaseProgressLimits({ RIGHT_RELEASE_STALL_MS: "1000", RIGHT_RELEASE_ABSOLUTE_MS: "1000" }), /must exceed/);
+  assert.throws(() => releaseProgressLimits({ RIGHT_RELEASE_STALL_MS: "nope" }), /positive finite/);
+});
+
+test("latest managed request id follows streamed root Cargo requests", () => {
+  const first = "11111111-1111-4111-8111-111111111111";
+  const second = "22222222-2222-4222-8222-222222222222";
+  assert.equal(latestManagedRequestId(`rightkit: request ${first}\nrightkit managed-agent: request ${second}`), second);
+  assert.equal(firstManagedRequestId(`rightkit: request ${first}\nrightkit managed-agent: request ${second}`), first);
+  assert.equal(latestManagedRequestId("ordinary output", first), first);
+});
+
+test("managed cancellation issues CANCEL, waits for terminal RESULT, & returns reap receipt", async () => {
+  const id = "33333333-3333-4333-8333-333333333333";
+  const calls = [];
+  const run = async (args) => {
+    calls.push(args);
+    if (args[0] === "cancel") return { code: 0, output: JSON.stringify({ type: "CANCEL_REQUESTED", id }) };
+    return { code: 130, output: `compiler tail\n${JSON.stringify({ type: "RESULT", id, status: "CANCELLED", exitCode: 130, receipt: { reap: { reaped: true } } })}\n` };
+  };
+  assert.deepEqual(await cancelAndReapManagedRequest(id, { run }), {
+    status: "CANCELLED", id, exitCode: 130, receipt: { reap: { reaped: true } }, cancelExitCode: 0, attachExitCode: 130,
+  });
+  assert.deepEqual(calls, [["cancel", id], ["attach", id]]);
+});
+
+test("missing terminal broker result fails closed", async () => {
+  const run = async () => ({ code: 125, output: "broker closed", timedOut: false });
+  await assert.rejects(cancelAndReapManagedRequest("44444444-4444-4444-8444-444444444444", { run }), /lacked terminal RESULT/);
+  assert.equal(terminalResultFromOutput("noise\n"), null);
+});

package/registry-parity.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = fileURLToPath(new URL('.', import.meta.url));
+
+async function files(root, relative = '') {
+  const entries = await readdir(join(root, relative), { withFileTypes: true });
+  const result = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const path = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) result.push(...await files(root, path));
+    else if (entry.isFile()) result.push(path);
+  }
+  return result;
+}
+
+export async function packedTree(root) {
+  const paths = await files(root);
+  const values = [];
+  for (const path of paths) {
+    const bytes = await readFile(join(root, path));
+    values.push([path, createHash('sha256').update(bytes).digest('hex')]);
+  }
+  return values;
+}
+
+export function comparePackedTrees(local, published) {
+  const left = JSON.stringify(local); const right = JSON.stringify(published);
+  if (left === right) return Object.freeze({ equal: true, differences: [] });
+  const localMap = new Map(local); const publishedMap = new Map(published);
+  const differences = [...new Set([...localMap.keys(), ...publishedMap.keys()])]
+    .sort()
+    .filter((path) => localMap.get(path) !== publishedMap.get(path));
+  return Object.freeze({ equal: false, differences: Object.freeze(differences) });
+}
+
+async function extract(archive, destination) {
+  await mkdir(destination, { recursive: true });
+  execFileSync('tar', ['-xzf', archive, '-C', destination], { stdio: 'pipe' });
+  return join(destination, 'package');
+}
+
+export async function verifyRegistryParity({ allowUnpublished = false, fetchImpl = fetch } = {}) {
+  const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+  const encodedName = encodeURIComponent(manifest.name);
+  const metadata = await fetchImpl(`https://registry.npmjs.org/${encodedName}/${manifest.version}`);
+  if (metadata.status === 404 && allowUnpublished) return Object.freeze({ status: 'UNPUBLISHED', name: manifest.name, version: manifest.version });
+  if (!metadata.ok) throw new Error(`registry metadata failed: HTTP ${metadata.status}`);
+  const record = await metadata.json();
+  if (typeof record?.dist?.tarball !== 'string') throw new Error('registry metadata omitted dist.tarball');
+  const root = await mkdtemp(join(tmpdir(), 'rightkit-release-parity-'));
+  try {
+    const localDir = join(root, 'local'); const publishedArchive = join(root, 'published.tgz');
+    await mkdir(localDir, { recursive: true });
+    const packed = JSON.parse(execFileSync('pnpm', ['pack', '--pack-destination', localDir, '--json'], { cwd: packageRoot, encoding: 'utf8' }));
+    const localArchive = join(localDir, basename(packed[0]?.filename ?? ''));
+    const response = await fetchImpl(record.dist.tarball);
+    if (!response.ok) throw new Error(`registry tarball failed: HTTP ${response.status}`);
+    await writeFile(publishedArchive, Buffer.from(await response.arrayBuffer()));
+    const localTree = await packedTree(await extract(localArchive, join(root, 'local-tree')));
+    const publishedTree = await packedTree(await extract(publishedArchive, join(root, 'published-tree')));
+    const comparison = comparePackedTrees(localTree, publishedTree);
+    if (!comparison.equal) throw new Error(`published ${manifest.name}@${manifest.version} differs from source pack: ${comparison.differences.join(', ')}`);
+    return Object.freeze({ status: 'MATCH', name: manifest.name, version: manifest.version, files: localTree.length });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  verifyRegistryParity({ allowUnpublished: process.argv.includes('--allow-unpublished') })
+    .then((result) => process.stdout.write(`${JSON.stringify(result)}\n`))
+    .catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+}

package/registry-parity.test.mjs

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { comparePackedTrees, verifyRegistryParity } from './registry-parity.mjs';
+
+test('registry parity rejects same-version packed-byte drift', () => {
+  assert.deepEqual(comparePackedTrees([['build-release.mjs', 'new']], [['build-release.mjs', 'old']]), {
+    equal: false,
+    differences: ['build-release.mjs'],
+  });
+});
+
+test('registry parity accepts identical packed trees', () => {
+  assert.deepEqual(comparePackedTrees([['a.mjs', 'one'], ['package.json', 'two']], [['a.mjs', 'one'], ['package.json', 'two']]), {
+    equal: true,
+    differences: [],
+  });
+});
+
+test('registry parity distinguishes an unpublished version from registry failure', async () => {
+  const notFound = async () => ({ status: 404, ok: false });
+  assert.deepEqual(await verifyRegistryParity({ allowUnpublished: true, fetchImpl: notFound }), {
+    status: 'UNPUBLISHED',
+    name: '@rightkit/release',
+    version: '0.2.67',
+  });
+  await assert.rejects(
+    verifyRegistryParity({ fetchImpl: notFound }),
+    /registry metadata failed: HTTP 404/,
+  );
+});

package/release-state.mjs

@@ -82,7 +82,7 @@ function watchDirectoryTree(root, onProgress, watchers, fallback, { watchFactory
 
 export function releaseEnvironment({ root, cacheRoot, platform, architecture, app, cacheKey, kind = "release", appRoot, mode = "legacy", env = process.env }) {
   if (kind !== "release" && kind !== "test") throw new Error(`invalid target kind: ${kind}`);
-  if (mode !== "legacy" && mode !== "shared") throw new Error(`invalid cache mode: ${mode}`);
+  if (mode !== "legacy" && mode !== "shared" && mode !== "broker") throw new Error(`invalid cache mode: ${mode}`);
   if (mode === "shared") {
     if (!cacheRoot || !platform || !architecture || !app || !cacheKey || !appRoot) throw new Error("shared release environment requires cacheRoot, platform, architecture, app, cacheKey, and appRoot");
     const layout = resolveCacheLayout({ cacheRoot, platform, architecture, app, fingerprint: cacheKey, kind });

package/release.test.mjs

@@ -134,21 +134,39 @@ function lockFixture() {
   return { dir, config };
 }
 
+// This suite must exercise the non-broker path deterministically regardless of
+// whether the machine running the tests is itself broker-managed (this
+// workspace's own agent shells are: the managed cargo shim sits on PATH).
+// Strip both broker signals from the inherited environment before spawning.
+function unmanagedEnv() {
+  const sanitized = { ...process.env };
+  delete sanitized.RIGHTKIT_BUILD_BROKER_SOCKET;
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  sanitized.PATH = String(process.env.PATH ?? "")
+    .split(delimiter)
+    .filter((entry) => !/(?:^|[/\\])(?:\.rightkit-managed|rightkitmanagedagent)[/\\]agent-bin$/i.test(entry))
+    .join(delimiter);
+  return sanitized;
+}
+
 function run(config, ...args) {
   return spawnSync(process.execPath, [release, "--config", config, "--platform", "win", "--dry-run", ...args], {
     encoding: "utf8",
+    env: unmanagedEnv(),
   });
 }
 
 function runRaw(config, ...args) {
   return spawnSync(process.execPath, [release, "--config", config, ...args], {
     encoding: "utf8",
+    env: unmanagedEnv(),
   });
 }
 
 function runDoctor(config, ...args) {
   return spawnSync(process.execPath, [cli, "doctor", "--config", config, "--platform", hostPlatform, ...args], {
     encoding: "utf8",
+    env: unmanagedEnv(),
   });
 }
 
@@ -284,6 +302,18 @@ test("doctor rejects a real src-tauri target before release work", () => {
   assert.match(`${result.stdout}\n${result.stderr}`, /target-bridge[\s\S]*real directory[\s\S]*cache migrate/i);
 });
 
+test("doctor accepts a real src-tauri target on a broker-managed host instead of proposing cache migrate", () => {
+  const config = fixture({ platform: hostPlatform });
+  mkdirSync(path.join(path.dirname(config), "src-tauri", "target"));
+  const result = spawnSync(process.execPath, [cli, "doctor", "--config", config, "--platform", hostPlatform], {
+    encoding: "utf8",
+    env: { ...unmanagedEnv(), RIGHTKIT_BUILD_BROKER_SOCKET: "/managed/broker.sock" },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(`${result.stdout}\n${result.stderr}`, /cache migrate/i);
+  assert.match(result.stdout, /target-bridge[\s\S]*broker-managed host, left untouched/i);
+});
+
 test("doctor permits unrelated dirt", () => {
   const config = fixture({ platform: hostPlatform });
   const root = path.dirname(config);

package/right-suite-contract.test.mjs

@@ -47,6 +47,24 @@ const macOnlyApps = [
   { key: "screenright", root: "tools/screenright", releaseFiles: ["scripts/release-package.mjs"] },
 ];
 
+// Consuming suite apps whose packaging/build scripts must resolve Cargo build
+// output from `cargo metadata`'s `target_directory`, never by reading
+// CARGO_TARGET_DIR (or a shell/PowerShell equivalent) directly to locate it.
+// This defect recurred three times across the suite (broker-managed hosts own
+// CARGO_TARGET_DIR, so a stale/wrong value silently reads the wrong tree).
+// rightsites and tools/screenright are intentionally out of scope here.
+const cargoTargetDirGuardApps = [
+  "coderight/apps/coderight-tauri",
+  "cutright/apps/studio",
+  "genright",
+  "heardright/tauri-app-next",
+  "mailright",
+  "membrane/apps/membrane-hub",
+  "orthic",
+  "scraperight",
+  "viewright",
+];
+
 function assertReleasePackageScripts(scripts, label) {
   for (const platform of ["mac", "win"]) {
     assert.equal(scripts[`release:build:${platform}`], `right-release build --platform ${platform}`, `${label} must use the tier-neutral ${platform} build entry point`);
@@ -468,12 +486,12 @@ test("RightKit exposes one current version manifest", () => {
     "@rightkit/legal": "0.3.0",
     "@rightkit/legal-ui": "0.1.1",
     "@rightkit/license": "0.1.6",
-    "@rightkit/release": "0.2.65",
+    "@rightkit/release": "0.2.67",
     "@rightkit/qa": "0.2.0",
   });
   assert.deepEqual(versions.legacyNpm, {
     "@rightkit/legal-ui": ["0.1.0"],
-    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46", "0.2.49", "0.2.50", "0.2.51", "0.2.53", "0.2.54", "0.2.55", "0.2.56", "0.2.61", "0.2.62", "0.2.63", "0.2.64"],
+    "@rightkit/release": ["0.2.22", "0.2.29", "0.2.30", "0.2.31", "0.2.41", "0.2.42", "0.2.43", "0.2.44", "0.2.45", "0.2.46", "0.2.49", "0.2.50", "0.2.51", "0.2.53", "0.2.54", "0.2.55", "0.2.56", "0.2.61", "0.2.62", "0.2.63", "0.2.64", "0.2.65", "0.2.66"],
     "@rightkit/qa": ["0.1.0"],
   });
   assert.ok(
@@ -769,6 +787,113 @@ function readCanonicalCrateVersions() {
   );
 }
 
+const CARGO_TARGET_DIR_GUARD_EXTENSIONS = new Set([".mjs", ".js", ".ts", ".sh", ".ps1"]);
+const CARGO_TARGET_DIR_GUARD_ALLOW_MARKER = /rightkit-allow-cargo-target-dir:\s*\S/;
+// Test/contract files assert *about* the CARGO_TARGET_DIR pattern (e.g. inside
+// a regex literal passed to assert.match/assert.doesNotMatch) rather than
+// locating build output with it; they are not packaging/build scripts.
+const CARGO_TARGET_DIR_GUARD_SKIP_BASENAME = /(?:^test-.*|\.test)\.(?:mjs|js|ts)$/;
+
+function cargoTargetDirGuardPatternFor(extension) {
+  if (extension === ".ps1") return /\$env:CARGO_TARGET_DIR\b/;
+  if (extension === ".sh") return /\$\{?CARGO_TARGET_DIR\b/;
+  return /process\.env(?:\.CARGO_TARGET_DIR\b|\[["']CARGO_TARGET_DIR["']\])/;
+}
+
+function findCargoTargetDirGuardFiles(root) {
+  const found = [];
+  const visit = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory() && ["node_modules", "target", "vendor", ".git", ".cache", ".right-release"].includes(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (entry.isFile() && CARGO_TARGET_DIR_GUARD_EXTENSIONS.has(path.extname(entry.name))) found.push(full);
+    }
+  };
+  const scriptsDir = path.join(root, "scripts");
+  if (existsSync(scriptsDir)) visit(scriptsDir);
+  for (const topLevel of ["package.sh", "package.ps1"]) {
+    const candidate = path.join(root, topLevel);
+    if (existsSync(candidate)) found.push(candidate);
+  }
+  return found;
+}
+
+test("consuming suite apps resolve Cargo build output from cargo metadata, never CARGO_TARGET_DIR directly", () => {
+  for (const appRoot of cargoTargetDirGuardApps) {
+    const root = path.join(workspace, appRoot);
+    if (!existsSync(root)) continue;
+    for (const filePath of findCargoTargetDirGuardFiles(root)) {
+      const basename = path.basename(filePath);
+      if (CARGO_TARGET_DIR_GUARD_SKIP_BASENAME.test(basename)) continue;
+      const extension = path.extname(filePath);
+      const pattern = cargoTargetDirGuardPatternFor(extension);
+      const lines = readFileSync(filePath, "utf8").split("\n");
+      const relativePath = path.relative(workspace, filePath);
+      lines.forEach((line, index) => {
+        if (!pattern.test(line)) return;
+        if (/^\s*(?:\/\/|#)/.test(line)) return; // prose describing the pattern, not code reading it
+        const previousLine = index > 0 ? lines[index - 1] : "";
+        const allowed = CARGO_TARGET_DIR_GUARD_ALLOW_MARKER.test(line) || CARGO_TARGET_DIR_GUARD_ALLOW_MARKER.test(previousLine);
+        assert.ok(
+          allowed,
+          `${relativePath}:${index + 1} reads CARGO_TARGET_DIR directly to locate Cargo build output: \`${line.trim()}\`\n`
+          + "resolve build output from `cargo metadata`'s `target_directory`; the environment is never authoritative for locating output.\n"
+          + "add a `rightkit-allow-cargo-target-dir: <reason>` marker on this line (or the line above) only if this use is not locating output.",
+        );
+      });
+    }
+  }
+});
+
+// The shared resolver helpers themselves must keep asking cargo metadata for
+// target_directory. Guarding only the wrong pattern's reintroduction is not
+// enough — gutting/deleting the correct implementation must also fail here.
+const cargoTargetRootHelpers = [
+  "coderight/apps/coderight-tauri/scripts/lib/target-root.mjs",
+  "heardright/tauri-app-next/scripts/lib/target-root.mjs",
+  "mailright/scripts/lib/target-root.mjs",
+  "orthic/scripts/lib/target-root.mjs",
+  "viewright/scripts/lib/target-root.mjs",
+  "membrane/apps/membrane-hub/scripts/lib/target-root.mjs",
+];
+
+test("shared target-root helpers still resolve build output via cargo metadata's target_directory", () => {
+  for (const helperPath of cargoTargetRootHelpers) {
+    const appRoot = path.join(workspace, helperPath.split("/scripts/lib/target-root.mjs")[0]);
+    if (!existsSync(path.join(appRoot, "package.json"))) continue;
+    const fullPath = path.join(workspace, helperPath);
+    assert.ok(existsSync(fullPath), `${helperPath} is missing; the app must keep its shared cargo-metadata target resolver`);
+    const source = readFileSync(fullPath, "utf8");
+    assert.match(source, /cargo/, `${helperPath} must invoke cargo`);
+    assert.match(source, /metadata/, `${helperPath} must call cargo metadata`);
+    assert.match(source, /target_directory/, `${helperPath} must read target_directory from cargo metadata's output`);
+  }
+});
+
+// After the app migration lands, every consuming app's target-root helper must
+// become a thin re-export of the shared tools/rightkit resolveTargetRoot
+// (cargo-target.mjs) rather than its own copy of the cargo-metadata call. Until
+// that migration lands, cargoTargetRootHelpers above still point at full local
+// implementations, so this stays skipped to avoid failing the still-unmigrated
+// app repos. Enable it once every app's target-root.mjs is a re-export shim.
+test("consuming app target-root helpers are thin re-export shims, not local resolver re-implementations", { skip: true }, () => {
+  const LOCAL_RESOLVER_PATTERN = /function\s+(?:cargoTargetRoot|resolveManagedCargoTarget)\s*\([^)]*\)\s*\{[^}]*cargo[^}]*metadata/s;
+  for (const helperPath of cargoTargetRootHelpers) {
+    const appRoot = path.join(workspace, helperPath.split("/scripts/lib/target-root.mjs")[0]);
+    if (!existsSync(appRoot)) continue;
+    const fullPath = path.join(workspace, helperPath);
+    if (!existsSync(fullPath)) continue;
+    const source = readFileSync(fullPath, "utf8");
+    assert.doesNotMatch(
+      source,
+      LOCAL_RESOLVER_PATTERN,
+      `${helperPath} must re-export @rightkit/release's resolveTargetRoot instead of reimplementing the cargo metadata call locally`,
+    );
+  }
+});
+
 test("Right Suite has no hosted workflow files", () => {
   for (const root of ["viewright", "scraperight", "heardright", "mailright", "coderight", "genright", "voiceright", "tools/rightkit"]) {
     const workflowDir = path.join(workspace, root, ".github", "workflows");

package/rightkit-versions.json

@@ -19,7 +19,7 @@
     "@rightkit/legal": "0.3.0",
     "@rightkit/legal-ui": "0.1.1",
     "@rightkit/license": "0.1.6",
-    "@rightkit/release": "0.2.65",
+    "@rightkit/release": "0.2.67",
     "@rightkit/qa": "0.2.0"
   },
   "legacyNpm": {
@@ -47,7 +47,9 @@
       "0.2.61",
       "0.2.62",
       "0.2.63",
-      "0.2.64"
+      "0.2.64",
+      "0.2.65",
+      "0.2.66"
     ],
     "@rightkit/qa": [
       "0.1.0"

package/standalone-clone-verify.test.mjs

@@ -22,7 +22,7 @@ test("standalone verifier clones, installs, doctors from a nested app root, and
   writeFileSync(path.join(source, "apps", "desktop", "package.json"), JSON.stringify({
     name: "standalone-fixture",
     private: true,
-    packageManager: "pnpm@11.17.0",
+    packageManager: "pnpm@11.18.0",
     scripts: { "release:doctor": "node doctor.mjs" },
   }), "utf8");
   writeFileSync(path.join(source, "apps", "desktop", "pnpm-lock.yaml"), "lockfileVersion: '9.0'\nsettings:\n  autoInstallPeers: true\n  excludeLinksFromLockfile: false\nimporters:\n  .: {}\n", "utf8");

package/target-bridge.mjs

@@ -9,12 +9,21 @@ import path from "node:path";
  *   fingerprint change — i.e. every Cargo.lock or version bump — left a stale
  *   link that hard-stopped the next build until someone deleted it by hand.
  *   Omit it to keep the strict refuse-everything behavior.
+ * @param brokerManaged True when a build broker owns CARGO_TARGET_DIR on this
+ *   host. A real (non-symlink) directory at `link` is then not corruption to
+ *   repair — it is the broker's own build output, or a leftover from before the
+ *   broker took ownership, and either way is not this bridge's to touch. The
+ *   non-broker path used to name that same directory "corrupt" and point at
+ *   `cache migrate`, which renames it away; on a broker host that came within
+ *   one step of moving ~5.9 GB of warm intermediates the broker still expects
+ *   to find in place. Leave it untouched instead.
  */
 export function createTargetBridge({
   link,
   target,
   ownedRoot,
   platform = process.platform,
+  brokerManaged = false,
   lstat = lstatSync,
   mkdir = mkdirSync,
   realpath = realpathSync,
@@ -29,6 +38,7 @@ export function createTargetBridge({
     ensure() {
       let entry = readEntry(link, lstat);
       if (entry && !entry.isSymbolicLink()) {
+        if (brokerManaged) return { created: false, link, target, brokerManaged: true };
         throw new Error(
           `primary checkout target is not a symbolic link; refusing to replace it: ${link}\n` +
             `  It is a real directory holding build output. Run right-release cache migrate before building.`,

package/target-bridge.test.mjs

@@ -160,6 +160,41 @@ test("rejecting a real target does not create the shared cache destination", ()
   assert.equal(existsSync(target), false);
 });
 
+test("broker-managed: a real target directory is left untouched instead of treated as corruption", async () => {
+  const fx = fixture();
+  mkdirSync(fx.link);
+  writeFileSync(path.join(fx.link, "user.txt"), "keep\n");
+  const result = await createTargetBridge({ ...fx, brokerManaged: true }).run(async (bridge) => bridge.ensure());
+  assert.equal(result.brokerManaged, true);
+  assert.equal(result.created, false);
+  // Nothing was removed, replaced, or relinked: the real directory and its
+  // content are exactly as they were, and no shared-cache destination was
+  // fabricated in its place.
+  assert.equal(readFileSync(path.join(fx.link, "user.txt"), "utf8"), "keep\n");
+  assert.equal(lstatSync(fx.link).isSymbolicLink(), false);
+});
+
+test("broker-managed: release() is a safe no-op after leaving a real target untouched", () => {
+  const fx = fixture();
+  mkdirSync(fx.link);
+  writeFileSync(path.join(fx.link, "user.txt"), "keep\n");
+  const bridge = createTargetBridge({ ...fx, brokerManaged: true });
+  bridge.ensure();
+  assert.equal(bridge.release(), false);
+  assert.equal(readFileSync(path.join(fx.link, "user.txt"), "utf8"), "keep\n");
+});
+
+test("broker-managed has no effect on the non-broker path: a symlink bridge still behaves exactly as before", async () => {
+  const fx = fixture();
+  const result = await createTargetBridge({ ...fx, brokerManaged: true }).run(async (bridge) => {
+    const ensured = bridge.ensure();
+    assert.equal(lstatSync(fx.link).isSymbolicLink(), true);
+    return ensured;
+  });
+  assert.equal(result.created, true);
+  assert.equal(result.brokerManaged, undefined);
+});
+
 test("cleanup is idempotent and reports process errors without masking a build failure", async () => {
   const fx = fixture();
   const bridge = createTargetBridge(fx);