@provos/ironcurtain 0.9.1 → 0.11.0

package/dist/config/paths.d.ts

@@ -1,3 +1,4 @@
+import type { BundleId } from '../session/types.js';
 /**
  * Returns the IronCurtain home directory.
  * Defaults to ~/.ironcurtain, overridable via IRONCURTAIN_HOME env var.
@@ -7,6 +8,14 @@ export declare function getIronCurtainHome(): string;
  * Returns the sessions base directory: {home}/sessions/
  */
 export declare function getSessionsDir(): string;
+/**
+ * Filenames shared across session-scoped and workflow-state-scoped
+ * layouts. Centralized so the "single source of truth" for how session
+ * artifacts are named does not drift between helpers and call sites.
+ */
+export declare const SESSION_LOG_FILENAME = "session.log";
+export declare const SESSION_METADATA_FILENAME = "session-metadata.json";
+export declare const SESSION_STATE_FILENAME = "session-state.json";
 /**
  * Returns the session directory for a given session ID:
  *   {home}/sessions/{sessionId}/
@@ -126,6 +135,12 @@ export declare function getReadOnlyPolicyDir(): string;
  * (either the user's IronCurtain home or the package config dir).
  */
 export declare function getPackageConfigDir(): string;
+/**
+ * Reads just the user constitution text (without base principles).
+ * Returns empty string if no user constitution file exists, because
+ * an absent user constitution is a valid state (means "no server-specific guidance").
+ */
+export declare function loadUserConstitutionText(): string;
 /**
  * Loads the combined constitution text (base + optional user constitution).
  * If ~/.ironcurtain/constitution.md exists, it replaces the package-bundled base.
@@ -137,6 +152,20 @@ export declare function loadConstitutionText(packageBasePath: string): string;
  * Loads the combined constitution and returns its SHA-256 hex digest.
  */
 export declare function computeConstitutionHash(basePath: string): string;
+/**
+ * Returns the user workflows directory: {home}/workflows/
+ * Users can place custom workflow definitions here.
+ */
+export declare function getUserWorkflowsDir(): string;
+/**
+ * Returns the user-global skills directory: {home}/skills/
+ *
+ * Skills placed here are layered into every Docker session regardless
+ * of workflow or persona. See `src/skills/discovery.ts` for the
+ * resolution order (user-global → persona → workflow, last-wins on
+ * collision) and `docs/designs/skills-capability.md` for the format.
+ */
+export declare function getUserSkillsDir(): string;
 /**
  * Returns the OAuth directory: {home}/oauth/
  * Stores provider credentials and token files.
@@ -159,6 +188,14 @@ export declare function getOAuthCredentialsPath(providerId: string): string;
  * can communicate with a running daemon (e.g., add-job, run-job).
  */
 export declare function getDaemonSocketPath(): string;
+/**
+ * Returns the web UI state file path: {home}/web-ui.json
+ *
+ * The daemon writes connection info (port + auth token) here on startup
+ * so CLI commands (e.g., `observe`) can connect to the WebSocket server.
+ * The file is removed on daemon shutdown.
+ */
+export declare function getWebUiStatePath(): string;
 /**
  * Returns the jobs base directory: {home}/jobs/
  */
@@ -182,3 +219,147 @@ export declare function getJobWorkspaceDir(jobId: string): string;
  * {home}/jobs/{jobId}/runs/
  */
 export declare function getJobRunsDir(jobId: string): string;
