deepdebug-local-agent 1.0.23 → 1.2.0

package/test/observability-detect.test.js

@@ -0,0 +1,199 @@
+// test/observability-detect.test.js
+// The zero-observability decision must be conservative: recommend 'provision'
+// ONLY when nothing already ships logs/metrics, and never count OUR own stack
+// as the client's pre-existing observability.
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  classifyObservability,
+  ownStackRunning,
+  OBSERVABILITY_SIGNALS,
+} from '../src/observability/detect.js';
+import { validateProvisionInput } from '../src/observability/provision.js';
+import { renderBundle, COMPOSE_PROJECT } from '../src/observability/bundle-files.js';
+
+describe('classifyObservability', () => {
+  test('empty host => provision', () => {
+    const r = classifyObservability({ containers: [], processes: [] });
+    assert.equal(r.hasObservability, false);
+    assert.equal(r.recommendation, 'provision');
+    assert.deepEqual(r.found, []);
+  });
+
+  test('a running Grafana/Loki (client-owned) => skip, not provision', () => {
+    const r = classifyObservability({
+      containers: [
+        { name: 'grafana', image: 'grafana/grafana:10.0.0', project: 'monitoring' },
+        { name: 'loki', image: 'grafana/loki:2.9.0', project: 'monitoring' },
+      ],
+    });
+    assert.equal(r.hasObservability, true);
+    assert.equal(r.recommendation, 'skip');
+    assert.ok(r.found.includes('grafana'));
+    assert.ok(r.found.includes('loki'));
+  });
+
+  test('a Datadog agent process (no docker) => skip', () => {
+    const r = classifyObservability({
+      containers: [],
+      processes: ['/opt/datadog-agent/bin/agent/agent run'],
+    });
+    assert.equal(r.hasObservability, true);
+    assert.equal(r.recommendation, 'skip');
+    assert.ok(r.found.includes('datadog'));
+  });
+
+  test('OUR OWN stack does not count as the client already having observability', () => {
+    const r = classifyObservability({
+      containers: [
+        { name: 'deepdebug-observability-grafana-1', image: 'grafana/grafana:11.1.0', project: COMPOSE_PROJECT },
+        { name: 'deepdebug-observability-loki-1', image: 'grafana/loki:3.1.1', project: COMPOSE_PROJECT },
+        { name: 'app', image: 'mycompany/app:latest', project: 'app' },
+      ],
+    });
+    assert.equal(r.hasObservability, false, 'only our stack is present => client has none');
+    assert.equal(r.recommendation, 'provision');
+    assert.equal(r.ours.length, 2);
+  });
+
+  test('client app containers alone => provision', () => {
+    const r = classifyObservability({
+      containers: [
+        { name: 'nginx', image: 'nginx:1.25', project: 'web' },
+        { name: 'api', image: 'mycompany/api:2.0', project: 'web' },
+        { name: 'postgres', image: 'postgres:16', project: 'web' },
+      ],
+    });
+    assert.equal(r.hasObservability, false);
+    assert.equal(r.recommendation, 'provision');
+  });
+
+  test('ownStackRunning reflects the compose project label', () => {
+    assert.equal(ownStackRunning([{ name: 'x', project: COMPOSE_PROJECT }]), true);
+    assert.equal(ownStackRunning([{ name: 'x', project: 'other' }]), false);
+    assert.equal(ownStackRunning([]), false);
+  });
+
+  test('signal list is non-trivial and lowercase', () => {
+    assert.ok(OBSERVABILITY_SIGNALS.length >= 10);
+    for (const s of OBSERVABILITY_SIGNALS) assert.equal(s, s.toLowerCase());
+  });
+});
+
+describe('renderBundle', () => {
+  const rendered = renderBundle({
+    gatewayUrl: 'https://api.visionhammer.io/',
+    triggerSecret: 'vht_deadbeef.secretpart',
+    environment: 'production',
+  });
+
+  test('produces the full file set', () => {
+    for (const p of [
+      'docker-compose.yml',
+      'loki/loki-config.yaml',
+      'loki/rules/fake/client.yaml',
+      'alloy/config.alloy',
+      'alertmanager/alertmanager.yml',
+      'grafana/provisioning/datasources/loki.yaml',
+      'grafana/dashboards/ddo-logs.json',
+      'caddy/Caddyfile',
+      'docker-compose.tunnel.yml',
+    ]) {
+      assert.ok(rendered[p] && rendered[p].length > 0, `missing ${p}`);
+    }
+  });
+
+  test('tunnel overlay bakes the bearer token into the caddy gate', () => {
+    const withToken = renderBundle({
+      gatewayUrl: 'https://api.visionhammer.io',
+      triggerSecret: 'vht_deadbeef.secretpart',
+      lokiTunnelToken: 'tok_123abc',
+    });
+    const caddy = withToken['caddy/Caddyfile'];
+    assert.ok(caddy.includes('Bearer tok_123abc'), 'caddy must require the exact bearer token');
+    assert.ok(!caddy.includes('__LOKI_TUNNEL_TOKEN__'), 'token placeholder must be resolved');
+    // The overlay exposes the auth gate, never Loki directly.
+    assert.ok(withToken['docker-compose.tunnel.yml'].includes('http://loki-auth:8080'));
+  });
+
+  test('trailing slash on gatewayUrl is stripped in the webhook URL', () => {
+    const am = rendered['alertmanager/alertmanager.yml'];
+    assert.ok(am.includes("url: 'https://api.visionhammer.io/api/v1/webhooks/alertmanager'"));
+    assert.ok(!am.includes('.io//api'), 'double slash must not appear');
+  });
+
+  test('alertmanager sends the secret as a bearer header, never in the URL', () => {
+    const am = rendered['alertmanager/alertmanager.yml'];
+    assert.ok(!am.includes('?s='), 'secret must not be in the webhook URL (Cloud Run logs URLs)');
+    assert.ok(am.includes("credentials: 'vht_deadbeef.secretpart'"));
+    assert.ok(am.includes('type: Bearer'));
+  });
+
+  test('the error rule never alerts on our own containers on the host', () => {
+    const rule = rendered['loki/rules/fake/client.yaml'];
+    assert.ok(rule.includes('service!~"deepdebug-observability-.*|vh-obs-.*|visionhammer-agent"'));
+  });
+
+  test('alloy pushes the docker stream to the gateway as OTLP JSON with the tenant secret', () => {
+    const alloy = rendered['alloy/config.alloy'];
+    assert.ok(alloy.includes('otelcol.receiver.loki.visionhammer.receiver'), 'loki stream must fan out to the push');
+    assert.ok(alloy.includes('logs_endpoint = "https://api.visionhammer.io/api/v1/webhooks/logs/otlp"'));
+    assert.ok(alloy.includes('encoding      = "json"'), 'gateway accepts JSON only');
+    assert.ok(alloy.includes('"Authorization" = "Bearer vht_deadbeef.secretpart"'));
+  });
+
+  test('no placeholders survive rendering', () => {
+    for (const [p, content] of Object.entries(rendered)) {
+      assert.ok(!content.includes('__GATEWAY_URL__'), `__GATEWAY_URL__ left in ${p}`);
+      assert.ok(!content.includes('__TRIGGER_SECRET__'), `__TRIGGER_SECRET__ left in ${p}`);
+      assert.ok(!content.includes('__ENVIRONMENT__'), `__ENVIRONMENT__ left in ${p}`);
+    }
+  });
+
+  test('the dashboard data link and static env label carry the tenant secret + env', () => {
+    const dash = rendered['grafana/dashboards/ddo-logs.json'];
+    assert.ok(dash.includes('/api/v1/webhooks/from-log?s=vht_deadbeef.secretpart'));
+    const alloy = rendered['alloy/config.alloy'];
+    assert.ok(alloy.includes('environment = "production"'));
+  });
+
+  test('loki ruler is wired for delivery (v2 API) and accepts the docker backlog', () => {
+    const loki = rendered['loki/loki-config.yaml'];
+    // Alertmanager v0.27 removed the v1 push API the ruler defaults to.
+    assert.ok(loki.includes('enable_alertmanager_v2: true'),
+      'ruler must POST alerts on the v2 endpoint or they never arrive');
+    // The rule lives under the "fake" tenant dir (auth_enabled=false) or it is
+    // never loaded.
+    assert.ok(rendered['loki/rules/fake/client.yaml'],
+      'rule must be under rules/<tenant>/ to be loaded by the local ruler');
+    // A tight reject window drops the on-boot docker log backlog.
+    assert.ok(loki.includes('reject_old_samples_max_age: 720h'),
+      'reject window must clear the existing docker log backlog on first start');
+  });
+
+  test('missing inputs throw', () => {
+    assert.throws(() => renderBundle({ gatewayUrl: 'x' }));
+    assert.throws(() => renderBundle({ triggerSecret: 'y' }));
+  });
+});
+
+describe('validateProvisionInput', () => {
+  const ok = { gatewayUrl: 'https://api.visionhammer.io', triggerSecret: 'vht_deadbeef.secretpart', environment: 'production' };
+
+  test('accepts a plain https origin, a vht_ secret and a simple environment', () => {
+    assert.equal(validateProvisionInput(ok), null);
+  });
+
+  test('rejects values that would break out of the rendered YAML/Alloy/.env', () => {
+    assert.ok(validateProvisionInput({ ...ok, triggerSecret: "vht_a'\n  url: http://evil" }));
+    assert.ok(validateProvisionInput({ ...ok, environment: 'prod"}' }));
+    assert.ok(validateProvisionInput({ ...ok, gatewayUrl: 'https://api.visionhammer.io/?x=1' }));
+    assert.ok(validateProvisionInput({ ...ok, grafanaPassword: 'a\nGF_X=1' }));
+  });
+
+  test('requires https except for local gateways', () => {
+    assert.ok(validateProvisionInput({ ...ok, gatewayUrl: 'http://api.visionhammer.io' }));
+    assert.equal(validateProvisionInput({ ...ok, gatewayUrl: 'http://localhost:8080' }), null);
+  });
+});

