tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/src/lib/resolved-config.ts

@@ -0,0 +1,425 @@
+import {
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { WorkspaceConfigV1SchemaZ, type WorkspaceConfigV1 } from "@tmux-ide/contracts";
+import type { IdeConfig } from "../types.ts";
+import {
+  loadWorkspaceConfig,
+  WorkspaceConfigLoadError,
+  type LoadedWorkspaceConfig,
+  type LoadWorkspaceConfigOptions,
+} from "./workspace-config-loader.ts";
+import { ConfigError, IdeError } from "./errors.ts";
+import {
+  resolveProject,
+  type ProjectResolution,
+  type ResolveProjectOptions,
+} from "./project-resolver.ts";
+import {
+  hasLegacyConfigAt,
+  legacyConfigPath,
+  readLegacyConfigAt,
+  readLegacyConfigFile,
+} from "./legacy-config-adapter.ts";
+import {
+  convertLegacyConfigToWorkspace,
+  workspaceConfigToLegacyProjection,
+  workspaceConfigToYaml,
+  type LegacyMigrationDiagnostic,
+} from "./legacy-config-migration.ts";
+
+export type ResolvedConfigKind = "workspace" | "legacy" | "none";
+
+export class WorkspaceConfigWriteError extends IdeError {
+  readonly path: string;
+
+  constructor(message: string, code: string, path: string, cause?: unknown) {
+    super(message, {
+      code,
+      exitCode: 1,
+      cause:
+        cause instanceof Error ? cause : cause === undefined ? undefined : new Error(String(cause)),
+    });
+    this.name = "WorkspaceConfigWriteError";
+    this.path = path;
+  }
+}
+
+export class UnsupportedLegacyConfigMutationError extends IdeError {
+  constructor(
+    readonly diagnostics: LegacyMigrationDiagnostic[],
+    message = `Legacy ide.yml contains unsupported fields that would be dropped by config mutation. Run \`tmux-ide migrate --dry-run\` and move to .tmux-ide/workspace.yml first.`,
+  ) {
+    super(message, { code: "LEGACY_CONFIG_MUTATION_UNSUPPORTED", exitCode: 1 });
+    this.name = "UnsupportedLegacyConfigMutationError";
+  }
+}
+
+export interface ResolvedConfig {
+  kind: ResolvedConfigKind;
+  path: string | null;
+  localPath: string | null;
+  provenance: "explicit" | "workspace" | "legacy" | "none";
+  resolution: ProjectResolution;
+  workspace: WorkspaceConfigV1 | null;
+  legacy: IdeConfig | null;
+  launchConfig: IdeConfig | null;
+  diagnostics: LegacyMigrationDiagnostic[];
+  migrationHint: string | null;
+}
+
+export interface ResolveConfigOptions extends LoadWorkspaceConfigOptions {
+  resolveOptions?: ResolveProjectOptions;
+}
+
+function loadedWorkspaceToResolved(loaded: LoadedWorkspaceConfig): ResolvedConfig {
+  const launchConfig = workspaceConfigToLegacyProjection(loaded.config);
+  return {
+    kind: "workspace",
+    path: loaded.source.basePath,
+    localPath: loaded.source.localPath,
+    provenance: loaded.source.resolution.config.explicit ? "explicit" : "workspace",
+    resolution: loaded.source.resolution,
+    workspace: loaded.config,
+    legacy: null,
+    launchConfig,
+    diagnostics: [],
+    migrationHint: null,
+  };
+}
+
+function configReadError(message: string, cause: unknown): ConfigError {
+  return new ConfigError(message, "READ_ERROR", {
+    cause: cause instanceof Error ? cause : new Error(String(cause)),
+  });
+}
+
+function configInvalidError(message: string, cause: unknown): ConfigError {
+  return new ConfigError(message, "INVALID_CONFIG", {
+    cause: cause instanceof Error ? cause : new Error(String(cause)),
+  });
+}
+
+function mapWorkspaceLoadError(error: WorkspaceConfigLoadError): ConfigError {
+  if (error.code.endsWith("_READ_FAILED") || error.code === "RESOLUTION_FAILED") {
+    return configReadError(error.message, error);
+  }
+  return configInvalidError(error.message, error);
+}
+
+function readLegacyConfigForResolution(path: string): { config: IdeConfig; raw: string } {
+  try {
+    return readLegacyConfigFile(path);
+  } catch (cause) {
+    const name = (cause as Error).name;
+    if (name === "YAMLException") {
+      throw configInvalidError(
+        `Invalid legacy ide.yml YAML at ${path}: ${(cause as Error).message}. Run "tmux-ide validate" for details.`,
+        cause,
+      );
+    }
+    if (name === "ZodError") {
+      throw configInvalidError(
+        `Invalid legacy ide.yml at ${path}: ${(cause as Error).message}. Run "tmux-ide validate" for details.`,
+        cause,
+      );
+    }
+    throw configReadError(
+      `Cannot read legacy ide.yml at ${path}: ${(cause as Error).message}`,
+      cause,
+    );
+  }
+}
+
+export async function resolveConfig(
+  dir: string,
+  options: ResolveConfigOptions = {},
+): Promise<ResolvedConfig> {
+  const resolution = await resolveProject(dir, {
+    explicitConfigPath: options.explicitConfigPath ?? options.resolveOptions?.explicitConfigPath,
+    projectRootHint: options.resolveOptions?.projectRootHint,
+    io: options.resolverIo ?? options.resolveOptions?.io,
+  });
+
+  if (resolution.config.kind === "workspace") {
+    let loaded: LoadedWorkspaceConfig;
+    try {
+      loaded = await loadWorkspaceConfig(dir, {
+        explicitConfigPath: resolution.config.explicit ? resolution.config.path : null,
+        resolverIo: options.resolverIo ?? options.resolveOptions?.io,
+        io: options.io,
+      });
+    } catch (error) {
+      if (error instanceof WorkspaceConfigLoadError) throw mapWorkspaceLoadError(error);
+      throw error;
+    }
+    return loadedWorkspaceToResolved(loaded);
+  }
+
+  if (resolution.config.kind === "legacy") {
+    const { config: legacy } = readLegacyConfigForResolution(resolution.config.path);
+    const migration = convertLegacyConfigToWorkspace(legacy);
+    return {
+      kind: "legacy",
+      path: resolution.config.path,
+      localPath: null,
+      provenance: resolution.config.explicit ? "explicit" : "legacy",
+      resolution,
+      workspace: migration.workspace,
+      legacy,
+      launchConfig: legacy,
+      diagnostics: migration.diagnostics,
+      migrationHint:
+        "Legacy ide.yml is supported for compatibility. Run `tmux-ide migrate --dry-run` to preview .tmux-ide/workspace.yml.",
+    };
+  }
+
+  return {
+    kind: "none",
+    path: null,
+    localPath: null,
+    provenance: "none",
+    resolution,
+    workspace: null,
+    legacy: null,
+    launchConfig: null,
+    diagnostics: [],
+    migrationHint: null,
+  };
+}
+
+export function workspaceConfigPath(dir: string): string {
+  return resolve(dir, ".tmux-ide", "workspace.yml");
+}
+
+export function workspaceLocalConfigPath(dir: string): string {
+  return resolve(dir, ".tmux-ide", "workspace.local.yml");
+}
+
+export function writeWorkspaceConfig(dir: string, workspace: WorkspaceConfigV1): string {
+  const parsed = WorkspaceConfigV1SchemaZ.parse(workspace);
+  const configPath = workspaceConfigPath(dir);
+  const configDir = dirname(configPath);
+  const tempPath = join(
+    configDir,
+    `.workspace.yml.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+  );
+  try {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(tempPath, workspaceConfigToYaml(parsed), { encoding: "utf-8", flag: "wx" });
+    renameSync(tempPath, configPath);
+  } catch (cause) {
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // Preserve the original write/rename failure.
+    }
+    throw new WorkspaceConfigWriteError(
+      `Failed to write workspace config at ${configPath}`,
+      "WORKSPACE_WRITE_FAILED",
+      configPath,
+      cause,
+    );
+  }
+  return configPath;
+}
+
+export function createWorkspaceConfig(dir: string, workspace: WorkspaceConfigV1): string {
+  const parsed = WorkspaceConfigV1SchemaZ.parse(workspace);
+  const configPath = workspaceConfigPath(dir);
+  const configDir = dirname(configPath);
+  const tempPath = join(
+    configDir,
+    `.workspace.yml.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+  );
+  try {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(tempPath, workspaceConfigToYaml(parsed), { encoding: "utf-8", flag: "wx" });
+    linkSync(tempPath, configPath);
+    unlinkSync(tempPath);
+  } catch (cause) {
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // Preserve the original write/link failure.
+    }
+    if ((cause as NodeJS.ErrnoException | undefined)?.code === "EEXIST" && existsSync(configPath)) {
+      throw new WorkspaceConfigWriteError(
+        `Workspace config already exists at ${configPath}`,
+        "CONFIG_EXISTS",
+        configPath,
+        cause,
+      );
+    }
+    throw new WorkspaceConfigWriteError(
+      `Failed to create workspace config at ${configPath}`,
+      "WORKSPACE_WRITE_FAILED",
+      configPath,
+      cause,
+    );
+  }
+  return configPath;
+}
+
+function readWorkspaceBaseConfig(dir: string): WorkspaceConfigV1 | null {
+  const workspacePath = workspaceConfigPath(dir);
+  if (!existsSync(workspacePath)) return null;
+  return WorkspaceConfigV1SchemaZ.parse(yaml.load(readFileSync(workspacePath, "utf-8")));
+}
+
+const LAUNCH_CONFIG_KEYS = new Set([
+  "name",
+  "before",
+  "rows",
+  "theme",
+  "team",
+  "orchestrator",
+  "command_center",
+  "dashboard",
+  "auth",
+  "tunnel",
+  "hq",
+  "sidebar",
+]);
+const ROW_KEYS = new Set(["size", "panes"]);
+const PANE_KEYS = new Set([
+  "id",
+  "title",
+  "command",
+  "type",
+  "target",
+  "dir",
+  "size",
+  "focus",
+  "env",
+  "role",
+  "task",
+  "specialty",
+  "skill",
+]);
+
+function unsupportedOutputDiagnostics(config: IdeConfig): LegacyMigrationDiagnostic[] {
+  const diagnostics: LegacyMigrationDiagnostic[] = [];
+  for (const key of Object.keys(config as Record<string, unknown>)) {
+    if (!LAUNCH_CONFIG_KEYS.has(key)) {
+      diagnostics.push({
+        code: "UNSUPPORTED_UNKNOWN_FIELD",
+        path: key,
+        message: "unknown top-level config field cannot be represented in WorkspaceConfigV1",
+      });
+    }
+  }
+  config.rows?.forEach((row, rowIndex) => {
+    for (const key of Object.keys(row as Record<string, unknown>)) {
+      if (!ROW_KEYS.has(key)) {
+        diagnostics.push({
+          code: "UNSUPPORTED_UNKNOWN_FIELD",
+          path: `rows.${rowIndex}.${key}`,
+          message: "unknown row config field cannot be represented in WorkspaceConfigV1",
+        });
+      }
+    }
+    row.panes?.forEach((pane, paneIndex) => {
+      for (const key of Object.keys(pane as Record<string, unknown>)) {
+        if (!PANE_KEYS.has(key)) {
+          diagnostics.push({
+            code: "UNSUPPORTED_UNKNOWN_FIELD",
+            path: `rows.${rowIndex}.panes.${paneIndex}.${key}`,
+            message: "unknown pane config field cannot be represented in WorkspaceConfigV1",
+          });
+        }
+      }
+    });
+  });
+  return diagnostics;
+}
+
+export function writeLaunchProjectionConfig(dir: string, config: IdeConfig): string {
+  const converted = convertLegacyConfigToWorkspace(config);
+  const unsupportedOutput = unsupportedOutputDiagnostics(config);
+  const existing = readWorkspaceBaseConfig(dir);
+  if (!existing && hasLegacyConfig(dir)) {
+    const legacy = readLegacyConfigAt(dir).config;
+    const legacyDiagnostics = convertLegacyConfigToWorkspace(legacy).diagnostics;
+    if (legacyDiagnostics.length > 0) {
+      throw new UnsupportedLegacyConfigMutationError(legacyDiagnostics);
+    }
+  }
+  if (unsupportedOutput.length > 0 || converted.diagnostics.length > 0) {
+    throw new UnsupportedLegacyConfigMutationError(
+      [...unsupportedOutput, ...converted.diagnostics],
+      existing
+        ? "Config mutation introduced legacy-only fields that cannot be represented in WorkspaceConfigV1."
+        : "New workspace config contains legacy-only fields that cannot be represented in WorkspaceConfigV1.",
+    );
+  }
+  if (!existing) return writeWorkspaceConfig(dir, converted.workspace);
+
+  return writeWorkspaceConfig(dir, {
+    ...existing,
+    ...(converted.workspace.name === undefined
+      ? { name: undefined }
+      : { name: converted.workspace.name }),
+    ...(converted.workspace.before === undefined
+      ? { before: undefined }
+      : { before: converted.workspace.before }),
+    terminal: converted.workspace.terminal,
+  });
+}
+
+export function readConfigCompatSync(dir: string): { config: IdeConfig; configPath: string } {
+  const workspacePath = workspaceConfigPath(dir);
+  if (existsSync(workspacePath)) {
+    const parsed = WorkspaceConfigV1SchemaZ.parse(yaml.load(readFileSync(workspacePath, "utf-8")));
+    return { config: workspaceConfigToLegacyProjection(parsed), configPath: workspacePath };
+  }
+  const { config, configPath } = readLegacyConfigAtCompat(dir);
+  return { config, configPath };
+}
+
+export function getSessionNameCompatSync(dir: string): {
+  name: string;
+  source: "config" | "fallback";
+} {
+  try {
+    const { config } = readConfigCompatSync(dir);
+    return { name: config.name ?? basename(dir), source: config.name ? "config" : "fallback" };
+  } catch {
+    return { name: basename(dir), source: "fallback" };
+  }
+}
+
+export function hasWorkspaceConfig(dir: string): boolean {
+  return existsSync(workspaceConfigPath(dir));
+}
+
+export function hasLegacyConfig(dir: string): boolean {
+  return hasLegacyConfigAt(dir);
+}
+
+export function hasLaunchConfig(dir: string): boolean {
+  return hasWorkspaceConfig(dir) || hasLegacyConfig(dir);
+}
+
+export function canonicalConfigPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function readLegacyConfigAtCompat(dir: string): { config: IdeConfig; configPath: string } {
+  const configPath = legacyConfigPath(dir);
+  const { config } = readLegacyConfigFile(configPath);
+  return { config, configPath };
+}

