@danielblomma/cortex-mcp 2.2.5 → 2.4.1

package/scaffold/mcp/src/daemon/global-host-events.ts

@@ -0,0 +1,288 @@
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadEnterpriseConfig } from "../core/config.js";
+import {
+  enterpriseCredentialId,
+  isAllowedLicenseEndpoint,
+} from "../core/license.js";
+import { matchesEnterpriseHostIdentity } from "../core/enterprise-host-identity.js";
+
+type GlobalHostEvent = Record<string, unknown> & {
+  event_type: "ungoverned_ai_session_detected";
+  timestamp: string;
+  credential_id: string;
+};
+
+type GlobalCursor = {
+  version: 1;
+  credential_id: string;
+  ungoverned_last_key?: string;
+};
+
+const EVENT_FILE_RE = /^ungoverned-\d{4}-\d{2}-\d{2}\.jsonl$/;
+const CURSOR_FILENAME = "global-host-events-cursor.json";
+
+function configuredHome(): string {
+  return process.env.HOME?.trim() || homedir();
+}
+
+function globalEventDir(create: boolean): string | null {
+  try {
+    const home = realpathSync(configuredHome());
+    const cortexDir = join(home, ".cortex");
+    if (!existsSync(cortexDir)) return null;
+    const cortexStat = lstatSync(cortexDir);
+    if (!cortexStat.isDirectory() || cortexStat.isSymbolicLink()) return null;
+    if (realpathSync(cortexDir) !== cortexDir) return null;
+
+    const dir = join(cortexDir, "host-events");
+    if (existsSync(dir)) {
+      const stat = lstatSync(dir);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return null;
+      if (realpathSync(dir) !== dir) return null;
+      chmodSync(dir, 0o700);
+      return dir;
+    }
+    if (!create) return null;
+    mkdirSync(dir, { mode: 0o700 });
+    chmodSync(dir, 0o700);
+    return dir;
+  } catch {
+    return null;
+  }
+}
+
+function eventKey(event: GlobalHostEvent): string {
+  const pid =
+    typeof event.pid === "number" || typeof event.pid === "string"
+      ? String(event.pid)
+      : "0";
+  return `${event.timestamp}#${pid}`;
+}
+
+export function writeGlobalUngovernedEvent(
+  credentialId: string,
+  event: Omit<GlobalHostEvent, "credential_id">,
+): boolean {
+  if (!matchesEnterpriseHostIdentity(credentialId)) return false;
+  const dir = globalEventDir(true);
+  if (!dir) return false;
+  const date = new Date().toISOString().slice(0, 10);
+  const path = join(dir, `ungoverned-${date}.jsonl`);
+  let fd: number | null = null;
+  try {
+    fd = openSync(
+      path,
+      constants.O_WRONLY |
+        constants.O_APPEND |
+        constants.O_CREAT |
+        constants.O_NOFOLLOW,
+      0o600,
+    );
+    fchmodSync(fd, 0o600);
+    writeSync(
+      fd,
+      JSON.stringify({ ...event, credential_id: credentialId }) + "\n",
+      undefined,
+      "utf8",
+    );
+    closeSync(fd);
+    return true;
+  } catch {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        // Best effort.
+      }
+    }
+    return false;
+  }
+}
+
+function readCursor(dir: string, credentialId: string): GlobalCursor {
+  const path = join(dir, CURSOR_FILENAME);
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      return { version: 1, credential_id: credentialId };
+    }
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<GlobalCursor>;
+    if (
+      parsed.version !== 1 ||
+      parsed.credential_id !== credentialId ||
+      (parsed.ungoverned_last_key !== undefined &&
+        typeof parsed.ungoverned_last_key !== "string")
+    ) {
+      return { version: 1, credential_id: credentialId };
+    }
+    return parsed as GlobalCursor;
+  } catch {
+    return { version: 1, credential_id: credentialId };
+  }
+}
+
+function writeCursor(dir: string, cursor: GlobalCursor): void {
+  const path = join(dir, CURSOR_FILENAME);
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(
+      temporaryPath,
+      JSON.stringify(cursor, null, 2) + "\n",
+      { encoding: "utf8", mode: 0o600, flag: "wx" },
+    );
+    chmodSync(temporaryPath, 0o600);
+    renameSync(temporaryPath, path);
+    chmodSync(path, 0o600);
+  } catch (err) {
+    try {
+      unlinkSync(temporaryPath);
+    } catch {
+      // Best effort.
+    }
+    throw err;
+  }
+}
+
+function readEvents(dir: string, credentialId: string): GlobalHostEvent[] {
+  const events: GlobalHostEvent[] = [];
+  for (const name of readdirSync(dir).filter((entry) => EVENT_FILE_RE.test(entry)).sort()) {
+    const path = join(dir, name);
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      for (const line of readFileSync(path, "utf8").split("\n")) {
+        if (!line.trim()) continue;
+        const parsed = JSON.parse(line) as Partial<GlobalHostEvent>;
+        if (
+          parsed.event_type !== "ungoverned_ai_session_detected" ||
+          parsed.credential_id !== credentialId ||
+          typeof parsed.timestamp !== "string"
+        ) {
+          continue;
+        }
+        events.push(parsed as GlobalHostEvent);
+      }
+    } catch {
+      // Skip malformed or concurrently changing files.
+    }
+  }
+  return events.sort((a, b) => eventKey(a).localeCompare(eventKey(b)));
+}
+
+export async function pushGlobalUngovernedEvents(
+  cwd: string,
+  credentialId: string,
+): Promise<{ pushed: number; error?: string }> {
+  if (!matchesEnterpriseHostIdentity(credentialId)) {
+    return { pushed: 0, error: "enterprise identity conflict" };
+  }
+  const config = loadEnterpriseConfig(join(cwd, ".context"));
+  const apiKey = config.enterprise.api_key.trim();
+  const baseUrl = (
+    config.enterprise.base_url || config.enterprise.endpoint
+  ).trim();
+  if (
+    !apiKey ||
+    !baseUrl ||
+    !isAllowedLicenseEndpoint(baseUrl) ||
+    enterpriseCredentialId(baseUrl, apiKey) !== credentialId
+  ) {
+    return { pushed: 0, error: "enterprise identity conflict" };
+  }
+  const dir = globalEventDir(false);
+  if (!dir) return { pushed: 0 };
+  const cursor = readCursor(dir, credentialId);
+  const events = readEvents(dir, credentialId).filter(
+    (event) =>
+      !cursor.ungoverned_last_key ||
+      eventKey(event) > cursor.ungoverned_last_key,
+  );
+  if (events.length === 0) return { pushed: 0 };
+
+  try {
+    const response = await fetch(
+      `${baseUrl.replace(/\/$/, "")}/api/v1/govern/ungoverned`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          events: events.map((event) => ({
+            detected_at: event.timestamp,
+            host_id: event.host_id,
+            cli: event.cli,
+            binary_path: event.binary,
+            args: event.args,
+            sys_user: event.user,
+            parent_pid: event.ppid,
+            pid: event.pid,
+            action_taken: event.action ?? "logged",
+          })),
+        }),
+      },
+    );
+    if (!response.ok) {
+      return {
+        pushed: 0,
+        error: `HTTP ${response.status} ${response.statusText}`,
+      };
+    }
+    cursor.ungoverned_last_key = eventKey(events[events.length - 1]);
+    writeCursor(dir, cursor);
+    return { pushed: events.length };
+  } catch (err) {
+    return {
+      pushed: 0,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export type GlobalHostEventsPusherHandle = {
+  stop(): void;
+};
+
+export function startGlobalUngovernedEventsPusher(
+  cwd: string,
+  credentialId: string,
+  intervalMs: number,
+): GlobalHostEventsPusherHandle {
+  const tick = () => {
+    void pushGlobalUngovernedEvents(cwd, credentialId).then((outcome) => {
+      if (outcome.error) {
+        process.stderr.write(
+          `[cortex-daemon] global host-events push failed: ${outcome.error}\n`,
+        );
+      }
+    });
+  };
+  void Promise.resolve().then(tick);
+  const handle = setInterval(tick, intervalMs);
+  if (typeof handle.unref === "function") handle.unref();
+  return {
+    stop() {
+      clearInterval(handle);
+    },
+  };
+}

package/scaffold/mcp/src/daemon/heartbeat-pusher.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { hostname, platform, release } from "node:os";
 import { loadEnterpriseConfig } from "../core/config.js";
+import { isAllowedEnterpriseEndpoint } from "../core/secure-endpoint.js";
 
 /**
  * Govern host heartbeat — fills the host_enrollment table on cortex-web.
@@ -107,6 +108,9 @@ export async function pushHeartbeat(cwd: string): Promise<HeartbeatPushOutcome>
   if (!apiKey || !baseUrl) {
     return { ok: false, error: "enterprise not configured" };
   }
+  if (!isAllowedEnterpriseEndpoint(baseUrl)) {
+    return { ok: false, error: "insecure or invalid enterprise endpoint" };
+  }
   const payload = buildHeartbeatPayload(cwd);
   try {
     const res = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/govern/heartbeat`, {

package/scaffold/mcp/src/daemon/heartbeat-tracker.ts

@@ -130,6 +130,7 @@ export class HeartbeatTracker {
     const now = options.now ?? new Date();
     const thresholdMs = options.missingThresholdSeconds * 1000;
     const flagged: TamperLockEntry[] = [];
+    const allowedCwds = new Set(options.cwds);
 
     for (const [sessionId, state] of this.sessions) {
       // Cleanup sessions that have been silent forever — they crashed.
@@ -140,6 +141,7 @@ export class HeartbeatTracker {
       }
 
       if (state.ended) continue;
+      if (!allowedCwds.has(state.cwd)) continue;
       // Need at least 2 heartbeats for the "had-activity-then-silence"
       // signal — a single SessionStart followed by silence may just be a
       // user opening Claude and walking away.

package/scaffold/mcp/src/daemon/host-events-pusher.ts

@@ -8,6 +8,7 @@ import {
 } from "node:fs";
 import { join, dirname } from "node:path";
 import { loadEnterpriseConfig } from "../core/config.js";
+import { isAllowedEnterpriseEndpoint } from "../core/secure-endpoint.js";
 
 /**
  * Phase 7 sync flow — host-events pusher.
@@ -150,6 +151,10 @@ export async function pushHostEvents(cwd: string): Promise<PushOutcome> {
     outcome.errors.push("enterprise not configured");
     return outcome;
   }
+  if (!isAllowedEnterpriseEndpoint(baseUrl)) {
+    outcome.errors.push("insecure or invalid enterprise endpoint");
+    return outcome;
+  }
 
   const cursor = readCursor(cwd);
   const ungovernedCursor = normalizeCursor(cursor.ungoverned_last_ts);

package/scaffold/mcp/src/daemon/main.ts

@@ -11,6 +11,9 @@ import type {
   AuditLogResult,
 } from "./protocol.js";
 import { loadEnterpriseConfig, resolveEnterpriseActivation } from "../core/config.js";
+import { configuredEnterpriseCredentialId } from "../core/enterprise-identity.js";
+import { matchesEnterpriseHostIdentity } from "../core/enterprise-host-identity.js";
+import { startGlobalUngovernedEventsPusher } from "./global-host-events.js";
 import { pushMetrics } from "../enterprise/telemetry/sync.js";
 import { TelemetryCollector, type TelemetryMetrics } from "../core/telemetry/collector.js";
 import { resolveTelemetryStateDir, telemetryStatePath } from "../core/telemetry/state-dir.js";
@@ -34,6 +37,10 @@ import { startCapabilitySyncTimer } from "./capability-sync-checker.js";
 import { startHostEventsPusher } from "./host-events-pusher.js";
 import { startEgressProxy } from "./egress-proxy.js";
 import { startHeartbeatPusher } from "./heartbeat-pusher.js";
+import {
+  normalizeProjectCwd,
+  ProjectServiceRegistry,
+} from "./project-service-registry.js";
 import type { HeartbeatPayload, HeartbeatResult } from "./protocol.js";
 
 /**
@@ -302,8 +309,37 @@ async function auditLog(payload: AuditLogPayload): Promise<AuditLogResult> {
 async function main(): Promise<void> {
   // Phase 6: hook heartbeat tracker (per-session activity record + tamper detect).
   const tracker = new HeartbeatTracker();
+  let projectServices: ProjectServiceRegistry | null = null;
+  function registerEnterpriseProject(cwd: string): boolean {
+    const config = loadEnterpriseConfig(join(cwd, ".context"));
+    if (!resolveEnterpriseActivation(config).active) return true;
+    if (projectServices?.has(cwd)) return true;
+    const credentialId = configuredEnterpriseCredentialId(cwd);
+    if (!credentialId || !matchesEnterpriseHostIdentity(credentialId)) {
+      process.stderr.write(
+        `[cortex-daemon] rejected Enterprise project ${cwd}: ` +
+          "this user profile is enrolled to another endpoint or API key\n",
+      );
+      return false;
+    }
+    if (!projectServices?.register(cwd)) {
+      process.stderr.write(
+        `[cortex-daemon] rejected Enterprise project ${cwd}: ` +
+          "this user daemon is already bound to another endpoint or API key\n",
+      );
+      return false;
+    }
+    return true;
+  }
   async function heartbeat(payload: HeartbeatPayload): Promise<HeartbeatResult> {
-    return tracker.recordHeartbeat(payload);
+    const cwd = normalizeProjectCwd(payload.cwd);
+    if (!cwd) {
+      return { recorded: false, tamper_lock_active: false };
+    }
+    if (!registerEnterpriseProject(cwd)) {
+      return { recorded: false, tamper_lock_active: false };
+    }
+    return tracker.recordHeartbeat({ ...payload, cwd });
   }
 
   const daemon = new CortexDaemon({
@@ -312,15 +348,11 @@ async function main(): Promise<void> {
     onAuditLog: auditLog,
     onHeartbeat: heartbeat,
   });
-  await daemon.start();
 
   // Phase 5: Tier 3 ungoverned-session detection. Periodic process scan, audit
   // emit per finding, optional SIGTERM in enforced mode (same-user only).
   const scanInterval = parseInt(process.env.CORTEX_UNGOVERNED_SCAN_MS ?? "", 10);
   const intervalMs = Number.isFinite(scanInterval) && scanInterval > 0 ? scanInterval : 60_000;
-  if (process.env.CORTEX_DISABLE_UNGOVERNED_SCAN !== "1") {
-    startUngovernedScanner({ cwd: process.cwd(), intervalMs });
-  }
 
   // Phase 6: periodic tamper-checker. For each active session that had at
   // least one tool-fired hook then went silent past missing_threshold_seconds,
@@ -343,12 +375,7 @@ async function main(): Promise<void> {
   const pushIntervalRaw = parseInt(process.env.CORTEX_HOST_EVENTS_PUSH_MS ?? "", 10);
   const pushIntervalMs =
     Number.isFinite(pushIntervalRaw) && pushIntervalRaw > 0 ? pushIntervalRaw : 5 * 60 * 1000;
-  if (process.env.CORTEX_DISABLE_SYNC_CHECK !== "1") {
-    startSyncTimer(process.cwd(), syncIntervalMs);
-  }
-  if (process.env.CORTEX_DISABLE_HOST_EVENTS_PUSH !== "1") {
-    startHostEventsPusher(process.cwd(), pushIntervalMs);
-  }
+
   // Skills v3: poll cortex-web for org-authored skills, write SKILL.md
   // files into per-CLI user-scope directories. Runs at the same cadence
   // as the govern-config sync check by default but is independently
@@ -356,9 +383,6 @@ async function main(): Promise<void> {
   const skillSyncRaw = parseInt(process.env.CORTEX_SKILL_SYNC_MS ?? "", 10);
   const skillSyncMs =
     Number.isFinite(skillSyncRaw) && skillSyncRaw > 0 ? skillSyncRaw : syncIntervalMs;
-  if (process.env.CORTEX_DISABLE_SKILL_SYNC !== "1") {
-    startSkillSyncTimer(process.cwd(), skillSyncMs);
-  }
 
   // Harness Phase 2: poll cortex-web for org-authored workflows, cache
   // their definitions locally so cortex.workflow.start can resolve
@@ -370,9 +394,6 @@ async function main(): Promise<void> {
     Number.isFinite(workflowSyncRaw) && workflowSyncRaw > 0
       ? workflowSyncRaw
       : skillSyncMs;
-  if (process.env.CORTEX_DISABLE_WORKFLOW_SYNC !== "1") {
-    startWorkflowSyncTimer(process.cwd(), workflowSyncMs);
-  }
 
   // Harness Phase 2: poll cortex-web for org-authored capabilities and
   // cache definitions locally so evaluateToolCall can merge them over
@@ -384,18 +405,68 @@ async function main(): Promise<void> {
     Number.isFinite(capabilitySyncRaw) && capabilitySyncRaw > 0
       ? capabilitySyncRaw
       : workflowSyncMs;
-  if (process.env.CORTEX_DISABLE_CAPABILITY_SYNC !== "1") {
-    startCapabilitySyncTimer(process.cwd(), capabilitySyncMs);
-  }
 
   // Govern host heartbeat — fills host_enrollment on cortex-web so the
   // dashboard at /dashboard/govern actually shows this host.
   const heartbeatRaw = parseInt(process.env.CORTEX_HEARTBEAT_PUSH_MS ?? "", 10);
   const heartbeatMs =
     Number.isFinite(heartbeatRaw) && heartbeatRaw > 0 ? heartbeatRaw : 5 * 60 * 1000;
-  if (process.env.CORTEX_DISABLE_HEARTBEAT_PUSH !== "1") {
-    startHeartbeatPusher(process.cwd(), heartbeatMs);
-  }
+
+  projectServices = new ProjectServiceRegistry((cwd) => {
+    const handles = [];
+    if (process.env.CORTEX_DISABLE_SYNC_CHECK !== "1") {
+      handles.push(startSyncTimer(cwd, syncIntervalMs));
+    }
+    if (process.env.CORTEX_DISABLE_HOST_EVENTS_PUSH !== "1") {
+      handles.push(startHostEventsPusher(cwd, pushIntervalMs));
+    }
+    return handles;
+  }, {
+    credentialIdForCwd: configuredEnterpriseCredentialId,
+    hostFactory: (cwd, credentialId) => {
+      const handles = [];
+      // These services operate on user-global process or artifact state.
+      // One explicit host governance project owns them; projects carrying
+      // another Enterprise identity are rejected by the registry.
+      if (process.env.CORTEX_DISABLE_UNGOVERNED_SCAN !== "1") {
+        // Process snapshots do not carry a trustworthy project cwd. Keep the
+        // single host-wide scanner detection-only so an enforced project can
+        // never terminate a process belonging to an advisory project.
+        handles.push(startUngovernedScanner({
+          cwd,
+          credentialId,
+          intervalMs,
+          mode: "advisory",
+        }));
+      }
+      if (process.env.CORTEX_DISABLE_HOST_EVENTS_PUSH !== "1") {
+        handles.push(
+          startGlobalUngovernedEventsPusher(
+            cwd,
+            credentialId,
+            pushIntervalMs,
+          ),
+        );
+      }
+      if (process.env.CORTEX_DISABLE_SKILL_SYNC !== "1") {
+        handles.push(startSkillSyncTimer(cwd, skillSyncMs));
+      }
+      if (process.env.CORTEX_DISABLE_WORKFLOW_SYNC !== "1") {
+        handles.push(startWorkflowSyncTimer(cwd, workflowSyncMs));
+      }
+      if (process.env.CORTEX_DISABLE_CAPABILITY_SYNC !== "1") {
+        handles.push(startCapabilitySyncTimer(cwd, capabilitySyncMs));
+      }
+      if (process.env.CORTEX_DISABLE_HEARTBEAT_PUSH !== "1") {
+        handles.push(startHeartbeatPusher(cwd, heartbeatMs));
+      }
+      return handles;
+    },
+  });
+
+  await daemon.start();
+  const startupCwd = normalizeProjectCwd(process.cwd());
+  if (startupCwd) registerEnterpriseProject(startupCwd);
 
   // Phase 4 task 19: cortex egress proxy. Logs SNI + destination per
   // outbound connection (no TLS termination). cortex run sets
@@ -404,7 +475,10 @@ async function main(): Promise<void> {
   const proxyPortRaw = parseInt(process.env.CORTEX_EGRESS_PROXY_PORT ?? "", 10);
   const proxyPort = Number.isFinite(proxyPortRaw) && proxyPortRaw > 0 ? proxyPortRaw : 18888;
   if (process.env.CORTEX_DISABLE_EGRESS_PROXY !== "1") {
-    startEgressProxy({ cwd: process.cwd(), port: proxyPort })
+    // A shared proxy connection has no trustworthy project identity. Keep
+    // transport support, but suppress project audit emission until callers
+    // use an attributable per-project channel.
+    startEgressProxy({ port: proxyPort })
       .then((handle) => {
         process.stderr.write(
           `[cortex-daemon] egress proxy listening on 127.0.0.1:${handle.port}\n`,
@@ -447,7 +521,7 @@ async function main(): Promise<void> {
   if (process.env.CORTEX_DISABLE_TAMPER_CHECK !== "1") {
     const checkTimer = setInterval(() => {
       const detected = tracker.detectTamper({
-        cwds: [process.cwd()],
+        cwds: projectServices?.projectCwds() ?? [],
         missingThresholdSeconds,
       });
       for (const entry of detected) {

package/scaffold/mcp/src/daemon/project-service-registry.ts

@@ -0,0 +1,107 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export type ProjectServiceHandle = {
+  stop(): void | Promise<void>;
+};
+
+export type ProjectServiceFactory = (
+  cwd: string,
+) => ReadonlyArray<ProjectServiceHandle>;
+
+export type HostServiceFactory = (
+  cwd: string,
+  credentialId: string,
+) => ReadonlyArray<ProjectServiceHandle>;
+
+export type ProjectServiceRegistryOptions = {
+  credentialIdForCwd?: (cwd: string) => string | null;
+  hostFactory?: HostServiceFactory;
+};
+
+export function normalizeProjectCwd(cwd: string): string | null {
+  if (!cwd.trim()) return null;
+  const candidate = resolve(cwd);
+  try {
+    if (!existsSync(candidate) || !statSync(candidate).isDirectory()) {
+      return null;
+    }
+    if (!existsSync(join(candidate, ".context"))) {
+      return null;
+    }
+    return realpathSync(candidate);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Owns background services for every project observed by the per-user daemon.
+ * Request-time handlers already carry cwd in their payloads; this registry
+ * gives the periodic services the same project isolation.
+ */
+export class ProjectServiceRegistry {
+  private readonly projects = new Map<
+    string,
+    ReadonlyArray<ProjectServiceHandle>
+  >();
+  private hostCredentialId: string | null = null;
+  private hostHandles: ReadonlyArray<ProjectServiceHandle> = [];
+
+  constructor(
+    private readonly factory: ProjectServiceFactory,
+    private readonly options: ProjectServiceRegistryOptions = {},
+  ) {}
+
+  register(cwd: string): boolean {
+    const normalized = normalizeProjectCwd(cwd);
+    if (!normalized || this.projects.has(normalized)) return false;
+    const credentialId =
+      this.options.credentialIdForCwd?.(normalized) ?? "project-local";
+    if (!credentialId) return false;
+    if (
+      this.hostCredentialId &&
+      this.hostCredentialId !== credentialId
+    ) {
+      return false;
+    }
+    if (!this.hostCredentialId) {
+      this.hostCredentialId = credentialId;
+      this.hostHandles =
+        this.options.hostFactory?.(normalized, credentialId) ?? [];
+    }
+    const handles = this.factory(normalized);
+    this.projects.set(normalized, handles);
+    return true;
+  }
+
+  has(cwd: string): boolean {
+    const normalized = normalizeProjectCwd(cwd);
+    return normalized ? this.projects.has(normalized) : false;
+  }
+
+  projectCwds(): string[] {
+    return Array.from(this.projects.keys());
+  }
+
+  async stopAll(): Promise<void> {
+    const handles = [
+      ...Array.from(this.projects.values()).flat(),
+      ...this.hostHandles,
+    ];
+    this.projects.clear();
+    this.hostHandles = [];
+    this.hostCredentialId = null;
+    await Promise.allSettled(
+      handles.map((handle) => Promise.resolve(handle.stop())),
+    );
+  }
+
+  size(): number {
+    return this.projects.size;
+  }
+
+  activeCredentialId(): string | null {
+    return this.hostCredentialId;
+  }
+}