create-snipara 2.1.0 → 2.2.0

package/dist/managed-config.d.ts

@@ -0,0 +1,19 @@
+interface ManagedNativeConfiguration {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/** Preserve source-bound context and unrelated connections; add only local capabilities. */
+declare function mergeManagedMcpServers<T>(existing: Record<string, T>, native: T, hosted: T, sourceBound?: boolean): Record<string, T>;
+interface ManagedCodexOptions {
+    file: string;
+    python: string;
+    server: ManagedNativeConfiguration;
+    env: Record<string, string | undefined>;
+    validateExisting: (server: ManagedNativeConfiguration) => boolean;
+    initialContent?: string;
+}
+declare function managedCodexSnippet(server: ManagedNativeConfiguration): string;
+declare function mergeManagedCodexConfig(options: ManagedCodexOptions): "created" | "appended" | "unchanged";
+
+export { type ManagedCodexOptions, type ManagedNativeConfiguration, managedCodexSnippet, mergeManagedCodexConfig, mergeManagedMcpServers };

package/dist/managed-config.js

@@ -0,0 +1,86 @@
+// src/managed-config.ts
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+import { TextDecoder } from "util";
+function mergeManagedMcpServers(existing, native, hosted, sourceBound = false) {
+  return { ...existing, ...sourceBound || existing["snipara-repository"] ? {} : { snipara: hosted }, "snipara-local": native };
+}
+var PARSE = "import json,sys\ntry:\n import tomllib\nexcept ImportError:\n import tomli as tomllib\nvalue=tomllib.loads(sys.stdin.read())\nservers=value.get('mcp_servers',{})\nif not isinstance(servers,dict): raise ValueError('invalid MCP table')\nprint(json.dumps(servers.get('snipara-local'),ensure_ascii=True))";
+function parse(content, options) {
+  try {
+    return JSON.parse(execFileSync(options.python, ["-I", "-B", "-c", PARSE], {
+      input: content,
+      env: options.env,
+      encoding: "utf8",
+      timeout: 5e3,
+      maxBuffer: 1e6,
+      stdio: ["pipe", "pipe", "pipe"]
+    }));
+  } catch {
+    throw new Error("Existing Codex configuration is malformed or its parser is unavailable; file preserved");
+  }
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function managedCodexSnippet(server) {
+  const env = server.env && Object.keys(server.env).length ? `
+env = { ${Object.entries(server.env).map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`).join(", ")} }` : "";
+  return `[mcp_servers.snipara-local]
+command = ${JSON.stringify(server.command)}
+args = ${JSON.stringify(server.args)}${env}
+`;
+}
+function mergeManagedCodexConfig(options) {
+  const directory = path.dirname(options.file);
+  if (!fs.existsSync(directory)) fs.mkdirSync(directory, { mode: 448 });
+  const parent = fs.lstatSync(directory);
+  if (!parent.isDirectory() || parent.isSymbolicLink() || parent.uid !== process.getuid?.() || parent.mode & 18)
+    throw new Error("Codex configuration directory is not safely owned; preserved");
+  let previous = null;
+  try {
+    const fd2 = fs.openSync(options.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+      const info = fs.fstatSync(fd2);
+      if (!info.isFile() || info.uid !== process.getuid?.() || info.nlink !== 1 || info.size > 1e6 || info.mode & 18)
+        throw new Error("Existing Codex configuration is not safely owned; preserved");
+      previous = fs.readFileSync(fd2);
+      if (previous.length > 1e6) throw new Error("Existing Codex configuration exceeds its bound; preserved");
+    } finally {
+      fs.closeSync(fd2);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const content = previous ? new TextDecoder("utf8", { fatal: true }).decode(previous) : options.initialContent ?? "";
+  const selected = parse(content, options);
+  if (selected !== null) {
+    if (!object(selected) || Object.keys(selected).some((key) => !["command", "args", "env"].includes(key)) || typeof selected.command !== "string" || !Array.isArray(selected.args) || !selected.args.every((value) => typeof value === "string") || selected.env !== void 0 && (!object(selected.env) || !Object.values(selected.env).every((value) => typeof value === "string")) || !options.validateExisting(selected))
+      throw new Error("Existing managed Codex connection conflicts with setup; file preserved and activation incomplete");
+    return "unchanged";
+  }
+  const result = content + (content ? content.endsWith("\n") ? "\n" : "\n\n" : "") + managedCodexSnippet(options.server);
+  parse(result, options);
+  if (previous && !fs.readFileSync(options.file).equals(previous))
+    throw new Error("Codex configuration changed during setup; file preserved");
+  if (!previous) {
+    fs.writeFileSync(options.file, result, { flag: "wx", mode: 384 });
+    return "created";
+  }
+  const fd = fs.openSync(options.file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_NOFOLLOW);
+  try {
+    const current = fs.fstatSync(fd), named = fs.lstatSync(options.file);
+    if (current.ino !== named.ino || current.dev !== named.dev || current.size !== previous.length || !current.isFile())
+      throw new Error("Codex configuration changed during setup; file preserved");
+    fs.writeFileSync(fd, result.slice(content.length), "utf8");
+  } finally {
+    fs.closeSync(fd);
+  }
+  return "appended";
+}
+export {
+  managedCodexSnippet,
+  mergeManagedCodexConfig,
+  mergeManagedMcpServers
+};

package/dist/managed-toolchain.d.ts

@@ -0,0 +1,38 @@
+import { ManagedToolchainManifest } from '@snipara/project-intelligence-contracts';
+
+declare const MANAGED_VERSIONS: Readonly<{
+    companion: string;
+    orchestrator: string;
+    sandbox: string;
+}>;
+declare function assertManagedRuntimeVersions(nodeVersion: string, pythonVersion: string): void;
+type Execution = {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    timeoutMs: number;
+};
+type ManagedInstallerRunner = (input: Execution) => Promise<{
+    stdout: string;
+}>;
+interface ManagedInstallerOptions {
+    home?: string;
+    runner?: ManagedInstallerRunner;
+    python?: string;
+    npm?: string;
+    repair?: boolean;
+}
+declare function readManagedManifest(file: string, options?: ManagedInstallerOptions): ManagedToolchainManifest;
+/** A retained bootstrap executes only Companion; its old peer commands are never selected. */
+declare function verifyRetainedCompanionBootstrap(command: string, active: ManagedToolchainManifest, options?: ManagedInstallerOptions): boolean;
+declare function managedToolchainStatus(options?: ManagedInstallerOptions): {
+    status: "absent" | "ready";
+    manifest: ManagedToolchainManifest | null;
+    manifestPath: string | null;
+};
+declare const runManagedInstaller: ManagedInstallerRunner;
+declare function prepareManagedToolchain(options?: ManagedInstallerOptions): Promise<ManagedToolchainManifest>;
+declare function rollbackManagedToolchain(options?: ManagedInstallerOptions): Promise<ManagedToolchainManifest>;
+
+export { MANAGED_VERSIONS, type ManagedInstallerOptions, type ManagedInstallerRunner, assertManagedRuntimeVersions, managedToolchainStatus, prepareManagedToolchain, readManagedManifest, rollbackManagedToolchain, runManagedInstaller, verifyRetainedCompanionBootstrap };

package/dist/managed-toolchain.js

@@ -0,0 +1,505 @@
+// src/managed-toolchain.ts
+import fs from "fs";
+import path from "path";
+import { homedir } from "os";
+import { createHash as createHash5, randomUUID as randomUUID2 } from "crypto";
+import { spawn } from "child_process";
+
+// ../project-intelligence-contracts/src/worker-profile.ts
+import { createHash } from "crypto";
+
+// ../project-intelligence-contracts/src/producer-loop.ts
+import { createHash as createHash2 } from "crypto";
+
+// ../project-intelligence-contracts/src/decision-request.ts
+import { createHash as createHash3 } from "crypto";
+
+// ../project-intelligence-contracts/src/why-capture-confidence-v1.json
+var why_capture_confidence_v1_default = {
+  version: "why-capture-confidence-v1",
+  base: 0.72,
+  decisionRationaleBonus: 0.1,
+  nonManualSourceBonus: 0.04,
+  maximum: 0.9,
+  decimalPlaces: 2,
+  validatedExecutionOutcomes: ["completed"],
+  vectors: [
+    {
+      candidateType: "CONTEXT",
+      hasDecision: false,
+      hasRationale: false,
+      sourceKind: "manual",
+      executionOutcome: "completed",
+      expected: 0.72
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "manual",
+      executionOutcome: "completed",
+      expected: 0.82
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "completed",
+      expected: 0.86
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "partial",
+      expected: 0.76
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "blocked",
+      expected: 0.76
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: true,
+      sourceKind: "phase_commit",
+      executionOutcome: "abandoned",
+      expected: 0.76
+    },
+    {
+      candidateType: "DECISION",
+      hasDecision: true,
+      hasRationale: false,
+      sourceKind: "final_commit",
+      executionOutcome: "completed",
+      expected: 0.76
+    }
+  ]
+};
+
+// ../project-intelligence-contracts/src/why-capture-confidence.ts
+var WHY_CAPTURE_CONFIDENCE_VERSION = why_capture_confidence_v1_default.version;
+var WHY_CAPTURE_CONFIDENCE_TEST_VECTORS = why_capture_confidence_v1_default.vectors;
+
+// ../project-intelligence-contracts/src/judgment-integrity.ts
+import { randomUUID } from "crypto";
+
+// ../project-intelligence-contracts/src/agent-memory-pilot.ts
+import { createHash as createHash4 } from "crypto";
+
+// ../project-intelligence-contracts/src/managed-toolchain.ts
+var MANAGED_TOOLCHAIN_VERSION = "snipara.toolchain.v1";
+var MANAGED_TOOLCHAIN_COMPONENTS = ["companion", "orchestrator", "sandbox"];
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var bounded = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max && !Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
+function canonicalAbsolute(value) {
+  return bounded(value, 4096) && value.startsWith("/") && value !== "/" && !value.endsWith("/") && !value.split("/").some((part, index) => index > 0 && ["", ".", ".."].includes(part));
+}
+function parseManagedToolchainManifest(value) {
+  if (!object(value) || value.schemaVersion !== MANAGED_TOOLCHAIN_VERSION || !bounded(value.bundleId, 128) || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value.bundleId) || !canonicalAbsolute(value.root) || !object(value.components) || !object(value.contracts) || value.contracts.taskReference !== 1 || value.contracts.validation !== 1 || !Array.isArray(value.capabilities) || value.capabilities.length > 32 || !value.capabilities.every((item) => bounded(item, 64) && /^[a-z][a-z0-9_-]*$/.test(item)) || new Set(value.capabilities).size !== value.capabilities.length) {
+    throw new Error("Unsupported or invalid managed toolchain manifest");
+  }
+  const root = value.root;
+  const components = {};
+  for (const name of MANAGED_TOOLCHAIN_COMPONENTS) {
+    const component = value.components[name];
+    if (!object(component) || !bounded(component.version, 64) || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(component.version) || !canonicalAbsolute(component.command) || !component.command.startsWith(root + "/") || typeof component.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(component.sha256)) {
+      throw new Error("Invalid managed component identity");
+    }
+    components[name] = { version: component.version, command: component.command, sha256: component.sha256 };
+  }
+  return {
+    schemaVersion: MANAGED_TOOLCHAIN_VERSION,
+    bundleId: value.bundleId,
+    root,
+    components,
+    contracts: { taskReference: 1, validation: 1 },
+    capabilities: [...value.capabilities]
+  };
+}
+
+// src/managed-versions.json
+var managed_versions_default = {
+  companion: "4.2.0",
+  orchestrator: "1.16.0",
+  sandbox: "3.0.0"
+};
+
+// src/managed-toolchain.ts
+var MANAGED_VERSIONS = Object.freeze(managed_versions_default);
+function assertManagedRuntimeVersions(nodeVersion, pythonVersion) {
+  const node = /^v?(\d+)\.\d+\.\d+(?:[-+].*)?$/.exec(nodeVersion);
+  const python = /^Python (\d+)\.(\d+)\.\d+(?:[a-z0-9.+-]*)?$/i.exec(pythonVersion.trim());
+  if (!node || Number(node[1]) < 18 || !python || Number(python[1]) !== 3 || Number(python[2]) < 10)
+    throw new Error("Local work requires existing Node.js 18+ and Python 3.10+. Update your system runtimes and retry; no operating-system runtime was installed");
+}
+var ManagedInstallerCleanupError = class extends Error {
+};
+var sha = (bytes2) => createHash5("sha256").update(bytes2).digest("hex");
+var uid = () => {
+  if (!process.getuid || process.platform === "win32") throw new Error("Managed local work requires macOS or Linux");
+  return process.getuid();
+};
+function exists(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function owned(file, directory, privateMode = false) {
+  const info = fs.lstatSync(file);
+  if (info.uid !== uid() || info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile()) || !directory && info.nlink !== 1 || (info.mode & 18) !== 0 || privateMode && (info.mode & 63) !== 0)
+    throw new Error("Managed installation path is not owned and protected");
+  return info;
+}
+function privateDirectory(directory) {
+  if (!exists(directory)) {
+    privateDirectory(path.dirname(directory));
+    fs.mkdirSync(directory, { mode: 448 });
+  }
+  owned(directory, true);
+}
+function location(options) {
+  const home = fs.realpathSync(options.home ?? homedir());
+  owned(home, true);
+  return path.join(home, ".local/share/snipara/toolchains");
+}
+function bytes(file, limit = 65536) {
+  owned(file, false);
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+  try {
+    const info = fs.fstatSync(fd);
+    if (!info.isFile() || info.uid !== uid() || info.size > limit || info.mode & 18)
+      throw new Error("Managed installation artifact is invalid");
+    const value = fs.readFileSync(fd);
+    if (value.length > limit) throw new Error("Managed installation artifact exceeds its bound");
+    return value;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function writePrivate(file, value) {
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n", { mode: 384, flag: "wx" });
+}
+function protectedCommand(root, command) {
+  const real = fs.realpathSync(command);
+  if (!real.startsWith(root + path.sep)) throw new Error("Managed command escapes its bundle");
+  for (let current = path.dirname(real); current !== root; current = path.dirname(current)) owned(current, true);
+  const info = owned(real, false);
+  if (!(info.mode & 73)) throw new Error("Managed command is not executable");
+  return real;
+}
+function readManagedManifest(file, options = {}) {
+  const base = location(options);
+  owned(base, true, true);
+  const link = fs.lstatSync(file);
+  let target = file;
+  if (link.isSymbolicLink()) {
+    if (link.uid !== uid()) throw new Error("Managed pointer has a foreign owner");
+    target = path.resolve(path.dirname(file), fs.readlinkSync(file));
+  }
+  if (path.basename(target) !== "toolchain.json" || path.dirname(path.dirname(target)) !== base)
+    throw new Error("Managed manifest is outside the private installation");
+  const root = path.dirname(target);
+  owned(root, true, true);
+  if (fs.realpathSync(root) !== root) throw new Error("Managed bundle cannot use linked directories");
+  owned(target, false, true);
+  const manifest = parseManagedToolchainManifest(JSON.parse(bytes(target).toString("utf8")));
+  if (manifest.root !== root || manifest.bundleId !== path.basename(root) || !manifest.capabilities.includes("validation") || !manifest.capabilities.includes("coordination"))
+    throw new Error("Managed bundle identity or required capabilities differ");
+  for (const component of Object.values(manifest.components)) {
+    if (protectedCommand(root, component.command) !== component.command || sha(bytes(component.command, 8e6)) !== component.sha256)
+      throw new Error("Managed command identity changed; prepare a replacement bundle");
+  }
+  return manifest;
+}
+function verifyRetainedCompanionBootstrap(command, active, options = {}) {
+  try {
+    const current = readManagedManifest(path.join(active.root, "toolchain.json"), options);
+    const base = location(options);
+    if (!path.isAbsolute(command) || !command.startsWith(base + path.sep)) return false;
+    const bundleId = command.slice(base.length + 1).split(path.sep)[0], root = path.join(base, bundleId);
+    owned(root, true, true);
+    if (fs.realpathSync(root) !== root || protectedCommand(root, command) !== command) return false;
+    const manifestFile = path.join(root, "toolchain.json");
+    owned(manifestFile, false, true);
+    const body = bytes(manifestFile), observedHash = sha(bytes(command, 8e6));
+    let previous;
+    try {
+      previous = parseManagedToolchainManifest(JSON.parse(body.toString("utf8")));
+    } catch {
+      return command === path.join(root, path.relative(current.root, current.components.companion.command)) && observedHash === current.components.companion.sha256;
+    }
+    return previous.root === root && previous.bundleId === bundleId && previous.components.companion.command === command && previous.components.companion.sha256 === observedHash;
+  } catch {
+    return false;
+  }
+}
+function managedToolchainStatus(options = {}) {
+  const active = path.join(location(options), "active.json");
+  if (!exists(active)) return { status: "absent", manifest: null, manifestPath: null };
+  return { status: "ready", manifest: readManagedManifest(active, options), manifestPath: fs.realpathSync(active) };
+}
+function program(name) {
+  for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+    if (!directory || !path.isAbsolute(directory)) continue;
+    const candidate = path.join(directory, name);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.statSync(candidate).isFile()) return fs.realpathSync(candidate);
+    } catch {
+    }
+  }
+  throw new Error(`${name} is required; no operating-system runtime will be installed`);
+}
+function cleanEnvironment(root) {
+  return {
+    PATH: [path.dirname(process.execPath), "/usr/local/bin", "/opt/homebrew/bin", "/usr/bin", "/bin"].join(path.delimiter),
+    HOME: path.join(root, "home"),
+    TMPDIR: path.join(root, "tmp"),
+    LANG: "C.UTF-8",
+    LC_ALL: "C.UTF-8",
+    PYTHONNOUSERSITE: "1",
+    PYTHONDONTWRITEBYTECODE: "1",
+    PIP_DISABLE_PIP_VERSION_CHECK: "1",
+    PIP_NO_INPUT: "1",
+    PIP_CONFIG_FILE: "/dev/null",
+    NPM_CONFIG_USERCONFIG: "/dev/null",
+    NPM_CONFIG_GLOBALCONFIG: "/dev/null",
+    NPM_CONFIG_IGNORE_SCRIPTS: "true",
+    NPM_CONFIG_AUDIT: "false",
+    NPM_CONFIG_FUND: "false",
+    NO_COLOR: "1"
+  };
+}
+var runManagedInstaller = async (input) => new Promise((resolve, reject) => {
+  const child = spawn(input.command, input.args, {
+    cwd: input.cwd,
+    env: input.env,
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: process.platform !== "win32"
+  });
+  let output = "", size = 0, stopped = false, stopReason = null;
+  let reapTimer;
+  const kill = () => {
+    try {
+      if (child.pid) process.kill(-child.pid, "SIGKILL");
+    } catch {
+      child.kill("SIGKILL");
+    }
+  };
+  const interrupted = () => stop("Managed preparation interrupted; the prior selection was preserved");
+  const exiting = () => kill();
+  const cleanup = () => {
+    clearTimeout(timer);
+    if (reapTimer) clearTimeout(reapTimer);
+    process.removeListener("SIGINT", interrupted);
+    process.removeListener("SIGTERM", interrupted);
+    process.removeListener("exit", exiting);
+  };
+  const stop = (message) => {
+    if (stopped || stopReason) return;
+    stopReason = message;
+    kill();
+    reapTimer = setTimeout(() => {
+      if (!stopped) {
+        stopped = true;
+        cleanup();
+        reject(new ManagedInstallerCleanupError("Managed installer cleanup could not be observed within its deadline; installation lock retained"));
+      }
+    }, 2e3);
+  };
+  const timer = setTimeout(() => stop("Managed preparation exceeded its bounded deadline"), input.timeoutMs);
+  process.on("SIGINT", interrupted);
+  process.on("SIGTERM", interrupted);
+  process.on("exit", exiting);
+  child.stdout.on("data", (value) => {
+    size += value.length;
+    if (size > 1e6) stop("Managed preparation output exceeded its bound");
+    else output += value.toString("utf8");
+  });
+  child.stderr.on("data", (value) => {
+    size += value.length;
+    if (size > 1e6) stop("Managed preparation output exceeded its bound");
+  });
+  child.on("error", () => {
+    cleanup();
+    if (!stopped) {
+      stopped = true;
+      reject(new Error("Managed preparation executable was unavailable"));
+    }
+  });
+  child.on("close", (code) => {
+    cleanup();
+    if (stopped) return;
+    stopped = true;
+    if (stopReason) reject(new Error(stopReason));
+    else if (code !== 0) reject(new Error("Managed preparation step failed; the previous active bundle was preserved"));
+    else resolve({ stdout: output });
+  });
+});
+function switchPointer(base, name, target) {
+  const current = path.join(base, name);
+  if (exists(current)) {
+    const stat = fs.lstatSync(current);
+    if (!stat.isSymbolicLink() || stat.uid !== uid()) throw new Error("Managed active pointer must be an owned symlink");
+  }
+  const temporary = path.join(base, `.pointer-${randomUUID2()}`);
+  fs.symlinkSync(target, temporary);
+  try {
+    fs.renameSync(temporary, current);
+  } finally {
+    if (exists(temporary)) fs.unlinkSync(temporary);
+  }
+}
+async function locked(options, action) {
+  const base = location(options);
+  privateDirectory(base);
+  owned(base, true, true);
+  const lock = path.join(base, ".install.lock");
+  const fd = fs.openSync(lock, "wx", 384);
+  let release = true;
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() }));
+    return await action(base);
+  } catch (error) {
+    if (error instanceof ManagedInstallerCleanupError) release = false;
+    throw error;
+  } finally {
+    fs.closeSync(fd);
+    if (release) fs.unlinkSync(lock);
+  }
+}
+async function prepareManagedToolchain(options = {}) {
+  if (Number(process.versions.node.split(".")[0]) < 18)
+    throw new Error("Local work requires Node.js 18+; update your system runtime and retry");
+  return locked(options, async (base) => {
+    const active = path.join(base, "active.json");
+    let prior = null;
+    let recovery = null;
+    const preserveInvalidSelection = () => {
+      const pointer = fs.lstatSync(active);
+      if (!pointer.isSymbolicLink() || pointer.uid !== uid()) throw new Error("Repair refuses a foreign or non-symlink active pointer");
+      const target = path.resolve(base, fs.readlinkSync(active));
+      if (path.basename(target) !== "toolchain.json" || path.dirname(path.dirname(target)) !== base)
+        throw new Error("Repair refuses an active pointer outside the owned installation");
+      const root2 = path.dirname(target);
+      owned(root2, true, true);
+      if (fs.realpathSync(root2) !== root2) throw new Error("Repair refuses a linked bundle directory");
+      let previousHash = null;
+      if (exists(target)) {
+        owned(target, false, true);
+        previousHash = sha(bytes(target));
+      }
+      return { priorManifestPath: target, priorManifestSha256: previousHash, priorSelection: "invalid_owned_bundle" };
+    };
+    if (exists(active)) {
+      try {
+        prior = readManagedManifest(active, options);
+      } catch (error) {
+        if (!options.repair) throw error;
+        recovery = preserveInvalidSelection();
+        prior = null;
+      }
+    }
+    const runner = options.runner ?? runManagedInstaller;
+    async function handshake(manifest) {
+      for (const [name, component] of Object.entries(manifest.components)) {
+        const command = name === "companion" ? process.execPath : component.command;
+        const args = name === "companion" ? [component.command, "--version"] : ["--version"];
+        const observed = await runner({ command, args, cwd: manifest.root, env: cleanEnvironment(manifest.root), timeoutMs: 15e3 });
+        if (!new RegExp(`^(?:snipara-${name}[ ,]+)?${component.version.replaceAll(".", "\\.")}$`, "i").test(observed.stdout.trim()))
+          throw new Error("Managed component version handshake did not match the pinned bundle");
+      }
+    }
+    const selectedPrior = prior;
+    if (selectedPrior && Object.entries(MANAGED_VERSIONS).every(([name, version]) => selectedPrior.components[name].version === version)) {
+      try {
+        await handshake(selectedPrior);
+        readManagedManifest(active, options);
+        return selectedPrior;
+      } catch (error) {
+        if (!options.repair) throw error;
+        recovery = preserveInvalidSelection();
+        prior = null;
+      }
+    }
+    const bundleId = `bundle-${MANAGED_VERSIONS.companion}-${MANAGED_VERSIONS.orchestrator}-${MANAGED_VERSIONS.sandbox}-${randomUUID2()}`;
+    const root = path.join(base, bundleId);
+    fs.mkdirSync(root, { mode: 448 });
+    for (const directory of ["home", "tmp"]) fs.mkdirSync(path.join(root, directory), { mode: 448 });
+    const env = cleanEnvironment(root);
+    const run = (command, args, timeoutMs = 3e5) => runner({ command, args, cwd: root, env, timeoutMs });
+    try {
+      if (recovery) writePrivate(path.join(root, "recovery.json"), { schemaVersion: "snipara.toolchain_recovery.v1", ...recovery, originalBundlePreserved: true });
+      const python = options.python ?? program("python3"), npm = options.npm ?? program("npm");
+      if (![python, npm].every((value) => path.isAbsolute(value))) throw new Error("Managed package managers need absolute executable paths");
+      const runtime = await run(python, ["--version"], 1e4);
+      assertManagedRuntimeVersions(process.versions.node, runtime.stdout);
+      const venv = path.join(root, "python"), prefix = path.join(root, "node");
+      await run(python, ["-I", "-m", "venv", venv], 6e4);
+      await run(path.join(venv, "bin/python"), ["-I", "-m", "pip", "install", "--no-input", "--disable-pip-version-check", "snipara-sandbox[validation,mcp]==" + MANAGED_VERSIONS.sandbox, "snipara-orchestrator==" + MANAGED_VERSIONS.orchestrator]);
+      await run(npm, ["install", "--prefix", prefix, "--ignore-scripts", "--no-audit", "--no-fund", "--save-exact", "snipara-companion@" + MANAGED_VERSIONS.companion]);
+      const manifest = {
+        schemaVersion: "snipara.toolchain.v1",
+        bundleId,
+        root,
+        components: {
+          companion: { version: MANAGED_VERSIONS.companion, command: fs.realpathSync(path.join(prefix, "node_modules/.bin/snipara-companion")), sha256: "" },
+          orchestrator: { version: MANAGED_VERSIONS.orchestrator, command: path.join(venv, "bin/snipara-orchestrator"), sha256: "" },
+          sandbox: { version: MANAGED_VERSIONS.sandbox, command: path.join(venv, "bin/snipara-sandbox"), sha256: "" }
+        },
+        contracts: { taskReference: 1, validation: 1 },
+        capabilities: ["validation", "coordination"]
+      };
+      for (const component of Object.values(manifest.components)) {
+        component.command = protectedCommand(root, component.command);
+        component.sha256 = sha(bytes(component.command, 8e6));
+      }
+      const manifestFile = path.join(root, "toolchain.json");
+      writePrivate(manifestFile, parseManagedToolchainManifest(manifest));
+      await handshake(manifest);
+      readManagedManifest(manifestFile, options);
+      writePrivate(path.join(root, "prepared.json"), { schemaVersion: "snipara.toolchain_preparation.v1", status: "prepared", manifestSha256: sha(bytes(manifestFile)), observedAt: (/* @__PURE__ */ new Date()).toISOString(), activationObserved: false });
+      if (prior) switchPointer(base, "previous.json", path.join(prior.root, "toolchain.json"));
+      switchPointer(base, "active.json", manifestFile);
+      return manifest;
+    } catch (error) {
+      writePrivate(path.join(root, "failed.json"), { schemaVersion: "snipara.toolchain_preparation.v1", status: "failed", observedAt: (/* @__PURE__ */ new Date()).toISOString(), reason: "preparation_or_identity_check_failed", priorActivePreserved: true });
+      throw error;
+    }
+  });
+}
+async function rollbackManagedToolchain(options = {}) {
+  return locked(options, async (base) => {
+    const previous = readManagedManifest(path.join(base, "previous.json"), options);
+    let active = null;
+    try {
+      active = readManagedManifest(path.join(base, "active.json"), options);
+    } catch {
+    }
+    switchPointer(base, "active.json", path.join(previous.root, "toolchain.json"));
+    if (active) switchPointer(base, "previous.json", path.join(active.root, "toolchain.json"));
+    return previous;
+  });
+}
+export {
+  MANAGED_VERSIONS,
+  assertManagedRuntimeVersions,
+  managedToolchainStatus,
+  prepareManagedToolchain,
+  readManagedManifest,
+  rollbackManagedToolchain,
+  runManagedInstaller,
+  verifyRetainedCompanionBootstrap
+};

package/dist/source-connection.d.ts

@@ -0,0 +1,12 @@
+interface ObservedSource {
+  root: string;
+  kind: "repository" | "local-repository" | "folder";
+  fingerprint: string;
+  repository?: string;
+}
+
+declare function detectSourceConnection(workspace: string, options?: {
+    python?: string;
+}): ObservedSource | null;
+
+export { detectSourceConnection };