package/packages/daemon/src/lib/runtime-namespace.ts

@@ -0,0 +1,186 @@
+/**
+ * One authority bundle for every piece of process-local tmux-ide state.
+ *
+ * Production intentionally defaults to the user's canonical state and tmux
+ * server. Tests, smoke runs and performance fixtures must opt into an
+ * isolated namespace. Keeping the guard here makes accidental canonical I/O
+ * impossible even when a new harness forgets one of the legacy env vars.
+ */
+import { homedir } from "node:os";
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { captureUnixSocketIdentity } from "./unix-socket-authority.ts";
+
+export const RUNTIME_MODE_ENV = "TMUX_IDE_RUNTIME_MODE";
+export const STATE_HOME_ENV = "TMUX_IDE_HOME";
+export const REGISTRY_DIR_ENV = "TMUX_IDE_REGISTRY_DIR";
+export const DAEMON_INFO_DIR_ENV = "TMUX_IDE_DAEMON_INFO_DIR";
+export const TMUX_SOCKET_NAME_ENV = "TMUX_IDE_TMUX_SOCKET_NAME";
+export const TMUX_SOCKET_PATH_ENV = "TMUX_IDE_TMUX_SOCKET_PATH";
+export const CLEANUP_TOKEN_ENV = "TMUX_IDE_CLEANUP_TOKEN";
+
+export type RuntimeMode = "production" | "test" | "smoke" | "testdrive" | "performance";
+
+export interface RuntimeNamespace {
+  readonly mode: RuntimeMode;
+  readonly stateHome: string;
+  readonly registryDir: string;
+  readonly daemonInfoDir: string;
+  readonly controlSocketPath: string;
+  readonly eventLogPath: string;
+  readonly tmuxSocket:
+    | { readonly kind: "name"; readonly name: string }
+    | { readonly kind: "path"; readonly path: string };
+  readonly cleanupToken: string | null;
+  readonly namespaceId: string;
+  readonly persistence: "durable" | "ephemeral";
+  readonly isolated: boolean;
+}
+
+export interface RuntimeNamespaceResolutionOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly userHome?: string;
+  readonly cwd?: string;
+}
+
+const ISOLATED_MODES = new Set<RuntimeMode>(["test", "smoke", "testdrive", "performance"]);
+const SAFE_SOCKET_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/u;
+const SAFE_CLEANUP_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{7,127}$/u;
+
+function nonEmpty(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const value = env[key]?.trim();
+  return value ? value : undefined;
+}
+
+function absolutePath(value: string, cwd: string, key: string): string {
+  const path = isAbsolute(value) ? value : resolve(cwd, value);
+  if (!isAbsolute(path)) throw new TypeError(`${key} must resolve to an absolute path`);
+  return path;
+}
+
+function pathIdentity(path: string): string {
+  let cursor = resolve(path);
+  const suffix: string[] = [];
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    suffix.unshift(basename(cursor));
+    cursor = parent;
+  }
+  if (existsSync(cursor) && lstatSync(cursor).isSocket()) {
+    return resolve(captureUnixSocketIdentity(cursor).path, ...suffix);
+  }
+  return resolve(existsSync(cursor) ? realpathSync(cursor) : cursor, ...suffix);
+}
+
+function isInsideOrEqual(path: string, parent: string): boolean {
+  const child = pathIdentity(path);
+  const root = pathIdentity(parent);
+  const offset = relative(root, child);
+  return offset === "" || (!offset.startsWith(`..${sep}`) && offset !== "..");
+}
+
+function runtimeMode(env: NodeJS.ProcessEnv): RuntimeMode {
+  const raw = nonEmpty(env, RUNTIME_MODE_ENV) ?? "production";
+  if (!["production", "test", "smoke", "testdrive", "performance"].includes(raw)) {
+    throw new TypeError(`${RUNTIME_MODE_ENV} has an unsupported value`);
+  }
+  return raw as RuntimeMode;
+}
+
+export function resolveRuntimeNamespace(
+  options: RuntimeNamespaceResolutionOptions = {},
+): RuntimeNamespace {
+  const env = options.env ?? process.env;
+  const userHome = options.userHome ?? homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const mode = runtimeMode(env);
+  const isolated = ISOLATED_MODES.has(mode);
+  const canonicalHome = join(userHome, ".tmux-ide");
+  const configuredHome = nonEmpty(env, STATE_HOME_ENV);
+
+  if (isolated && !configuredHome) {
+    throw new TypeError(`${mode} runtime requires an explicit ${STATE_HOME_ENV}`);
+  }
+
+  const stateHome = absolutePath(configuredHome ?? canonicalHome, cwd, STATE_HOME_ENV);
+  const registryDir = absolutePath(
+    nonEmpty(env, REGISTRY_DIR_ENV) ?? stateHome,
+    cwd,
+    REGISTRY_DIR_ENV,
+  );
+  const daemonInfoDir = absolutePath(
+    // Preserve the long-standing registry override as the compatibility
+    // authority for daemon publication when no dedicated directory is set.
+    // This also keeps an explicitly empty DAEMON_INFO_DIR equivalent to
+    // "unset" instead of silently escaping a caller's isolated registry.
+    nonEmpty(env, DAEMON_INFO_DIR_ENV) ?? registryDir,
+    cwd,
+    DAEMON_INFO_DIR_ENV,
+  );
+  const tmuxSocketName = nonEmpty(env, TMUX_SOCKET_NAME_ENV);
+  const tmuxSocketPath = nonEmpty(env, TMUX_SOCKET_PATH_ENV);
+  const cleanupToken = nonEmpty(env, CLEANUP_TOKEN_ENV) ?? null;
+
+  if (tmuxSocketName && tmuxSocketPath) {
+    throw new TypeError(
+      `configure only one of ${TMUX_SOCKET_NAME_ENV} and ${TMUX_SOCKET_PATH_ENV}`,
+    );
+  }
+  if (tmuxSocketName && !SAFE_SOCKET_NAME.test(tmuxSocketName)) {
+    throw new TypeError(`${TMUX_SOCKET_NAME_ENV} is invalid`);
+  }
+  const tmuxSocket = tmuxSocketPath
+    ? ({ kind: "path", path: absolutePath(tmuxSocketPath, cwd, TMUX_SOCKET_PATH_ENV) } as const)
+    : ({ kind: "name", name: tmuxSocketName ?? "default" } as const);
+  if (isolated && tmuxSocket.kind === "name" && tmuxSocket.name === "default") {
+    throw new TypeError(`${mode} runtime requires a non-default ${TMUX_SOCKET_NAME_ENV}`);
+  }
+  if (isolated && isInsideOrEqual(stateHome, canonicalHome)) {
+    throw new TypeError(`${mode} runtime cannot use the canonical tmux-ide state home`);
+  }
+  if (
+    isolated &&
+    (isInsideOrEqual(registryDir, canonicalHome) || isInsideOrEqual(daemonInfoDir, canonicalHome))
+  ) {
+    throw new TypeError(`${mode} runtime cannot use canonical registry or daemon state`);
+  }
+  if (isolated && tmuxSocket.kind === "path" && isInsideOrEqual(tmuxSocket.path, canonicalHome)) {
+    throw new TypeError(`${mode} runtime cannot use a tmux socket inside canonical state`);
+  }
+  if (isolated && cleanupToken === null) {
+    throw new TypeError(`${mode} runtime requires an explicit ${CLEANUP_TOKEN_ENV}`);
+  }
+  if (cleanupToken !== null && !SAFE_CLEANUP_TOKEN.test(cleanupToken)) {
+    throw new TypeError(`${CLEANUP_TOKEN_ENV} is invalid`);
+  }
+
+  return Object.freeze({
+    mode,
+    stateHome,
+    registryDir,
+    daemonInfoDir,
+    controlSocketPath: join(stateHome, "control.sock"),
+    eventLogPath: join(stateHome, "events.jsonl"),
+    tmuxSocket,
+    cleanupToken,
+    namespaceId: isolated ? cleanupToken! : "canonical",
+    persistence: isolated ? "ephemeral" : "durable",
+    isolated,
+  });
+}
+
+export function runtimeNamespaceEnvironment(
+  namespace: RuntimeNamespace,
+): Readonly<Record<string, string>> {
+  return Object.freeze({
+    [RUNTIME_MODE_ENV]: namespace.mode,
+    [STATE_HOME_ENV]: namespace.stateHome,
+    [REGISTRY_DIR_ENV]: namespace.registryDir,
+    [DAEMON_INFO_DIR_ENV]: namespace.daemonInfoDir,
+    ...(namespace.tmuxSocket.kind === "name"
+      ? { [TMUX_SOCKET_NAME_ENV]: namespace.tmuxSocket.name }
+      : { [TMUX_SOCKET_PATH_ENV]: namespace.tmuxSocket.path }),
+    ...(namespace.cleanupToken ? { [CLEANUP_TOKEN_ENV]: namespace.cleanupToken } : {}),
+  });
+}