package/test/open-gate.test.js

@@ -0,0 +1,341 @@
+// test/open-gate.test.js
+// OPEN GATE: /workspace/open with repoUrl is a HYDRATION request and must
+// never 500 on a stale clone dir left by a previous revision (in-memory
+// registry lost on restart => the dir is an ORPHAN with possibly broken git
+// state - QA 2026-07-20 00:17Z, "git reset --hard origin/main: ambiguous
+// argument"). Orphans are cleaned and re-cloned fresh; a dir REGISTERED for
+// another tenant is NEVER touched (clear 409, not a generic 500); a dir
+// registered for the same (or unknown) tenant keeps the byte-identical
+// reuse/refresh path.
+
+import { test, describe, before, after } 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 {
+  WORKSPACE_SIDECAR,
+  classifyOpenDestination,
+  extractOpenTenantId,
+  findRegistrationForDir,
+  isSafeToRemove,
+  readWorkspaceSidecar,
+} from '../src/utils/open-gate.js';
+import { WorkspaceManager } from '../src/workspace-manager.js';
+import { countFilesExcludingGit } from '../src/utils/file-count.js';
+
+let cache, orphanDir, registeredDir, multiParent, multiRepoDir;
+
+before(() => {
+  cache = fs.mkdtempSync(path.join(os.tmpdir(), 'open-gate-'));
+  // single-repo cloud-clone layout: <owner>_<repo>
+  orphanDir = path.join(cache, 'VISIONHAMMER_vh-e2e-sap-abap');
+  registeredDir = path.join(cache, 'VISIONHAMMER_vh-e2e-legacy-java8');
+  // multi-repo layout: <wsId>/<owner>_<repo>
+  multiParent = path.join(cache, 'ws-multi-1');
+  multiRepoDir = path.join(multiParent, 'ACME_catalog-api');
+  for (const d of [orphanDir, registeredDir, multiRepoDir]) {
+    fs.mkdirSync(d, { recursive: true });
+  }
+});
+
+after(() => {
+  try { fs.rmSync(cache, { recursive: true, force: true }); } catch (_) {}
+});
+
+describe('classifyOpenDestination', () => {
+  test('missing destination -> fresh clone (unchanged behavior)', () => {
+    const gate = classifyOpenDestination(path.join(cache, 'not-there-yet'), {
+      registry: [],
+      requestTenantId: 'tenant-a',
+    });
+    assert.equal(gate.action, 'fresh');
+  });
+
+  test('QA failure mode: orphan dir on disk (registry lost) -> clean_and_fresh, never reuse', () => {
+    // The exact scenario behind the /workspace/open 500: the dir exists
+    // from an older revision, no registry entry survives the restart.
+    const gate = classifyOpenDestination(orphanDir, {
+      registry: [],
+      requestTenantId: '0d0de93f-5537-423c-b5a2-c01789723ce6',
+    });
+    assert.equal(gate.action, 'clean_and_fresh');
+    assert.equal(gate.reason, 'orphan_dir_no_registration');
+  });
+
+  test('orphan classification holds even when the request tenant is unknown', () => {
+    // Today the gateway sends no tenantId on /workspace/open - the orphan
+    // cleanup must still engage (a null tenant registers as unknown, which
+    // is exactly the pre-restart state being replaced).
+    const gate = classifyOpenDestination(orphanDir, {
+      registry: [],
+      requestTenantId: null,
+    });
+    assert.equal(gate.action, 'clean_and_fresh');
+  });
+
+  test('destination registered for ANOTHER tenant (both known) -> deny, dir untouched', () => {
+    const gate = classifyOpenDestination(registeredDir, {
+      registry: [{ id: 'ws-1', root: registeredDir, tenantId: 'tenant-b' }],
+      requestTenantId: 'tenant-a',
+    });
+    assert.equal(gate.action, 'deny');
+    assert.equal(gate.reason, 'owned_by_another_tenant');
+    assert.equal(gate.ownerWorkspaceId, 'ws-1');
+    assert.equal(gate.ownerTenantId, 'tenant-b');
+  });
+
+  test('destination registered for the SAME tenant -> reuse (current refresh path)', () => {
+    const gate = classifyOpenDestination(registeredDir, {
+      registry: [{ id: 'ws-1', root: registeredDir, tenantId: 'tenant-a' }],
+      requestTenantId: 'tenant-a',
+    });
+    assert.equal(gate.action, 'reuse');
+  });
+
+  test('registered dir with UNKNOWN tenant on either side -> reuse (never destructive without proof)', () => {
+    // Registered tenant unknown (pre-gate registration):
+    assert.equal(classifyOpenDestination(registeredDir, {
+      registry: [{ id: 'ws-1', root: registeredDir }],
+      requestTenantId: 'tenant-a',
+    }).action, 'reuse');
+    // Request tenant unknown (today's gateway payload):
+    assert.equal(classifyOpenDestination(registeredDir, {
+      registry: [{ id: 'ws-1', root: registeredDir, tenantId: 'tenant-b' }],
+      requestTenantId: null,
+    }).action, 'reuse');
+  });
+
+  test('multi-repo: a per-repo sub-dir belongs to its registered PARENT workspace dir', () => {
+    const gateSame = classifyOpenDestination(multiRepoDir, {
+      registry: [{ id: 'ws-multi-1', root: multiParent, tenantId: 'tenant-a' }],
+      requestTenantId: 'tenant-a',
+    });
+    assert.equal(gateSame.action, 'reuse');
+    const gateOther = classifyOpenDestination(multiRepoDir, {
+      registry: [{ id: 'ws-multi-1', root: multiParent, tenantId: 'tenant-b' }],
+      requestTenantId: 'tenant-a',
+    });
+    assert.equal(gateOther.action, 'deny');
+  });
+
+  test('never throws on broken injections (fail-safe to fresh)', () => {
+    const gate = classifyOpenDestination(orphanDir, {
+      registry: [{ id: 'x', root: 42 }],
+      requestTenantId: 'tenant-a',
+      existsSync: () => { throw new Error('boom'); },
+    });
+    assert.equal(gate.action, 'fresh');
+  });
+});
+
+describe('findRegistrationForDir', () => {
+  test('exact root match wins', () => {
+    const reg = [{ id: 'ws-1', root: registeredDir, tenantId: 't' }];
+    assert.equal(findRegistrationForDir(registeredDir, reg), reg[0]);
+  });
+
+  test('ancestor root owns nested dirs, siblings stay orphan', () => {
+    const reg = [{ id: 'ws-multi-1', root: multiParent, tenantId: 't' }];
+    assert.equal(findRegistrationForDir(multiRepoDir, reg), reg[0]);
+    assert.equal(findRegistrationForDir(orphanDir, reg), null);
+    // prefix that is NOT a path boundary must not match ("/a/bc" vs "/a/b")
+    assert.equal(findRegistrationForDir(multiParent + '-other', reg), null);
+  });
+
+  test('degenerate inputs -> null (orphan handling stays conservative upstream)', () => {
+    assert.equal(findRegistrationForDir('', []), null);
+    assert.equal(findRegistrationForDir(null, null), null);
+    assert.equal(findRegistrationForDir(registeredDir, [null, {}, { root: '' }]), null);
+  });
+});
+
+describe('isSafeToRemove', () => {
+  test('only dirs STRICTLY inside the cache base are removable', () => {
+    assert.equal(isSafeToRemove(cache, orphanDir), true);
+    assert.equal(isSafeToRemove(cache, multiRepoDir), true);
+  });
+
+  test('the base itself, "/", traversal escapes and junk are never removable', () => {
+    assert.equal(isSafeToRemove(cache, cache), false);
+    assert.equal(isSafeToRemove(cache, '/'), false);
+    assert.equal(isSafeToRemove('/', '/etc'), false);
+    assert.equal(isSafeToRemove(cache, path.join(cache, '..', 'escape')), false);
+    assert.equal(isSafeToRemove(cache, ''), false);
+    assert.equal(isSafeToRemove('', orphanDir), false);
+    assert.equal(isSafeToRemove(cache, null), false);
+  });
+});
+
+describe('extractOpenTenantId', () => {
+  test('body.tenantId wins over the X-Tenant-ID header', () => {
+    assert.equal(extractOpenTenantId({ tenantId: 't-body' }, { 'x-tenant-id': 't-header' }), 't-body');
+  });
+
+  test('X-Tenant-ID header is the fallback', () => {
+    assert.equal(extractOpenTenantId({}, { 'x-tenant-id': 't-header' }), 't-header');
+    assert.equal(extractOpenTenantId(null, { 'x-tenant-id': ' t-header ' }), 't-header');
+  });
+
+  test('absent/blank everywhere -> null (unknown, gate stays non-destructive on registered dirs)', () => {
+    assert.equal(extractOpenTenantId({}, {}), null);
+    assert.equal(extractOpenTenantId({ tenantId: '   ' }, {}), null);
+    assert.equal(extractOpenTenantId(null, null), null);
+    assert.equal(extractOpenTenantId({ tenantId: 42 }, {}), null);
+  });
+});
+
+describe('WorkspaceManager tenant registration (open path)', () => {
+  test('open() registers the tenant and a later open without meta KEEPS it', async () => {
+    const mgr = new WorkspaceManager();
+    await mgr.open('ws-t', registeredDir, { tenantId: 'tenant-a' });
+    assert.equal(mgr.list().find((w) => w.id === 'ws-t').tenantId, 'tenant-a');
+    // Re-open (refresh) without tenant meta must not erase the registration.
+    await mgr.open('ws-t', registeredDir, {});
+    assert.equal(mgr.list().find((w) => w.id === 'ws-t').tenantId, 'tenant-a');
+  });
+
+  test('fresh-clone-over-orphan flow: cleanup + re-open registers the request tenant', async () => {
+    // Simulates the fixed /workspace/open path end-to-end at the module
+    // level: orphan classified -> removed -> "cloned" fresh -> registered.
+    const flowDir = path.join(cache, 'FLOW_org_repo');
+    fs.mkdirSync(path.join(flowDir, '.git'), { recursive: true });
+    const mgr = new WorkspaceManager();
+
+    const gate = classifyOpenDestination(flowDir, {
+      registry: mgr.list(),
+      requestTenantId: 'tenant-a',
+    });
+    assert.equal(gate.action, 'clean_and_fresh');
+    assert.equal(isSafeToRemove(cache, flowDir), true);
+    fs.rmSync(flowDir, { recursive: true, force: true });
+    assert.equal(fs.existsSync(flowDir), false);
+
+    // fresh clone lands, then the open registers it WITH the tenant
+    fs.mkdirSync(flowDir, { recursive: true });
+    await mgr.open('ws-flow', flowDir, { tenantId: 'tenant-a' });
+    const w = mgr.list().find((x) => x.id === 'ws-flow');
+    assert.equal(w.tenantId, 'tenant-a');
+    assert.equal(w.root, flowDir);
+
+    // and a SECOND open of the now-registered dir reuses (no cleanup)
+    assert.equal(classifyOpenDestination(flowDir, {
+      registry: mgr.list(),
+      requestTenantId: 'tenant-a',
+    }).action, 'reuse');
+  });
+});
+
+// SIDECAR (QA 2026-09-22): the registry is an in-memory Map; every Cloud Run
+// cold start / new revision / second instance forgets it and each clone dir
+// on disk becomes an "orphan" -> rm -rf + re-clone of all N repos per scan.
+// open() now persists `<root>/.vh-workspace.json`; a valid sidecar counts as
+// the registration and the SAME tenant rules apply to it.
+describe('registration sidecar (.vh-workspace.json)', () => {
+  function writeSidecar(dir, data) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, WORKSPACE_SIDECAR), JSON.stringify(data));
+  }
+
+  test('WorkspaceManager.open() writes the sidecar {id, tenantId, root, openedAt} - never a token', async () => {
+    const dir = path.join(cache, 'SIDE_write');
+    fs.mkdirSync(dir, { recursive: true });
+    const mgr = new WorkspaceManager();
+    await mgr.open('ws-side', dir, { tenantId: 'tenant-a', token: 'ghp_NEVER' });
+    const raw = fs.readFileSync(path.join(dir, WORKSPACE_SIDECAR), 'utf8');
+    const data = JSON.parse(raw);
+    assert.deepEqual(Object.keys(data).sort(), ['id', 'openedAt', 'root', 'tenantId']);
+    assert.equal(data.id, 'ws-side');
+    assert.equal(data.tenantId, 'tenant-a');
+    assert.equal(data.root, dir);
+    assert.doesNotMatch(raw, /ghp_NEVER|token/i);
+  });
+
+  test('QA loop breaker: registry LOST (new Map) + sidecar for the SAME tenant -> reuse, not orphan', () => {
+    const dir = path.join(cache, 'ws-side-same');
+    writeSidecar(dir, { id: 'ws-side-same', tenantId: 'tenant-a', root: dir, openedAt: 'x' });
+    const gate = classifyOpenDestination(dir, { registry: new WorkspaceManager().list(), requestTenantId: 'tenant-a' });
+    assert.equal(gate.action, 'reuse');
+    assert.equal(gate.ownerWorkspaceId, 'ws-side-same');
+    assert.equal(gate.registration.source, 'sidecar');
+  });
+
+  test('sidecar of ANOTHER tenant keeps the registered-dir rule: deny (never touched, never reused)', () => {
+    const dir = path.join(cache, 'ws-side-other');
+    writeSidecar(dir, { id: 'ws-side-other', tenantId: 'tenant-b', root: dir });
+    const gate = classifyOpenDestination(dir, { registry: [], requestTenantId: 'tenant-a' });
+    assert.equal(gate.action, 'deny');
+    assert.equal(gate.reason, 'owned_by_another_tenant');
+    assert.equal(gate.ownerTenantId, 'tenant-b');
+  });
+
+  test('sidecar with unknown tenant on either side -> reuse (non-destructive without proof)', () => {
+    const dir = path.join(cache, 'ws-side-unknown');
+    writeSidecar(dir, { id: 'ws-side-unknown', tenantId: null, root: dir });
+    assert.equal(classifyOpenDestination(dir, { registry: [], requestTenantId: 'tenant-a' }).action, 'reuse');
+    const dir2 = path.join(cache, 'ws-side-unknown-req');
+    writeSidecar(dir2, { id: 'ws-side-unknown-req', tenantId: 'tenant-b', root: dir2 });
+    assert.equal(classifyOpenDestination(dir2, { registry: [], requestTenantId: null }).action, 'reuse');
+  });
+
+  test('multi-repo: a per-repo sub-dir is owned by the PARENT sidecar', () => {
+    const parent = path.join(cache, 'ws-side-multi');
+    const sub = path.join(parent, 'ACME_api');
+    fs.mkdirSync(sub, { recursive: true });
+    writeSidecar(parent, { id: 'ws-side-multi', tenantId: 'tenant-a', root: parent });
+    assert.equal(findRegistrationForDir(sub, []).id, 'ws-side-multi');
+    assert.equal(classifyOpenDestination(sub, { registry: [], requestTenantId: 'tenant-b' }).action, 'deny');
+  });
+
+  test('invalid sidecars are ignored (still orphan): junk JSON, missing id, root of a DIFFERENT dir', () => {
+    const junk = path.join(cache, 'ws-side-junk');
+    fs.mkdirSync(junk, { recursive: true });
+    fs.writeFileSync(path.join(junk, WORKSPACE_SIDECAR), '{not json');
+    assert.equal(readWorkspaceSidecar(junk), null);
+    const noId = path.join(cache, 'ws-side-noid');
+    writeSidecar(noId, { tenantId: 't', root: noId });
+    assert.equal(readWorkspaceSidecar(noId), null);
+    const moved = path.join(cache, 'ws-side-moved');
+    writeSidecar(moved, { id: 'ws-x', tenantId: 't', root: path.join(cache, 'somewhere-else') });
+    assert.equal(readWorkspaceSidecar(moved), null);
+    for (const d of [junk, noId, moved]) {
+      assert.equal(classifyOpenDestination(d, { registry: [], requestTenantId: 'tenant-a' }).action, 'clean_and_fresh');
+    }
+    assert.equal(readWorkspaceSidecar(path.join(cache, 'does-not-exist')), null);
+  });
+
+  test('in-memory registry still wins over a sidecar; readSidecar:null disables the fallback', () => {
+    const dir = path.join(cache, 'ws-side-prec');
+    writeSidecar(dir, { id: 'ws-from-disk', tenantId: 'tenant-b', root: dir });
+    const reg = [{ id: 'ws-from-mem', root: dir, tenantId: 'tenant-a' }];
+    assert.equal(findRegistrationForDir(dir, reg).id, 'ws-from-mem');
+    assert.equal(findRegistrationForDir(dir, [], { readSidecar: null }), null);
+  });
+
+  test('open() without tenant meta REHYDRATES the tenant from the sidecar; close() removes it', async () => {
+    const dir = path.join(cache, 'ws-side-rehydrate');
+    writeSidecar(dir, { id: 'ws-side-rehydrate', tenantId: 'tenant-a', root: dir });
+    const mgr = new WorkspaceManager();
+    await mgr.open('ws-side-rehydrate', dir, {});
+    assert.equal(mgr.get('ws-side-rehydrate').tenantId, 'tenant-a');
+    // a DIFFERENT workspaceId re-registering the same dir never inherits it
+    const mgr2 = new WorkspaceManager();
+    await mgr2.open('ws-someone-else', dir, {});
+    assert.equal(mgr2.get('ws-someone-else').tenantId, null);
+    mgr2.close('ws-someone-else');
+    assert.equal(fs.existsSync(path.join(dir, WORKSPACE_SIDECAR)), false);
+    assert.equal(classifyOpenDestination(dir, { registry: [], requestTenantId: 'tenant-a' }).action, 'clean_and_fresh');
+  });
+
+  test('sidecar is invisible to ENG-1 file count and excluded from git (.git/info/exclude)', async () => {
+    const dir = path.join(cache, 'SIDE_gitrepo');
+    fs.mkdirSync(path.join(dir, '.git', 'info'), { recursive: true });
+    const mgr = new WorkspaceManager();
+    await mgr.open('ws-side-git', dir, { tenantId: 'tenant-a' });
+    assert.equal(countFilesExcludingGit(dir), 0, 'empty clone must still count 0');
+    const exclude = fs.readFileSync(path.join(dir, '.git', 'info', 'exclude'), 'utf8');
+    assert.equal(exclude.split('\n').filter((l) => l === WORKSPACE_SIDECAR).length, 1);
+    await mgr.open('ws-side-git', dir, { tenantId: 'tenant-a' }); // idempotent
+    assert.equal(fs.readFileSync(path.join(dir, '.git', 'info', 'exclude'), 'utf8').split('\n').filter((l) => l === WORKSPACE_SIDECAR).length, 1);
+  });
+});