+/**
+ * Returns the workflow runs base directory: {home}/workflow-runs/
+ */
+export declare function getWorkflowRunsDir(): string;
+/**
+ * Returns the directory for a specific workflow run:
+ * {home}/workflow-runs/{workflowId}/
+ */
+export declare function getWorkflowRunDir(workflowId: string): string;
+/**
+ * Returns the containers root for a workflow run:
+ *   {home}/workflow-runs/{workflowId}/containers/
+ *
+ * Each bundle (one Docker container + its MITM/Code-Mode proxies, CA,
+ * fake keys, audit log, and per-state artifacts) lives under
+ * `containers/<bundleId>/`. A single-scope workflow has one entry; a
+ * bifurcated workflow with distinct `containerScope` values has one
+ * entry per distinct scope.
+ */
+export declare function getWorkflowContainersDir(workflowId: string): string;
+/**
+ * Returns the outer directory for a single bundle within a workflow run:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/
+ *
+ * Contains the bundle's audit log, its inner `bundle/` directory with
+ * sockets/CA/fake keys/orientation, and the per-state `states/` tree.
+ */
+export declare function getBundleDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the inner bundle artifact directory:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/bundle/
+ *
+ * Holds the bundle-scoped files that `DockerInfrastructure` manages:
+ * MCP/MITM sockets, CA cert, fake keys, orientation scripts, and the
+ * effective system prompt. Bind-mounted into the Docker container for
+ * the UDS endpoints.
+ */
+export declare function getBundleBundleDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the per-bundle audit log path:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/audit.jsonl
+ *
+ * One audit file per bundle (coordinator). Each entry is tagged with
+ * the active `persona` so consumers can reconstruct per-persona /
+ * per-re-entry slices by scanning.
+ */
+export declare function getBundleAuditLogPath(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the per-bundle states root:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/states/
+ *
+ * Each agent state invocation (including re-entries) that borrows this
+ * bundle gets its own subdirectory keyed by `{stateId}.{N}`.
+ */
+export declare function getBundleStatesDir(workflowId: string, bundleId: BundleId): string;
+/**
+ * Returns the per-invocation artifact directory for a single state:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/states/{stateSlug}/
+ *
+ * Holds this invocation's `session.log` and `session-metadata.json`.
+ * `stateSlug` is `{stateId}.{N}` (e.g., `fetch.1`, `plan.2`).
+ */
+export declare function getInvocationDir(workflowId: string, bundleId: BundleId, stateSlug: string): string;
+/**
+ * Picks the next available `{stateId}.{N}` slug in `statesDir`. Returns
+ * `${stateId}.1` when no matching dir exists; otherwise the max existing
+ * N plus 1. Used so every state entry (true logical re-visits AND resume
+ * legs of a single visit) gets its own forensic dir — `session.log` and
+ * `session-metadata.json` no longer interleave across resume attempts.
+ */
+export declare function nextStateSlug(statesDir: string, stateId: string): string;
+/**
+ * Returns the coordinator control socket path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/ctrl.sock
+ *
+ * The coordinator listens on this UDS to accept policy hot-swap
+ * requests from the orchestrator. The socket sits under the bundle's
+ * per-bundle runtime root (mode `0o700`) so filesystem permissions
+ * gate access.
+ *
+ * The directory slug is truncated to 12 chars of `bundleId` so the
+ * assembled path fits under macOS `sockaddr_un.sun_path` (104 chars).
+ * 16^12 ≈ 2.8e14 combinations — collisions in the host-wide
+ * `run/<slug>/` namespace are astronomical.
+ */
+export declare function getBundleControlSocketPath(bundleId: BundleId): string;
+/**
+ * Returns the per-bundle runtime root directory:
+ *   {home}/run/{bundleId[0:12]}/
+ *
+ * Holds the coordinator control socket plus two subdirectories
+ * (`sockets/` and `host/`) so the bind-mounted UDS files can be
+ * co-located without exposing host-only sockets to the container.
+ */
+export declare function getBundleRuntimeRoot(bundleId: BundleId): string;
+/**
+ * Returns the per-bundle container-visible sockets directory:
+ *   {home}/run/{bundleId[0:12]}/sockets/
+ *
+ * Two UDS files live here:
+ *  - `proxy.sock`      (Code Mode proxy — bind-mounted into container)
+ *  - `mitm-proxy.sock` (MITM proxy      — bind-mounted into container)
+ *
+ * This directory is what `prepareDockerInfrastructure()` bind-mounts as
+ * `/run/ironcurtain/` inside the container (read-write). Only these two
+ * socket files live here — no audit logs, escalation files, or other
+ * session artifacts.
+ */
+export declare function getBundleSocketsDir(bundleId: BundleId): string;
+/**
+ * Returns the per-bundle host-only directory:
+ *   {home}/run/{bundleId[0:12]}/host/
+ *
+ * Holds UDS files that must NOT be visible to the container
+ * (currently just the MITM control socket).
+ */
+export declare function getBundleHostOnlyDir(bundleId: BundleId): string;
+/**
+ * Code Mode proxy UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/sockets/proxy.sock
+ *
+ * Bound by the host-side Code Mode proxy; reachable inside the
+ * container as `/run/ironcurtain/proxy.sock` via the bind mount on
+ * `getBundleSocketsDir()`.
+ */
+export declare function getBundleProxySocketPath(bundleId: BundleId): string;
+/**
+ * MITM proxy UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/sockets/mitm-proxy.sock
+ *
+ * Bound by the host-side MITM proxy; reachable inside the container as
+ * `/run/ironcurtain/mitm-proxy.sock` via the bind mount on
+ * `getBundleSocketsDir()`.
+ */
+export declare function getBundleMitmProxySocketPath(bundleId: BundleId): string;
+/**
+ * MITM control UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/host/mitm-control.sock
+ *
+ * Host-local only — lives under `host/` rather than `sockets/` so the
+ * bind mount that exposes `sockets/` at `/run/ironcurtain/` does not
+ * expose this socket to the container.
+ */
+export declare function getBundleMitmControlSocketPath(bundleId: BundleId): string;

package/dist/config/paths.js

@@ -1,9 +1,34 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { SESSION_STATE_FILENAME } from '../docker/pty-types.js';
+import { JOB_ID_PATTERN } from '../types/slug.js';
+/**
+ * Short slug length used in file/directory names that must fit under
+ * `sockaddr_un.sun_path` (macOS ~104 bytes, Linux ~108 bytes). 12 hex
+ * chars give 16^12 ≈ 2.8e14 combinations, so collisions in the
+ * host-wide `~/.ironcurtain/run/<slug>/` namespace are astronomical —
+ * important because bundle teardown runs `rmSync(runtimeRoot)` and a
+ * collision would wipe another live bundle's sockets. The full UUID
+ * remains the authoritative identity in Docker labels and directory
+ * paths; only socket-adjacent names use the short form. The new
+ * `~/.ironcurtain/run/<12chars>/sockets/<name>.sock` layout has ample
+ * sun_path budget for the longer slug on both macOS (104) and Linux
+ * (108).
+ */
+const BUNDLE_SLUG_LEN = 12;
+/**
+ * Derives the short slug from a `BundleId`. Strips hyphens first so the
+ * resulting `BUNDLE_SLUG_LEN` characters are all hex — a raw
+ * `substring(0, 12)` on a canonical UUID would include the hyphen at
+ * position 8 and yield only 11 hex digits of entropy (16^11 ≈ 1.8e13).
+ * 12 hex digits give 16^12 ≈ 2.8e14, matching the collision-space math
+ * the layout depends on.
+ */
+function toBundleSlug(bundleId) {
+    return bundleId.replace(/-/g, '').substring(0, BUNDLE_SLUG_LEN);
+}
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Returns the IronCurtain home directory.
@@ -19,12 +44,37 @@ export function getSessionsDir() {
     return resolve(getIronCurtainHome(), 'sessions');
 }
 /**
- * Validates that a session ID contains only safe characters
- * (alphanumeric, hyphens, underscores) to prevent path traversal.
+ * Characters permitted in any identifier that gets embedded in a
+ * filesystem path by this module (session IDs, workflow IDs, persona
+ * slugs, daemon log names). Rejects path separators, glob
+ * metacharacters, NUL bytes, and everything else that could escape the
+ * target directory.
+ */
+const PATH_SAFE_SLUG_RE = /^[a-zA-Z0-9_-]+$/;
+function assertPathSafeSlug(kind, value) {
+    if (!PATH_SAFE_SLUG_RE.test(value)) {
+        throw new Error(`Invalid ${kind}: ${value}`);
+    }
+}
+/**
+ * Filenames shared across session-scoped and workflow-state-scoped
+ * layouts. Centralized so the "single source of truth" for how session
+ * artifacts are named does not drift between helpers and call sites.
+ */
+export const SESSION_LOG_FILENAME = 'session.log';
+export const SESSION_METADATA_FILENAME = 'session-metadata.json';
+export const SESSION_STATE_FILENAME = 'session-state.json';
+/**
+ * Validates a workflow state slug of the form `{stateId}.{visitCount}`
+ * (e.g., `fetch.1`, `plan.2`). Accepts dot-separated segments where
+ * each segment satisfies `PATH_SAFE_SLUG_RE`. Empty segments — produced
+ * by `..`, leading or trailing dots — fail the per-segment check.
  */
-function validateSessionId(sessionId) {
-    if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) {
-        throw new Error(`Invalid session ID: ${sessionId}`);
+function assertStateSlug(value) {
+    if (value.length === 0)
+        throw new Error(`Invalid state slug: ${value}`);
+    for (const segment of value.split('.')) {
+        assertPathSafeSlug('state slug segment', segment);
     }
 }
 /**
@@ -32,7 +82,7 @@ function validateSessionId(sessionId) {
  *   {home}/sessions/{sessionId}/
  */
 export function getSessionDir(sessionId) {
-    validateSessionId(sessionId);
+    assertPathSafeSlug('session ID', sessionId);
     return resolve(getSessionsDir(), sessionId);
 }
 /**
@@ -54,7 +104,7 @@ export function getSessionEscalationDir(sessionId) {
  *   {home}/sessions/{sessionId}/session-metadata.json
  */
 export function getSessionMetadataPath(sessionId) {
-    return resolve(getSessionDir(sessionId), 'session-metadata.json');
+    return resolve(getSessionDir(sessionId), SESSION_METADATA_FILENAME);
 }
 /**
  * Returns the audit log path for a given session:
@@ -75,7 +125,7 @@ export function getSessionInteractionLogPath(sessionId) {
  *   {home}/sessions/{sessionId}/session.log
  */
 export function getSessionLogPath(sessionId) {
-    return resolve(getSessionDir(sessionId), 'session.log');
+    return resolve(getSessionDir(sessionId), SESSION_LOG_FILENAME);
 }
 /**
  * Returns the LLM interaction log path for a given session:
@@ -142,9 +192,7 @@ export function getLogsDir() {
  * E.g., getDaemonLogPath('signal-bot') → {home}/logs/signal-bot.log
  */
 export function getDaemonLogPath(name) {
-    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-        throw new Error(`Invalid daemon log name: ${name}`);
-    }
+    assertPathSafeSlug('daemon log name', name);
     return resolve(getLogsDir(), `${name}.log`);
 }
 /**
@@ -194,6 +242,22 @@ export function getReadOnlyPolicyDir() {
 export function getPackageConfigDir() {
     return resolve(__dirname);
 }
+/**
+ * Reads just the user constitution text (without base principles).
+ * Returns empty string if no user constitution file exists, because
+ * an absent user constitution is a valid state (means "no server-specific guidance").
+ */
+export function loadUserConstitutionText() {
+    const userPath = getUserConstitutionPath();
+    const fallbackPath = getBaseUserConstitutionPath();
+    if (existsSync(userPath)) {
+        return readFileSync(userPath, 'utf-8');
+    }
+    if (existsSync(fallbackPath)) {
+        return readFileSync(fallbackPath, 'utf-8');
+    }
+    return '';
+}
 /**
  * Loads the combined constitution text (base + optional user constitution).
  * If ~/.ironcurtain/constitution.md exists, it replaces the package-bundled base.
@@ -209,17 +273,10 @@ export function loadConstitutionText(packageBasePath) {
     const base = readFileSync(basePath, 'utf-8');
     const userPath = getUserConstitutionPath();
     const userFallbackPath = getBaseUserConstitutionPath();
-    let effectiveUserPath;
-    if (existsSync(userPath)) {
-        effectiveUserPath = userPath;
-    }
-    else if (existsSync(userFallbackPath)) {
-        effectiveUserPath = userFallbackPath;
-    }
-    else {
+    if (!existsSync(userPath) && !existsSync(userFallbackPath)) {
         throw new Error(`User constitution not found: tried ${userPath} and ${userFallbackPath}`);
     }
-    const user = readFileSync(effectiveUserPath, 'utf-8');
+    const user = loadUserConstitutionText();
     return `${base}\n\n${user}`;
 }
 /**
@@ -229,6 +286,24 @@ export function computeConstitutionHash(basePath) {
     const text = loadConstitutionText(basePath);
     return createHash('sha256').update(text).digest('hex');
 }
+/**
+ * Returns the user workflows directory: {home}/workflows/
+ * Users can place custom workflow definitions here.
+ */
+export function getUserWorkflowsDir() {
+    return resolve(getIronCurtainHome(), 'workflows');
+}
+/**
+ * Returns the user-global skills directory: {home}/skills/
+ *
+ * Skills placed here are layered into every Docker session regardless
+ * of workflow or persona. See `src/skills/discovery.ts` for the
+ * resolution order (user-global → persona → workflow, last-wins on
+ * collision) and `docs/designs/skills-capability.md` for the format.
+ */
+export function getUserSkillsDir() {
+    return resolve(getIronCurtainHome(), 'skills');
+}
 // ---------------------------------------------------------------------------
 // OAuth paths
 // ---------------------------------------------------------------------------
@@ -276,6 +351,16 @@ export function getOAuthCredentialsPath(providerId) {
 export function getDaemonSocketPath() {
     return resolve(getIronCurtainHome(), 'daemon.sock');
 }
+/**
+ * Returns the web UI state file path: {home}/web-ui.json
+ *
+ * The daemon writes connection info (port + auth token) here on startup
+ * so CLI commands (e.g., `observe`) can connect to the WebSocket server.
+ * The file is removed on daemon shutdown.
+ */
+export function getWebUiStatePath() {
+    return resolve(getIronCurtainHome(), 'web-ui.json');
+}
 // ---------------------------------------------------------------------------
 // Job paths (cron mode)
 // ---------------------------------------------------------------------------
@@ -285,7 +370,6 @@ export function getDaemonSocketPath() {
 export function getJobsDir() {
     return resolve(getIronCurtainHome(), 'jobs');
 }
-import { JOB_ID_PATTERN } from '../cron/types.js';
 /**
  * Validates that a job ID contains only safe characters.
  */
@@ -322,4 +406,223 @@ export function getJobWorkspaceDir(jobId) {
 export function getJobRunsDir(jobId) {
     return resolve(getJobDir(jobId), 'runs');
 }
+// ---------------------------------------------------------------------------
+// Workflow run paths
+// ---------------------------------------------------------------------------
+/**
+ * Returns the workflow runs base directory: {home}/workflow-runs/
+ */
+export function getWorkflowRunsDir() {
+    return resolve(getIronCurtainHome(), 'workflow-runs');
+}
+/**
+ * Returns the directory for a specific workflow run:
+ * {home}/workflow-runs/{workflowId}/
+ */
+export function getWorkflowRunDir(workflowId) {
+    assertPathSafeSlug('workflow ID', workflowId);
+    return resolve(getWorkflowRunsDir(), workflowId);
+}
+/**
+ * Returns the containers root for a workflow run:
+ *   {home}/workflow-runs/{workflowId}/containers/
+ *
+ * Each bundle (one Docker container + its MITM/Code-Mode proxies, CA,
+ * fake keys, audit log, and per-state artifacts) lives under
+ * `containers/<bundleId>/`. A single-scope workflow has one entry; a
+ * bifurcated workflow with distinct `containerScope` values has one
+ * entry per distinct scope.
+ */
+export function getWorkflowContainersDir(workflowId) {
+    return resolve(getWorkflowRunDir(workflowId), 'containers');
+}
+/**
+ * Returns the outer directory for a single bundle within a workflow run:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/
+ *
+ * Contains the bundle's audit log, its inner `bundle/` directory with
+ * sockets/CA/fake keys/orientation, and the per-state `states/` tree.
+ */
+export function getBundleDir(workflowId, bundleId) {
+    assertPathSafeSlug('bundle ID', bundleId);
+    return resolve(getWorkflowContainersDir(workflowId), bundleId);
+}
+/**
+ * Returns the inner bundle artifact directory:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/bundle/
+ *
+ * Holds the bundle-scoped files that `DockerInfrastructure` manages:
+ * MCP/MITM sockets, CA cert, fake keys, orientation scripts, and the
+ * effective system prompt. Bind-mounted into the Docker container for
+ * the UDS endpoints.
+ */
+export function getBundleBundleDir(workflowId, bundleId) {
+    return resolve(getBundleDir(workflowId, bundleId), 'bundle');
+}
+/**
+ * Returns the per-bundle audit log path:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/audit.jsonl
+ *
+ * One audit file per bundle (coordinator). Each entry is tagged with
+ * the active `persona` so consumers can reconstruct per-persona /
+ * per-re-entry slices by scanning.
+ */
+export function getBundleAuditLogPath(workflowId, bundleId) {
+    return resolve(getBundleDir(workflowId, bundleId), 'audit.jsonl');
+}
+/**
+ * Returns the per-bundle states root:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/states/
+ *
+ * Each agent state invocation (including re-entries) that borrows this
+ * bundle gets its own subdirectory keyed by `{stateId}.{N}`.
+ */
+export function getBundleStatesDir(workflowId, bundleId) {
+    return resolve(getBundleDir(workflowId, bundleId), 'states');
+}
+/**
+ * Returns the per-invocation artifact directory for a single state:
+ *   {home}/workflow-runs/{workflowId}/containers/{bundleId}/states/{stateSlug}/
+ *
+ * Holds this invocation's `session.log` and `session-metadata.json`.
+ * `stateSlug` is `{stateId}.{N}` (e.g., `fetch.1`, `plan.2`).
+ */
+export function getInvocationDir(workflowId, bundleId, stateSlug) {
+    assertStateSlug(stateSlug);
+    return resolve(getBundleStatesDir(workflowId, bundleId), stateSlug);
+}
+/**
+ * Picks the next available `{stateId}.{N}` slug in `statesDir`. Returns
+ * `${stateId}.1` when no matching dir exists; otherwise the max existing
+ * N plus 1. Used so every state entry (true logical re-visits AND resume
+ * legs of a single visit) gets its own forensic dir — `session.log` and
+ * `session-metadata.json` no longer interleave across resume attempts.
+ */
+export function nextStateSlug(statesDir, stateId) {
+    assertPathSafeSlug('state ID', stateId);
+    let max = 0;
+    if (existsSync(statesDir)) {
+        const prefix = `${stateId}.`;
+        for (const entry of readdirSync(statesDir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !entry.name.startsWith(prefix))
+                continue;
+            // Decimal-digit-only suffix; reject "1e6", "0x10", " 1 ", "01",
+            // etc. so a stray dir name can't inflate the next slug.
+            const suffix = entry.name.slice(prefix.length);
+            if (!DECIMAL_SUFFIX_RE.test(suffix))
+                continue;
+            const n = Number(suffix);
+            if (n > max)
+                max = n;
+        }
+    }
+    return `${stateId}.${max + 1}`;
+}
+const DECIMAL_SUFFIX_RE = /^(?:0|[1-9]\d*)$/;
+/**
+ * Returns the coordinator control socket path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/ctrl.sock
+ *
+ * The coordinator listens on this UDS to accept policy hot-swap
+ * requests from the orchestrator. The socket sits under the bundle's
+ * per-bundle runtime root (mode `0o700`) so filesystem permissions
+ * gate access.
+ *
+ * The directory slug is truncated to 12 chars of `bundleId` so the
+ * assembled path fits under macOS `sockaddr_un.sun_path` (104 chars).
+ * 16^12 ≈ 2.8e14 combinations — collisions in the host-wide
+ * `run/<slug>/` namespace are astronomical.
+ */
+export function getBundleControlSocketPath(bundleId) {
+    return resolve(getBundleRuntimeRoot(bundleId), 'ctrl.sock');
+}
+// ---------------------------------------------------------------------------
+// Per-bundle UDS endpoints (MCP proxy, MITM proxy, MITM control, coordinator)
+// ---------------------------------------------------------------------------
+//
+// Every UDS file owned by a bundle lives under a single per-bundle root
+// at `~/.ironcurtain/run/<bundleId[0:12]>/`. The directory is created
+// with `0o700` (see `docker-infrastructure.ts`), inheriting the same
+// security posture as the rest of the IronCurtain home. Worst-case
+// assembled path (with a 20-char username) is about 76 bytes —
+// comfortably under macOS 104 and Linux 108 `sockaddr_un.sun_path` caps.
+//
+// Three locations per bundle:
+//   run/<bid12>/ctrl.sock             → coordinator control socket
+//   run/<bid12>/sockets/              → bind-mounted as /run/ironcurtain/
+//   run/<bid12>/host/                 → host-local only (MITM control)
+// The `sockets/` vs `host/` split keeps the bind-mounted endpoints
+// separate from host-only endpoints so `isEndpointAllowed` is not the
+// only thing standing between the container and the MITM control API.
+/**
+ * Returns the per-bundle runtime root directory:
+ *   {home}/run/{bundleId[0:12]}/
+ *
+ * Holds the coordinator control socket plus two subdirectories
+ * (`sockets/` and `host/`) so the bind-mounted UDS files can be
+ * co-located without exposing host-only sockets to the container.
+ */
+export function getBundleRuntimeRoot(bundleId) {
+    assertPathSafeSlug('bundle ID', bundleId);
+    return resolve(getIronCurtainHome(), 'run', toBundleSlug(bundleId));
+}
+/**
+ * Returns the per-bundle container-visible sockets directory:
+ *   {home}/run/{bundleId[0:12]}/sockets/
+ *
+ * Two UDS files live here:
+ *  - `proxy.sock`      (Code Mode proxy — bind-mounted into container)
+ *  - `mitm-proxy.sock` (MITM proxy      — bind-mounted into container)
+ *
+ * This directory is what `prepareDockerInfrastructure()` bind-mounts as
+ * `/run/ironcurtain/` inside the container (read-write). Only these two
+ * socket files live here — no audit logs, escalation files, or other
+ * session artifacts.
+ */
+export function getBundleSocketsDir(bundleId) {
+    return resolve(getBundleRuntimeRoot(bundleId), 'sockets');
+}
+/**
+ * Returns the per-bundle host-only directory:
+ *   {home}/run/{bundleId[0:12]}/host/
+ *
+ * Holds UDS files that must NOT be visible to the container
+ * (currently just the MITM control socket).
+ */
+export function getBundleHostOnlyDir(bundleId) {
+    return resolve(getBundleRuntimeRoot(bundleId), 'host');
+}
+/**
+ * Code Mode proxy UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/sockets/proxy.sock
+ *
+ * Bound by the host-side Code Mode proxy; reachable inside the
+ * container as `/run/ironcurtain/proxy.sock` via the bind mount on
+ * `getBundleSocketsDir()`.
+ */
+export function getBundleProxySocketPath(bundleId) {
+    return resolve(getBundleSocketsDir(bundleId), 'proxy.sock');
+}
+/**
+ * MITM proxy UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/sockets/mitm-proxy.sock
+ *
+ * Bound by the host-side MITM proxy; reachable inside the container as
+ * `/run/ironcurtain/mitm-proxy.sock` via the bind mount on
+ * `getBundleSocketsDir()`.
+ */
+export function getBundleMitmProxySocketPath(bundleId) {
+    return resolve(getBundleSocketsDir(bundleId), 'mitm-proxy.sock');
+}
+/**
+ * MITM control UDS path for a bundle:
+ *   {home}/run/{bundleId[0:12]}/host/mitm-control.sock
+ *
+ * Host-local only — lives under `host/` rather than `sockets/` so the
+ * bind mount that exposes `sockets/` at `/run/ironcurtain/` does not
+ * expose this socket to the container.
+ */
+export function getBundleMitmControlSocketPath(bundleId) {
+    return resolve(getBundleHostOnlyDir(bundleId), 'mitm-control.sock');
+}
 //# sourceMappingURL=paths.js.map