package/packages/daemon/src/lib/semantic-resource-id.ts

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Mint the wire-safe product identity used to correlate a durable tmux stamp
+ * without publishing the raw stamp through application-shell resources.
+ */
+export function semanticResourceDigest(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 20);
+}
+
+export function semanticResourceId(namespace: string, value: string): string {
+  return `${namespace}.${semanticResourceDigest(value)}`;
+}
+
+export function terminalWindowResourceId(semanticWindowId: string): string {
+  return semanticResourceId("terminal-window", semanticWindowId);
+}

package/packages/daemon/src/lib/session-monitor.ts

@@ -12,6 +12,32 @@ interface MonitorPane {
   name?: string;
 }
 
+export function parseListeningPids(raw: string): Set<string> {
+  const pids = new Set<string>();
+  let currentPid: string | null = null;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("p")) {
+      currentPid = line.slice(1);
+    } else if (line.startsWith("n") && currentPid) {
+      const match = line.match(/:(\d+)$/);
+      if (match) {
+        const port = parseInt(match[1]!, 10);
+        if (port >= 1024 && port <= 20000) pids.add(currentPid);
+      }
+    }
+  }
+  return pids;
+}
+
+export function parseProcessTree(raw: string): Map<string, string> {
+  const tree = new Map<string, string>();
+  for (const line of raw.trim().split("\n")) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length === 2) tree.set(parts[0]!, parts[1]!);
+  }
+  return tree;
+}
+
 // --- Port detection (pure helpers) ---
 
 function getListeningPids(): Set<string> {
@@ -22,20 +48,7 @@ function getListeningPids(): Set<string> {
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 2000,
     });
-    const pids = new Set<string>();
-    let currentPid: string | null = null;
-    for (const line of raw.split("\n")) {
-      if (line.startsWith("p")) {
-        currentPid = line.slice(1);
-      } else if (line.startsWith("n") && currentPid) {
-        const match = line.match(/:(\d+)$/);
-        if (match) {
-          const port = parseInt(match[1]!, 10);
-          if (port >= 1024 && port <= 20000) pids.add(currentPid);
-        }
-      }
-    }
-    return pids;
+    return parseListeningPids(raw);
   } catch {
     return new Set<string>();
   }
@@ -49,12 +62,7 @@ function getProcessTree(): Map<string, string> {
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 2000,
     });
-    const tree = new Map<string, string>();
-    for (const line of raw.trim().split("\n")) {
-      const parts = line.trim().split(/\s+/);
-      if (parts.length === 2) tree.set(parts[0]!, parts[1]!);
-    }
-    return tree;
+    return parseProcessTree(raw);
   } catch {
     return new Map<string, string>();
   }