package/test/ranged-read.test.js

@@ -0,0 +1,60 @@
+// test/ranged-read.test.js
+// RANGED READS guard: /workspace/file-content pagination logic. A 7500-line
+// file must never be returned whole by default (context blowout -> the AI
+// falls back to sed-chunking and burns its iteration budget); explicit
+// ranges must slice exactly; small files stay byte-identical (null = caller
+// returns the original response).
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { sliceFileContent } from '../src/utils/ranged-read.js';
+
+function fileOf(lines) {
+  const content = Array.from({ length: lines }, (_, i) => 'L' + (i + 1)).join('\n');
+  return { path: 'big.js', content, lines, size: content.length };
+}
+
+describe('sliceFileContent', () => {
+  test('small file without range returns null (original response unchanged)', () => {
+    assert.equal(sliceFileContent(fileOf(50), { lineCap: 2000 }), null);
+    assert.equal(sliceFileContent(fileOf(2000), { lineCap: 2000 }), null);
+  });
+
+  test('oversized file without range returns first page + truncated + hint', () => {
+    const r = sliceFileContent(fileOf(7501), { lineCap: 2000 });
+    assert.equal(r.truncated, true);
+    assert.equal(r.startLine, 1);
+    assert.equal(r.endLine, 2000);
+    assert.equal(r.totalLines, 7501);
+    assert.ok(r.content.startsWith('L1\n'));
+    assert.ok(r.content.endsWith('\nL2000'));
+    assert.match(r.hint, /startLine=2001&endLine=4000/);
+  });
+
+  test('explicit range slices exactly (1-based, inclusive)', () => {
+    const r = sliceFileContent(fileOf(7501), { startLine: 901, endLine: 903, lineCap: 2000 });
+    assert.equal(r.content, 'L901\nL902\nL903');
+    assert.equal(r.lines, 3);
+    assert.equal(r.totalLines, 7501);
+    assert.equal(r.truncated, undefined);
+  });
+
+  test('endLine beyond EOF clamps; startLine without endLine pages one cap', () => {
+    const eof = sliceFileContent(fileOf(100), { startLine: 95, endLine: 500, lineCap: 2000 });
+    assert.equal(eof.endLine, 100);
+    assert.equal(eof.content, 'L95\nL96\nL97\nL98\nL99\nL100');
+
+    const page = sliceFileContent(fileOf(7501), { startLine: 2001, lineCap: 2000 });
+    assert.equal(page.startLine, 2001);
+    assert.equal(page.endLine, 4000);
+  });
+
+  test('degenerate inputs never throw', () => {
+    assert.equal(sliceFileContent({ path: 'x', content: '' }, {}), null);
+    const r = sliceFileContent(fileOf(10), { startLine: 99, lineCap: 5 });
+    // startLine past EOF clamps to the last line.
+    assert.equal(r.startLine, 10);
+    assert.equal(r.content, 'L10');
+    assert.equal(sliceFileContent(fileOf(10), { startLine: NaN, endLine: NaN, lineCap: NaN }), null);
+  });
+});