jorgex-stack 1.2.1 → 1.2.2

package/README.md

@@ -1,6 +1,6 @@
 # JorgeX Stack
 
-Portable multi-agent harness: one configuration source — 15 agents, 17 skills, hooks, persistent memory ([Engram](https://github.com/Gentleman-Programming/engram)), MCPs, and system prompt — installable with one command in **Claude Code**, **Codex CLI**, and **OpenCode**.
+Portable multi-agent harness: one configuration source — 15 agents, 17 skills, hooks, persistent memory ([Engram](https://github.com/Gentleman-Programming/engram)), MCPs, and system prompt — installable with one command in **Claude Code**, **Codex CLI**, **OpenCode**, and **Pi**.
 
 > Inspired by [gentle-ai](https://github.com/Gentleman-Programming/gentle-ai), rebuilt for the JorgeX stack.
 
@@ -75,7 +75,7 @@ Flags:
   pnpm dlx jorgex-stack install --mode programmatic --subagent-concurrency serial --yes
   ```
 
-  This installs into all detected runtimes. To be explicit, add `--agents opencode,claude-code,codex` or a comma-separated subset. Always pass `--mode programmatic`; without `--mode`, `--yes` and non-TTY installs default to `human`.
+  This installs into all detected runtimes. To be explicit, add `--agents opencode,claude-code,codex,pi` or a comma-separated subset. Always pass `--mode programmatic`; without `--mode`, `--yes` and non-TTY installs default to `human`.
 
   OpenCode also requires an existing selection in `~/.jorgex-stack/model-map.json`; run `pnpm dlx jorgex-stack models --agents opencode` interactively once before a headless install.
 
@@ -95,6 +95,24 @@ Programmatic mode does **not** provide:
 - Any special stdout streaming guarantee — the runtime's normal output rules apply.
 - Telemetry, JSONL streams, or runtime token-budget enforcement.
 
+### Pi runtime
+
+Pi is package-managed rather than file-managed. Stack supports the exact tested pair **Pi 0.84.2 + `jorgex-pi@0.1.0`** and keeps Pi out of the adapter/component manifest and model map.
+
+```bash
+pnpm dlx jorgex-stack install --agents pi
+pnpm dlx jorgex-stack doctor --agents pi
+pnpm dlx jorgex-stack models --agents pi
+pnpm dlx jorgex-stack sync --agents pi
+pnpm dlx jorgex-stack uninstall --agents pi
+```
+
+Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. A scope-bound receipt under `~/.jorgex-stack/pi-receipt.json` records ownership only after the package runner reports a healthy install. Manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state fails closed and is never adopted or removed silently.
+
+Engram remains mandatory and user-owned. An existing binary is preserved. Interactive install may offer the existing native `brew`/`go`/release channel with a default-No confirmation; `--yes` and non-TTY installs fail with a remedy when Engram is absent. No Pi lifecycle operation updates or deletes the Engram database or memories. Under `--target-dir`, Stack accepts only `<target>/bin/engram`, isolates Pi/Home/XDG/AppData/temp/npm-cache paths inside the target, and never consults the host Engram or Pi configuration.
+
+`update --agents pi` only runs the Pi package lifecycle; it does not enter the global Stack updater. `update --check --agents pi` is a read-only Pi doctor. Uninstall runs package cleanup, backs up Pi's settings before removal, removes only the exact receipt-owned package after verifying absence, and preserves all companion/user state. Full behavior, failure states and troubleshooting are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
+
 ### Browser automation
 
 Browser automation is opt-in and explicit. The legacy `agent-browser` integration has been removed; rely on the two surfaces below.

package/dist/cli.js

@@ -3713,6 +3713,856 @@ function readPackageMetadata() {
   return { name, version };
 }
 
+// src/lib/pi-runtime.ts
+import os5 from "os";
+import path30 from "path";
+import fs22 from "fs";
+import { spawnSync } from "child_process";
+import { createHash } from "crypto";
+
+// src/lib/pi-package-lifecycle.ts
+import path29 from "path";
+var REQUIRED_CAPABILITIES = /* @__PURE__ */ new Set([
+  "foundation-contract-v1",
+  "runner-json-v1"
+]);
+function sameRecord(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function ownership(receipt) {
+  return { receipt, adapters: false, manifest: false, modelMap: false };
+}
+function blocked(input, reason) {
+  return {
+    kind: "blocked",
+    reason,
+    receiptPath: input.scope.receiptPath,
+    ownership: ownership(input.receiptJson !== null)
+  };
+}
+function packageSource(entry) {
+  if (typeof entry === "string") return entry;
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return null;
+  const source = Reflect.get(entry, "source");
+  return typeof source === "string" ? source : null;
+}
+function isJorgeXPiSource(source) {
+  return source.includes("jorgex-pi");
+}
+function parsePackageSources(settingsJson) {
+  try {
+    const parsed = JSON.parse(settingsJson);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const packages = Reflect.get(parsed, "packages");
+    if (!Array.isArray(packages)) return null;
+    const sources = packages.map(packageSource);
+    return sources.every((source) => source !== null) ? sources : null;
+  } catch {
+    return null;
+  }
+}
+function expectedReceipt(candidate, state, scope) {
+  return {
+    schemaVersion: 1,
+    state,
+    candidate: {
+      package: candidate.package,
+      tarball: candidate.tarball,
+      provenance: candidate.provenance
+    },
+    scope
+  };
+}
+function parseReceipt(receiptJson, candidate, scope) {
+  try {
+    const parsed = JSON.parse(receiptJson);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const state = Reflect.get(parsed, "state");
+    if (state !== "installing" && state !== "installed") return null;
+    const expected = expectedReceipt(candidate, state, scope);
+    return sameRecord(parsed, expected) ? expected : null;
+  } catch {
+    return null;
+  }
+}
+function candidateIsValid(candidate, observed) {
+  return candidate.package.name === "jorgex-pi" && candidate.package.source === `npm:${candidate.package.name}@${candidate.package.version}` && candidate.contract.schemaVersion === 1 && candidate.contract.runner.schemaVersion === 1 && candidate.contract.runner.bin === "jorgex-pi" && candidate.contract.runner.maxStdoutBytes === 65536 && candidate.contract.managedExternalWrites.length === 0 && [...REQUIRED_CAPABILITIES].every((capability) => candidate.contract.capabilities.includes(capability)) && sameRecord(candidate.tarball, observed);
+}
+function planPiPackageLifecycle(input) {
+  if (!candidateIsValid(input.candidate, input.observedTarball)) {
+    return blocked(input, "tarball-integrity");
+  }
+  if (!input.candidate.pi.testedVersions.includes(input.pi.version)) {
+    return blocked(input, "unsupported-pi-version");
+  }
+  if (input.engramBin === null) return blocked(input, "engram-missing");
+  const sources = parsePackageSources(input.pi.settingsJson);
+  if (sources === null) return blocked(input, "settings-corrupt");
+  const matchingSources = sources.filter(isJorgeXPiSource);
+  const exactSources = matchingSources.filter((source) => source === input.candidate.package.source);
+  if (exactSources.length > 1) return blocked(input, "duplicate-package");
+  if (matchingSources.some((source) => source !== input.candidate.package.source)) {
+    return blocked(input, "source-divergent");
+  }
+  let receipt = null;
+  if (input.receiptJson !== null) {
+    receipt = parseReceipt(input.receiptJson, input.candidate, {
+      kind: input.scope.kind,
+      codingAgentDir: path29.resolve(input.scope.codingAgentDir)
+    });
+    if (receipt === null) return blocked(input, "receipt-corrupt");
+    if (receipt.state === "installing") return blocked(input, "partial-state");
+    if (exactSources.length !== 1) return blocked(input, "partial-state");
+  }
+  if (exactSources.length === 1 && receipt === null) {
+    return {
+      kind: "manual-existing",
+      receiptPath: input.scope.receiptPath,
+      ownership: ownership(false)
+    };
+  }
+  if (exactSources.length === 1 && receipt !== null) {
+    return {
+      kind: "ready",
+      receiptPath: input.scope.receiptPath,
+      ownership: ownership(true)
+    };
+  }
+  return {
+    kind: "install",
+    receiptPath: input.scope.receiptPath,
+    invocation: {
+      executable: input.pi.executable,
+      args: ["install", input.candidate.package.source, "--no-approve"],
+      environment: input.scope.environment
+    },
+    receipt: expectedReceipt(input.candidate, "installing", {
+      kind: input.scope.kind,
+      codingAgentDir: path29.resolve(input.scope.codingAgentDir)
+    }),
+    ownership: ownership(true)
+  };
+}
+function parseRunnerRecord(stdout, stderr, command, candidate, packageRunner) {
+  if (stderr !== "" || !stdout.endsWith("\n") || Buffer.byteLength(stdout) > candidate.contract.runner.maxStdoutBytes) {
+    return null;
+  }
+  const body = stdout.slice(0, -1);
+  if (body === "" || body.includes("\n") || body.includes("\r")) return null;
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const record = parsed;
+    if (record.schemaVersion !== candidate.contract.runner.schemaVersion || record.command !== command || record.ok !== true || record.package === null || typeof record.package !== "object" || record.package.name !== candidate.package.name || record.package.version !== candidate.package.version || typeof record.package.root !== "string" || !path29.isAbsolute(record.package.root) || path29.resolve(packageRunner) !== path29.resolve(record.package.root, "bin", "jorgex-pi.mjs")) {
+      return null;
+    }
+    return record;
+  } catch {
+    return null;
+  }
+}
+function runPackageCommand(input, deps, command) {
+  const result = deps.run({
+    executable: input.packageRunner,
+    args: [command, "--json"],
+    environment: input.environment
+  });
+  if (result.exitCode !== 0) return { kind: "blocked", reason: "runner-unhealthy" };
+  return parseRunnerRecord(result.stdout, result.stderr, command, input.candidate, input.packageRunner) ?? { kind: "blocked", reason: "runner-output" };
+}
+function isBlockedResult(value) {
+  return "kind" in value;
+}
+function executePiPackageLifecycle(input, deps) {
+  if (input.plan.kind === "manual-existing") return { kind: "manual-existing" };
+  if (input.operation === "install") {
+    if (input.plan.kind !== "install" || input.plan.receipt === void 0 || input.plan.invocation === void 0) {
+      return { kind: "blocked", reason: "runner-unhealthy" };
+    }
+    deps.writeReceipt(input.plan.receipt);
+    const installed = deps.run(input.plan.invocation);
+    if (installed.exitCode !== 0 || installed.stderr !== "") {
+      return { kind: "blocked", reason: "pi-install-failed" };
+    }
+    const doctor = runPackageCommand(input, deps, "doctor");
+    if (isBlockedResult(doctor)) return doctor;
+    const doctorResult = doctor.result;
+    if (doctorResult === null || typeof doctorResult !== "object" || Reflect.get(doctorResult, "healthy") !== true) {
+      return { kind: "blocked", reason: "runner-unhealthy" };
+    }
+    const receipt = { ...input.plan.receipt, state: "installed" };
+    deps.writeReceipt(receipt);
+    return { kind: "installed", receipt };
+  }
+  if (input.plan.kind !== "ready") return { kind: "blocked", reason: "runner-unhealthy" };
+  const command = runPackageCommand(input, deps, input.operation);
+  if (isBlockedResult(command)) return command;
+  if (input.operation === "sync") {
+    const result = command.result;
+    if (result === null || typeof result !== "object" || Reflect.get(result, "changed") !== false) {
+      return { kind: "blocked", reason: "runner-unhealthy" };
+    }
+    return { kind: "synced", actions: [] };
+  }
+  const models = command.result;
+  if (models === null || typeof models !== "object" || Reflect.get(models, "mode") !== "inherit-session" || !sameRecord(Reflect.get(models, "tiers"), ["strong", "standard", "cheap"])) {
+    return { kind: "blocked", reason: "runner-unhealthy" };
+  }
+  return { kind: "models", models: { mode: "inherit-session", tiers: ["strong", "standard", "cheap"] } };
+}
+function readReceiptCandidate(receiptJson) {
+  try {
+    const parsed = JSON.parse(receiptJson);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const schemaVersion = Reflect.get(parsed, "schemaVersion");
+    const state = Reflect.get(parsed, "state");
+    const candidate = Reflect.get(parsed, "candidate");
+    if (schemaVersion !== 1 || state !== "installing" && state !== "installed" || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+      return null;
+    }
+    const packageValue = Reflect.get(candidate, "package");
+    const tarball = Reflect.get(candidate, "tarball");
+    const provenance = Reflect.get(candidate, "provenance");
+    const scope = Reflect.get(parsed, "scope");
+    if (packageValue === null || typeof packageValue !== "object" || tarball === null || typeof tarball !== "object" || provenance === null || typeof provenance !== "object" || scope === null || typeof scope !== "object" || Array.isArray(scope)) {
+      return null;
+    }
+    const source = Reflect.get(packageValue, "source");
+    const name = Reflect.get(packageValue, "name");
+    const version = Reflect.get(packageValue, "version");
+    if (name !== "jorgex-pi" || typeof version !== "string" || typeof source !== "string" || source !== `npm:jorgex-pi@${version}`) {
+      return null;
+    }
+    const scopeKind = Reflect.get(scope, "kind");
+    const codingAgentDir = Reflect.get(scope, "codingAgentDir");
+    if (scopeKind !== "real" && scopeKind !== "target-dir" || typeof codingAgentDir !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function validateOwnedOperationState(input) {
+  const sources = parsePackageSources(input.detected.settingsJson);
+  if (sources === null) return { kind: "blocked", reason: "settings-corrupt" };
+  const matchingSources = sources.filter(isJorgeXPiSource);
+  if (matchingSources.length > 1) return { kind: "blocked", reason: "duplicate-package" };
+  if (input.receiptJson === null) {
+    return { kind: "blocked", reason: matchingSources.length === 1 ? "manual-existing" : "source-divergent" };
+  }
+  const receipt = readReceiptCandidate(input.receiptJson);
+  if (receipt === null) return { kind: "blocked", reason: "receipt-corrupt" };
+  if (receipt.state !== "installed") return { kind: "blocked", reason: "partial-state" };
+  const accepted = input.registry.acceptedCandidates ?? [input.registry.candidate];
+  if (!accepted.some((candidate) => sameRecord(receipt.candidate, {
+    package: candidate.package,
+    tarball: candidate.tarball,
+    provenance: candidate.provenance
+  }))) {
+    return { kind: "blocked", reason: "receipt-untrusted" };
+  }
+  if (receipt.scope.kind !== (input.paths.targetDir ? "target-dir" : "real") || path29.resolve(receipt.scope.codingAgentDir) !== path29.resolve(input.paths.codingAgentDir)) {
+    return { kind: "blocked", reason: "source-divergent" };
+  }
+  const source = receipt.candidate.package.source;
+  if (matchingSources.length !== 1 || matchingSources[0] !== source) {
+    return { kind: "blocked", reason: "source-divergent" };
+  }
+  return { receipt, source };
+}
+function operationWasBlocked(value) {
+  return "kind" in value;
+}
+function runManagedRunner(input, deps, command) {
+  const result = deps.run({
+    executable: input.detected.packageRunner,
+    args: [command, "--json"],
+    environment: input.paths.environment
+  });
+  if (result.exitCode !== 0) return { kind: "blocked", reason: "runner-unhealthy" };
+  const parsed = parseRunnerRecord(
+    result.stdout,
+    result.stderr,
+    command,
+    input.registry.candidate,
+    input.detected.packageRunner
+  );
+  return parsed ?? { kind: "blocked", reason: "runner-output" };
+}
+function managedRunnerWasBlocked(value) {
+  return "kind" in value;
+}
+function runPiPackageManagedOperation(input, deps) {
+  if (input.engramBin === null && input.operation !== "uninstall") {
+    return {
+      kind: "blocked",
+      reason: "engram-missing",
+      remedy: "Instala Engram o configura un ENGRAM_BIN absoluto antes de reintentar."
+    };
+  }
+  const owned = validateOwnedOperationState(input);
+  if (operationWasBlocked(owned)) return owned;
+  if (input.operation === "doctor") {
+    if (!sameRecord(owned.receipt.candidate, {
+      package: input.registry.candidate.package,
+      tarball: input.registry.candidate.tarball,
+      provenance: input.registry.candidate.provenance
+    })) {
+      return { kind: "blocked", reason: "source-divergent" };
+    }
+    const doctor = runManagedRunner(input, deps, "doctor");
+    if (managedRunnerWasBlocked(doctor)) return doctor;
+    const result = doctor.result;
+    return result !== null && typeof result === "object" && Reflect.get(result, "healthy") === true ? { kind: "healthy" } : { kind: "blocked", reason: "runner-unhealthy" };
+  }
+  if (input.operation === "uninstall") {
+    if (!sameRecord(owned.receipt.candidate, {
+      package: input.registry.candidate.package,
+      tarball: input.registry.candidate.tarball,
+      provenance: input.registry.candidate.provenance
+    })) {
+      return { kind: "blocked", reason: "source-divergent" };
+    }
+    const cleanup = runManagedRunner(input, deps, "cleanup");
+    if (managedRunnerWasBlocked(cleanup)) return cleanup;
+    deps.backupSettings();
+    const removed = deps.run({
+      executable: input.detected.executable,
+      args: ["remove", owned.source, "--no-approve"],
+      environment: input.paths.environment
+    });
+    if (removed.exitCode !== 0 || removed.stderr !== "") return { kind: "blocked", reason: "remove-failed" };
+    if (!deps.isPackageAbsent()) return { kind: "blocked", reason: "absence-unverified" };
+    deps.deleteReceipt();
+    return { kind: "uninstalled" };
+  }
+  const nextSource = input.registry.candidate.package.source;
+  if (nextSource === owned.source) return { kind: "healthy" };
+  return {
+    kind: "blocked",
+    reason: "verified-update-required",
+    remedy: "A cross-version Pi update requires verified replacement and rollback tgz artifacts."
+  };
+}
+
+// src/lib/pi-runtime.ts
+var PI_RUNTIME_CANDIDATE = {
+  package: {
+    name: "jorgex-pi",
+    version: "0.1.0",
+    source: "npm:jorgex-pi@0.1.0"
+  },
+  provenance: {
+    commit: "791db79e33efd6661899995b5491e4dff5caa363"
+  },
+  tarball: {
+    bytes: 89066153,
+    sha256: "6243bf8e3a8dbe7be9103d7ca9b03e196c41ac9eef6578f47ea6d03655366feb",
+    sha512: "07590abec9e9594b001e28d75eb810259c4088f9f2f6d1d5b9fe456bb2d15a7259ff31ee225d5f1f59b27a1c337a1f1f8e3e57089656bf7bbad966e653110ddd"
+  },
+  pi: {
+    testedVersions: ["0.84.2"]
+  },
+  contract: {
+    schemaVersion: 1,
+    capabilities: [
+      "foundation-contract-v1",
+      "stack-snapshot-v1",
+      "runtime-agents-v1",
+      "permission-gated-tools-v1",
+      "structured-questions-v1",
+      "web-access-v1",
+      "goal-continuation-v1",
+      "mcp-adapter-v1",
+      "engram-runtime-tools-v1",
+      "runner-json-v1"
+    ],
+    runner: {
+      bin: "jorgex-pi",
+      commands: ["status", "doctor", "models", "sync", "cleanup"],
+      schemaVersion: 1,
+      maxStdoutBytes: 65536
+    },
+    managedExternalWrites: []
+  }
+};
+var PI_RUNTIME_REGISTRY = {
+  pi: {
+    id: "pi",
+    kind: "package-managed",
+    source: PI_RUNTIME_CANDIDATE.package.source,
+    tarball: PI_RUNTIME_CANDIDATE.tarball,
+    pi: PI_RUNTIME_CANDIDATE.pi,
+    candidate: PI_RUNTIME_CANDIDATE,
+    acceptedCandidates: [PI_RUNTIME_CANDIDATE]
+  }
+};
+async function resolvePiEngramRequirement(input, deps) {
+  if (input.targetDir !== void 0) {
+    const targetBin = deps.detectTarget(input.targetDir);
+    return targetBin === null ? {
+      kind: "blocked",
+      reason: "engram-missing-target",
+      remedy: "A\xF1ade el binario Engram dentro del target-dir antes de reintentar."
+    } : { kind: "existing", bin: targetBin, scope: "target-dir" };
+  }
+  const existing = deps.detectHost();
+  if (existing !== null) return { kind: "existing", bin: existing, scope: "host" };
+  if (input.yes || !input.interactive) {
+    return {
+      kind: "blocked",
+      reason: "engram-required",
+      remedy: "Instala Engram de forma interactiva o configura ENGRAM_BIN antes de reintentar."
+    };
+  }
+  const accepted = await deps.confirm({
+    message: "Engram es obligatorio para JorgeX Pi. \xBFInstalar ahora el binario mediante el canal nativo?",
+    initialValue: false
+  });
+  if (!accepted) return { kind: "offer", accepted: false };
+  const installed = await deps.installNative({ version: "1.20.0", channels: ["brew", "go", "url"] });
+  if (!installed) {
+    return {
+      kind: "blocked",
+      reason: "engram-install-failed",
+      remedy: "Instala Engram manualmente o configura ENGRAM_BIN antes de reintentar."
+    };
+  }
+  const detected = deps.detectHost();
+  return detected === null ? {
+    kind: "blocked",
+    reason: "engram-install-unverified",
+    remedy: "La instalaci\xF3n termin\xF3, pero Engram no qued\xF3 detectable; configura ENGRAM_BIN."
+  } : { kind: "existing", bin: detected, scope: "host" };
+}
+function flatCandidateReceipt(candidate, scope, state) {
+  const match = /^npm:jorgex-pi@([^\s]+)$/.exec(candidate.source);
+  const packageValue = candidate.package ?? {
+    name: "jorgex-pi",
+    version: match?.[1] ?? "0.1.0",
+    source: candidate.source
+  };
+  return {
+    schemaVersion: 1,
+    state,
+    candidate: {
+      package: packageValue,
+      tarball: { bytes: candidate.bytes, sha256: candidate.sha256, sha512: candidate.sha512 },
+      provenance: candidate.provenance ?? { commit: PI_RUNTIME_CANDIDATE.provenance.commit }
+    },
+    scope
+  };
+}
+function normalizeInstalledSource(settingsJson, alias, canonical) {
+  try {
+    const parsed = JSON.parse(settingsJson);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const packages = Reflect.get(parsed, "packages");
+    if (!Array.isArray(packages)) return null;
+    if (packages.filter((entry) => entry === alias).length !== 1 || packages.includes(canonical)) return null;
+    Reflect.set(parsed, "packages", packages.map((entry) => entry === alias ? canonical : entry));
+    return JSON.stringify(parsed);
+  } catch {
+    return null;
+  }
+}
+function healthyDoctor(stdout, stderr, packageRunner, candidate) {
+  if (stderr !== "" || !stdout.endsWith("\n") || stdout.slice(0, -1).includes("\n")) return false;
+  try {
+    const record = JSON.parse(stdout.slice(0, -1));
+    if (record === null || typeof record !== "object" || Array.isArray(record)) return false;
+    const packageValue = Reflect.get(record, "package");
+    const result = Reflect.get(record, "result");
+    return Reflect.get(record, "schemaVersion") === 1 && Reflect.get(record, "command") === "doctor" && Reflect.get(record, "ok") === true && packageValue !== null && typeof packageValue === "object" && Reflect.get(packageValue, "name") === "jorgex-pi" && Reflect.get(packageValue, "version") === (candidate.package?.version ?? /^npm:jorgex-pi@([^\s]+)$/.exec(candidate.source)?.[1]) && path30.resolve(packageRunner) === path30.resolve(String(Reflect.get(packageValue, "root")), "bin", "jorgex-pi.mjs") && result !== null && typeof result === "object" && Reflect.get(result, "healthy") === true;
+  } catch {
+    return false;
+  }
+}
+function installPiFromVerifiedTarball(input, deps) {
+  const paths = input.targetDir === void 0 ? userPaths(input.engramBin, input.piExecutable) : targetPaths(input.targetDir, input.engramBin, input.piExecutable);
+  const destination = input.targetDir === void 0 ? path30.join(dataDir(), "packages", "jorgex-pi-0.1.0.tgz") : path30.join(path30.resolve(input.targetDir), "downloads", "jorgex-pi-0.1.0.tgz");
+  const artifact = deps.download(destination);
+  if (artifact.bytes !== input.candidate.bytes || artifact.sha256 !== input.candidate.sha256 || artifact.sha512 !== input.candidate.sha512) {
+    return { kind: "blocked", reason: "tarball-integrity" };
+  }
+  deps.backupSettings();
+  const scope = {
+    kind: input.targetDir === void 0 ? "real" : "target-dir",
+    codingAgentDir: path30.resolve(paths.codingAgentDir)
+  };
+  const installing = flatCandidateReceipt(input.candidate, scope, "installing");
+  deps.writeReceiptAtomic(`${JSON.stringify(installing)}
+`);
+  const alias = `npm:jorgex-pi@file:${artifact.path}`;
+  const installed = deps.run({
+    executable: input.piExecutable,
+    args: ["install", alias, "--no-approve"],
+    environment: paths.environment
+  });
+  if (installed.exitCode !== 0 || installed.stderr !== "") return { kind: "blocked", reason: "pi-install-failed" };
+  const normalized = normalizeInstalledSource(deps.readSettings(), alias, input.candidate.source);
+  if (normalized === null) return { kind: "blocked", reason: "settings-corrupt" };
+  deps.rewriteSettings(normalized);
+  const doctor = deps.run({
+    executable: process.execPath,
+    args: [paths.packageRunner, "doctor", "--json"],
+    environment: paths.environment
+  });
+  if (doctor.exitCode !== 0 || !healthyDoctor(doctor.stdout, doctor.stderr, paths.packageRunner, input.candidate)) {
+    return { kind: "blocked", reason: "runner-unhealthy" };
+  }
+  const receipt = flatCandidateReceipt(input.candidate, scope, "installed");
+  deps.writeReceiptAtomic(`${JSON.stringify(receipt)}
+`);
+  return { kind: "installed", receipt };
+}
+function runtimePath(piExecutable) {
+  const entries = process.platform === "win32" ? [piExecutable === void 0 ? null : path30.dirname(piExecutable), path30.dirname(process.execPath), process.env.SystemRoot ? path30.join(process.env.SystemRoot, "System32") : null] : [piExecutable === void 0 ? null : path30.dirname(piExecutable), path30.dirname(process.execPath), "/usr/local/bin", "/usr/bin", "/bin"];
+  return [...new Set(entries.filter((entry) => entry !== null))].join(path30.delimiter);
+}
+function targetPaths(targetDir, engramBin, piExecutable) {
+  const root = path30.resolve(targetDir);
+  const codingAgentDir = path30.join(root, "pi-agent");
+  const home = path30.join(root, "home");
+  const temporary = path30.join(root, "tmp");
+  return {
+    codingAgentDir,
+    receiptPath: path30.join(root, "state", "pi-receipt.json"),
+    packageRunner: path30.join(codingAgentDir, "npm", "node_modules", "jorgex-pi", "bin", "jorgex-pi.mjs"),
+    environment: {
+      HOME: home,
+      USERPROFILE: home,
+      APPDATA: path30.join(root, "appdata"),
+      LOCALAPPDATA: path30.join(root, "localappdata"),
+      XDG_CONFIG_HOME: path30.join(root, "xdg-config"),
+      XDG_DATA_HOME: path30.join(root, "xdg-data"),
+      XDG_CACHE_HOME: path30.join(root, "xdg-cache"),
+      TEMP: temporary,
+      TMP: temporary,
+      TMPDIR: temporary,
+      npm_config_cache: path30.join(root, "npm-cache"),
+      NPM_CONFIG_IGNORE_SCRIPTS: "true",
+      NPM_CONFIG_UPDATE_NOTIFIER: "false",
+      PI_CODING_AGENT_DIR: codingAgentDir,
+      ...engramBin === null ? {} : { ENGRAM_BIN: engramBin },
+      PATH: runtimePath(piExecutable)
+    }
+  };
+}
+function userPaths(engramBin, piExecutable) {
+  const home = os5.homedir();
+  const codingAgentDir = process.env.PI_CODING_AGENT_DIR ?? path30.join(home, ".pi", "agent");
+  return {
+    codingAgentDir,
+    receiptPath: path30.join(dataDir(), "pi-receipt.json"),
+    packageRunner: path30.join(codingAgentDir, "npm", "node_modules", "jorgex-pi", "bin", "jorgex-pi.mjs"),
+    environment: {
+      HOME: home,
+      XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME ?? path30.join(home, ".config"),
+      XDG_CACHE_HOME: process.env.XDG_CACHE_HOME ?? path30.join(home, ".cache"),
+      TMPDIR: os5.tmpdir(),
+      NPM_CONFIG_IGNORE_SCRIPTS: "true",
+      NPM_CONFIG_UPDATE_NOTIFIER: "false",
+      PI_CODING_AGENT_DIR: codingAgentDir,
+      ...engramBin === null ? {} : { ENGRAM_BIN: engramBin },
+      PATH: runtimePath(piExecutable)
+    }
+  };
+}
+function persistReturnedReceipt(result, paths, deps) {
+  if (result.receipt !== void 0) {
+    deps.writeReceiptAtomic(paths.receiptPath, `${JSON.stringify(result.receipt)}
+`);
+  }
+}
+function runPiRuntime(input, deps) {
+  if (input.engramBin === null && input.operation !== "uninstall") {
+    return {
+      kind: "blocked",
+      reason: "engram-missing",
+      remedy: "Instala Engram o configura un ENGRAM_BIN absoluto antes de reintentar."
+    };
+  }
+  if (input.operation === "install" && input.verifiedArtifact === void 0) {
+    return { kind: "blocked", reason: "tarball-integrity" };
+  }
+  const paths = input.targetDir === void 0 ? userPaths(input.engramBin, input.detected.executable) : targetPaths(input.targetDir, input.engramBin, input.detected.executable);
+  const settingsJson = deps.readSettings(path30.join(paths.codingAgentDir, "settings.json"));
+  const receiptJson = deps.readReceipt(paths.receiptPath);
+  const lifecycleInput = {
+    candidate: PI_RUNTIME_CANDIDATE,
+    observedTarball: input.verifiedArtifact ?? PI_RUNTIME_CANDIDATE.tarball,
+    pi: {
+      executable: input.detected.executable,
+      version: input.detected.version,
+      packageRunner: paths.packageRunner,
+      settingsJson
+    },
+    engramBin: input.engramBin,
+    receiptJson,
+    scope: {
+      kind: input.targetDir === void 0 ? "real" : "target-dir",
+      codingAgentDir: paths.codingAgentDir,
+      receiptPath: paths.receiptPath,
+      environment: paths.environment
+    }
+  };
+  if (input.operation === "install" || input.operation === "sync" || input.operation === "models") {
+    const plan = deps.prepare(lifecycleInput);
+    const result2 = deps.execute({
+      operation: input.operation,
+      plan,
+      candidate: PI_RUNTIME_CANDIDATE,
+      packageRunner: paths.packageRunner,
+      environment: paths.environment
+    });
+    persistReturnedReceipt(result2, paths, deps);
+    return result2;
+  }
+  const result = deps.operate({
+    operation: input.operation,
+    interactive: false,
+    registry: PI_RUNTIME_REGISTRY.pi,
+    detected: {
+      executable: input.detected.executable,
+      packageRunner: paths.packageRunner,
+      settingsJson
+    },
+    engramBin: input.engramBin,
+    receiptJson,
+    paths: {
+      targetDir: input.targetDir !== void 0,
+      codingAgentDir: paths.codingAgentDir,
+      receiptPath: paths.receiptPath,
+      environment: paths.environment
+    },
+    removeArgs: ["remove", PI_RUNTIME_CANDIDATE.package.source, "--no-approve"]
+  });
+  persistReturnedReceipt(result, paths, deps);
+  return result;
+}
+function readJsonFile(file) {
+  return JSON.parse(fs22.readFileSync(file, "utf8"));
+}
+function packageVersionFromExecutable(executable) {
+  let current;
+  try {
+    current = path30.dirname(fs22.realpathSync(executable));
+  } catch {
+    return null;
+  }
+  for (let depth = 0; depth < 8; depth++) {
+    const manifests = [
+      path30.join(current, "package.json"),
+      path30.join(current, "node_modules", "@earendil-works", "pi-coding-agent", "package.json")
+    ];
+    for (const manifest of manifests) {
+      try {
+        const parsed = readJsonFile(manifest);
+        if (parsed !== null && typeof parsed === "object" && Reflect.get(parsed, "name") === "@earendil-works/pi-coding-agent" && typeof Reflect.get(parsed, "version") === "string") {
+          return Reflect.get(parsed, "version");
+        }
+      } catch {
+      }
+    }
+    const parent = path30.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+function detectPiRuntime() {
+  const executable = lookPath("pi");
+  const home = os5.homedir();
+  return {
+    id: "pi",
+    name: "Pi",
+    installed: executable !== null,
+    executable,
+    version: executable === null ? null : packageVersionFromExecutable(executable),
+    codingAgentDir: process.env.PI_CODING_AGENT_DIR ?? path30.join(home, ".pi", "agent")
+  };
+}
+function hasManagedPiRuntime(targetDir) {
+  const receipt = targetDir === void 0 ? path30.join(dataDir(), "pi-receipt.json") : path30.join(path30.resolve(targetDir), "state", "pi-receipt.json");
+  return fs22.statSync(receipt, { throwIfNoEntry: false })?.isFile() === true;
+}
+function resolvePiEngramBin(targetDir) {
+  if (targetDir === void 0) return detectEngram();
+  const candidate = path30.join(path30.resolve(targetDir), "bin", process.platform === "win32" ? "engram.exe" : "engram");
+  return fs22.statSync(candidate, { throwIfNoEntry: false })?.isFile() ? candidate : null;
+}
+function readOptional(file, fallback) {
+  try {
+    return fs22.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+function hashPiTarball(file) {
+  const descriptor = fs22.openSync(file, "r");
+  const sha256 = createHash("sha256");
+  const sha512 = createHash("sha512");
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  let bytes = 0;
+  try {
+    while (true) {
+      const read = fs22.readSync(descriptor, buffer, 0, buffer.length, null);
+      if (read === 0) break;
+      bytes += read;
+      const chunk = buffer.subarray(0, read);
+      sha256.update(chunk);
+      sha512.update(chunk);
+    }
+  } finally {
+    fs22.closeSync(descriptor);
+  }
+  return { path: file, bytes, sha256: sha256.digest("hex"), sha512: sha512.digest("hex") };
+}
+async function acquirePiTarball(destination) {
+  const existing = fs22.statSync(destination, { throwIfNoEntry: false });
+  if (existing?.isFile()) {
+    const observed = hashPiTarball(destination);
+    if (observed.bytes === PI_RUNTIME_CANDIDATE.tarball.bytes && observed.sha256 === PI_RUNTIME_CANDIDATE.tarball.sha256 && observed.sha512 === PI_RUNTIME_CANDIDATE.tarball.sha512) {
+      return observed;
+    }
+    fs22.rmSync(destination, { force: true });
+  }
+  fs22.mkdirSync(path30.dirname(destination), { recursive: true });
+  const partial = `${destination}.partial-${process.pid}`;
+  const response = await fetch("https://registry.npmjs.org/jorgex-pi/-/jorgex-pi-0.1.0.tgz", {
+    redirect: "error",
+    headers: { accept: "application/octet-stream" }
+  });
+  if (!response.ok || response.body === null) throw new Error(`No se pudo descargar jorgex-pi@0.1.0 (${response.status}).`);
+  const descriptor = fs22.openSync(partial, "wx", 384);
+  let bytes = 0;
+  try {
+    for await (const chunk of response.body) {
+      const buffer = Buffer.from(chunk);
+      bytes += buffer.length;
+      if (bytes > PI_RUNTIME_CANDIDATE.tarball.bytes) throw new Error("El tarball de jorgex-pi excede el tama\xF1o fijado.");
+      let offset = 0;
+      while (offset < buffer.length) offset += fs22.writeSync(descriptor, buffer, offset);
+    }
+  } catch (error) {
+    fs22.closeSync(descriptor);
+    fs22.rmSync(partial, { force: true });
+    throw error;
+  }
+  fs22.closeSync(descriptor);
+  fs22.renameSync(partial, destination);
+  return hashPiTarball(destination);
+}
+function runProcess(invocation) {
+  const planned = /\.mjs$/i.test(invocation.executable) ? { command: process.execPath, args: [invocation.executable, ...invocation.args] } : planDetectedBinCommand(invocation.executable, invocation.args);
+  if (planned === null) return { exitCode: 1, stdout: "", stderr: "unsafe executable" };
+  const result = spawnSync(planned.command, planned.args, {
+    encoding: "utf8",
+    env: invocation.environment,
+    shell: false,
+    timeout: 12e4,
+    maxBuffer: PI_RUNTIME_CANDIDATE.contract.runner.maxStdoutBytes + 1,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? (result.error?.message ?? "")
+  };
+}
+async function runPiRuntimeSystem(input) {
+  if (input.engramBin === null && input.operation !== "uninstall") return runPiRuntime(input, {
+    readSettings: () => {
+      throw new Error("unreachable");
+    },
+    readReceipt: () => {
+      throw new Error("unreachable");
+    },
+    writeReceiptAtomic: () => {
+      throw new Error("unreachable");
+    },
+    prepare: () => {
+      throw new Error("unreachable");
+    },
+    execute: () => {
+      throw new Error("unreachable");
+    },
+    operate: () => {
+      throw new Error("unreachable");
+    }
+  });
+  const paths = input.targetDir === void 0 ? userPaths(input.engramBin, input.detected.executable) : targetPaths(input.targetDir, input.engramBin, input.detected.executable);
+  if (input.operation === "install") {
+    if (input.engramBin === null) {
+      return {
+        kind: "blocked",
+        reason: "engram-required",
+        remedy: "Instala Engram o configura un ENGRAM_BIN absoluto antes de reintentar."
+      };
+    }
+    const destination = input.targetDir === void 0 ? path30.join(dataDir(), "packages", "jorgex-pi-0.1.0.tgz") : path30.join(path30.resolve(input.targetDir), "downloads", "jorgex-pi-0.1.0.tgz");
+    let artifact;
+    try {
+      artifact = await acquirePiTarball(destination);
+    } catch (error) {
+      return { kind: "blocked", reason: "tarball-download", remedy: error instanceof Error ? error.message : String(error) };
+    }
+    return installPiFromVerifiedTarball({
+      targetDir: input.targetDir,
+      piExecutable: input.detected.executable,
+      engramBin: input.engramBin,
+      candidate: {
+        source: PI_RUNTIME_CANDIDATE.package.source,
+        ...PI_RUNTIME_CANDIDATE.tarball,
+        package: PI_RUNTIME_CANDIDATE.package,
+        provenance: PI_RUNTIME_CANDIDATE.provenance
+      }
+    }, {
+      download: () => artifact,
+      backupSettings: () => createBackup(
+        [path30.join(paths.codingAgentDir, "settings.json")],
+        "pi-package-install",
+        input.targetDir === void 0 ? void 0 : path30.join(path30.resolve(input.targetDir), "backups")
+      ),
+      run: runProcess,
+      readSettings: () => readOptional(path30.join(paths.codingAgentDir, "settings.json"), '{"packages":[]}'),
+      rewriteSettings: (content) => writeText(path30.join(paths.codingAgentDir, "settings.json"), `${content}
+`),
+      writeReceiptAtomic: (content) => writeText(paths.receiptPath, content)
+    });
+  }
+  const packageRoot = path30.dirname(path30.dirname(paths.packageRunner));
+  const writeReceipt = (receipt) => {
+    writeText(paths.receiptPath, `${JSON.stringify(receipt, null, 2)}
+`);
+  };
+  const deps = {
+    readSettings: (file) => readOptional(file, '{"packages":[]}'),
+    readReceipt: (file) => readOptional(file, null),
+    writeReceiptAtomic: (file, content) => writeText(file, content),
+    prepare: (value) => planPiPackageLifecycle(value),
+    execute: (value) => executePiPackageLifecycle(
+      value,
+      { writeReceipt, run: runProcess }
+    ),
+    operate: (value) => runPiPackageManagedOperation(
+      value,
+      {
+        backupSettings: () => createBackup(
+          [path30.join(paths.codingAgentDir, "settings.json")],
+          "pi-package-uninstall",
+          input.targetDir === void 0 ? void 0 : path30.join(path30.resolve(input.targetDir), "backups")
+        ),
+        run: runProcess,
+        isPackageAbsent: () => !fs22.existsSync(packageRoot),
+        deleteReceipt: () => fs22.rmSync(paths.receiptPath, { force: true })
+      }
+    )
+  };
+  return runPiRuntime(input, deps);
+}
+
 // src/cli.ts
 var VERSION = readPackageVersion();
 var COMMANDS = ["install", "sync", "models", "update", "doctor", "restore", "uninstall"];
@@ -3911,19 +4761,71 @@ function parseCliArgs(argv) {
   if (flags.unknownFlags.length > 0) return { action: "unknown-flags", command, flags };
   return { action: "run", command, flags };
 }
-async function resolveRuntimes(flags) {
+function isFileManagedRuntime(runtime) {
+  return runtime !== "pi";
+}
+async function resolveRuntimes(flags, includeAvailablePi = false) {
   if (flags.agents.length > 0) return flags.agents;
-  const detected = Object.values(ADAPTERS).filter((a) => a.detect().installed);
+  const detected = Object.values(ADAPTERS).filter((adapter) => adapter.detect().installed).map((adapter) => ({ id: adapter.id, name: adapter.name }));
+  const pi = detectPiRuntime();
+  if (pi.installed && (includeAvailablePi || hasManagedPiRuntime(flags.targetDir))) {
+    detected.push({ id: "pi", name: "Pi" });
+  }
   if (detected.length === 0) return [];
-  if (flags.yes || !process.stdout.isTTY || flags.targetDir !== void 0) return detected.map((a) => a.id);
+  if (flags.yes || !process.stdout.isTTY || flags.targetDir !== void 0) return detected.map((runtime) => runtime.id);
   const choice = await p6.multiselect({
     message: "\xBFEn qu\xE9 runtimes? (detectados en esta m\xE1quina)",
-    options: detected.map((a) => ({ value: a.id, label: a.name })),
-    initialValues: detected.map((a) => a.id)
+    options: detected.map((runtime) => ({ value: runtime.id, label: runtime.name })),
+    initialValues: detected.map((runtime) => runtime.id)
   });
   if (p6.isCancel(choice)) return null;
   return choice;
 }
+async function runSelectedPi(operation, targetDir, yes = false) {
+  const detected = detectPiRuntime();
+  if (!detected.installed || detected.executable === null) {
+    console.error("Pi no detectado. Instala el runtime Pi antes de gestionar jorgex-pi.");
+    return 1;
+  }
+  if (detected.version === null) {
+    console.error("No se pudo verificar la versi\xF3n instalada de Pi sin ejecutarlo; revisa la instalaci\xF3n de Pi.");
+    return 1;
+  }
+  let engramBin = resolvePiEngramBin(targetDir);
+  if (operation === "install" && engramBin === null) {
+    const requirement = await resolvePiEngramRequirement({
+      targetDir,
+      interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+      yes
+    }, {
+      detectHost: () => resolvePiEngramBin(),
+      detectTarget: (root) => resolvePiEngramBin(root),
+      confirm: async ({ message, initialValue }) => {
+        const answer = await p6.confirm({ message, initialValue });
+        return !p6.isCancel(answer) && answer;
+      },
+      installNative: async ({ version }) => updateEngram("Gentleman-Programming/engram", version)
+    });
+    if (requirement.kind !== "existing") {
+      console.error(requirement.kind === "offer" ? "Pi: instalaci\xF3n cancelada; Engram sigue siendo obligatorio." : `Pi: ${requirement.reason}. ${requirement.remedy}`);
+      return 1;
+    }
+    engramBin = requirement.bin;
+  }
+  const result = await runPiRuntimeSystem({
+    operation,
+    targetDir,
+    detected: { executable: detected.executable, version: detected.version },
+    engramBin
+  });
+  if (result.kind === "blocked") {
+    console.error(`Pi: ${result.reason ?? "operaci\xF3n bloqueada"}${result.remedy ? `. ${result.remedy}` : ""}`);
+    return 1;
+  }
+  if (result.kind === "models" && result.models !== void 0) console.log(JSON.stringify(result.models));
+  else p6.log.success(`Pi: ${result.kind}.`);
+  return 0;
+}
 function printHelp() {
   console.log(`jorgex-stack v${VERSION}
 
@@ -3941,7 +4843,7 @@ Comandos:
               desregistrarlo exige --remove-engram o el s\xED expl\xEDcito
 
 Opciones:
-  --agents, -a opencode,claude-code,codex   Runtimes destino (default: detectados)
+  --agents, -a opencode,claude-code,codex,pi   Runtimes destino (default: detectados)
   --mode human|programmatic   Modo de instalaci\xF3n (default: preferencia guardada o human)
   --subagent-concurrency serial|parallel  Concurrencia de subagentes en modo programmatic
   --target-dir <dir>    Dir alternativo (pruebas de paridad; requiere 1 runtime)
@@ -3988,34 +4890,42 @@ Flags disponibles: jorgex-stack --help`
   switch (command) {
     case "install":
     case "sync": {
-      const mode = await resolveInstallMode(flags);
-      if (mode === null) return;
-      const runtimes = await resolveRuntimes(flags);
+      const runtimes = await resolveRuntimes(flags, command === "install");
       if (runtimes === null) return;
       if (runtimes.length === 0) {
-        console.error("Ning\xFAn runtime detectado (opencode, claude-code, codex).");
+        console.error("Ning\xFAn runtime detectado (opencode, claude-code, codex, pi).");
         process.exitCode = 1;
         return;
       }
-      const devtoolsMcpSelection = await resolveDevtoolsMcpSelection(command, flags, runtimes);
-      if (devtoolsMcpSelection === null) return;
-      const playwrightToolConsent = await resolvePlaywrightToolConsent(command, flags);
-      if (playwrightToolConsent === null) return;
-      const hasOpenCodeModels = await ensureOpenCodeModelsForInstall(command, flags, runtimes);
-      if (!hasOpenCodeModels) {
-        process.exitCode = 1;
-        return;
+      const fileRuntimes = runtimes.filter(isFileManagedRuntime);
+      let exitCode = 0;
+      if (fileRuntimes.length > 0) {
+        const mode = await resolveInstallMode(flags);
+        if (mode === null) return;
+        const devtoolsMcpSelection = await resolveDevtoolsMcpSelection(command, flags, fileRuntimes);
+        if (devtoolsMcpSelection === null) return;
+        const playwrightToolConsent = await resolvePlaywrightToolConsent(command, flags);
+        if (playwrightToolConsent === null) return;
+        const hasOpenCodeModels = await ensureOpenCodeModelsForInstall(command, flags, fileRuntimes);
+        if (!hasOpenCodeModels) {
+          process.exitCode = 1;
+          return;
+        }
+        exitCode = await runInstall({
+          runtimes: fileRuntimes,
+          targetDir: flags.targetDir,
+          dryRun: flags.dryRun,
+          yes: flags.yes,
+          mode,
+          playwrightToolConsent,
+          devtoolsMcpSelection
+        });
       }
-      const installExitCode = await runInstall({
-        runtimes,
-        targetDir: flags.targetDir,
-        dryRun: flags.dryRun,
-        yes: flags.yes,
-        mode,
-        playwrightToolConsent,
-        devtoolsMcpSelection
-      });
-      process.exitCode = installExitCode;
+      if (runtimes.includes("pi")) {
+        if (flags.dryRun) p6.log.info(`Pi: ${command} previsto; dry-run no ejecuta subprocess ni escribe receipt.`);
+        else exitCode = Math.max(exitCode, await runSelectedPi(command, flags.targetDir, flags.yes));
+      }
+      process.exitCode = exitCode;
       return;
     }
     case "uninstall": {
@@ -4026,41 +4936,56 @@ Flags disponibles: jorgex-stack --help`
         process.exitCode = 1;
         return;
       }
-      process.exitCode = await runUninstall({
-        runtimes,
+      const fileRuntimes = runtimes.filter(isFileManagedRuntime);
+      let exitCode = fileRuntimes.length > 0 || flags.removePlaywright ? await runUninstall({
+        runtimes: fileRuntimes,
         targetDir: flags.targetDir,
         dryRun: flags.dryRun,
         yes: flags.yes,
         removeEngram: flags.removeEngram,
         removePlaywright: flags.removePlaywright
-      });
+      }) : 0;
+      if (runtimes.includes("pi")) {
+        if (flags.dryRun) p6.log.info("Pi: uninstall previsto; dry-run conserva paquete y receipt.");
+        else exitCode = Math.max(exitCode, await runSelectedPi("uninstall", flags.targetDir));
+      }
+      process.exitCode = exitCode;
       return;
     }
     case "doctor": {
-      process.exitCode = await runDoctor();
+      const fileDoctorSelected = flags.agents.length === 0 || flags.agents.some(isFileManagedRuntime);
+      let exitCode = fileDoctorSelected ? await runDoctor() : 0;
+      const piSelected = flags.agents.includes("pi") || flags.agents.length === 0 && detectPiRuntime().installed && hasManagedPiRuntime(flags.targetDir);
+      if (piSelected) exitCode = Math.max(exitCode, await runSelectedPi("doctor", flags.targetDir));
+      process.exitCode = exitCode;
       return;
     }
     case "update": {
-      if (flags.check) {
-        process.exitCode = await runUpdateCheck(VERSION, flags.targetDir === void 0);
-        return;
-      }
-      if (flags.dryRun) {
-        process.exitCode = await runUpdateCheck(VERSION, flags.targetDir === void 0);
+      if (flags.check || flags.dryRun) {
+        const piExplicit = flags.agents.includes("pi");
+        const fileRuntimeExplicit = flags.agents.some(isFileManagedRuntime);
+        let exitCode = flags.agents.length === 0 || fileRuntimeExplicit ? await runUpdateCheck(VERSION, flags.targetDir === void 0) : 0;
+        if (piExplicit) exitCode = Math.max(exitCode, await runSelectedPi("doctor", flags.targetDir));
+        process.exitCode = exitCode;
         return;
       }
       const runtimes = await resolveRuntimes(flags);
       if (runtimes === null) return;
+      const fileRuntimes = runtimes.filter(isFileManagedRuntime);
+      if (fileRuntimes.length === 0 && runtimes.includes("pi")) {
+        process.exitCode = await runSelectedPi("update", flags.targetDir);
+        return;
+      }
       const preferenceFile = installModePreferenceFile();
       const explicitMode = flags.mode !== void 0 || flags.subagentConcurrency !== void 0;
       const hasSavedMode = hasInstallModePreference(preferenceFile);
       const canResolveMode = flags.targetDir !== void 0 || explicitMode || hasSavedMode;
-      const mode = runtimes.length > 0 && canResolveMode ? await resolveInstallMode(flags, false) : DEFAULT_INSTALL_MODE_PREFERENCE;
+      const mode = fileRuntimes.length > 0 && canResolveMode ? await resolveInstallMode(flags, false) : DEFAULT_INSTALL_MODE_PREFERENCE;
       if (mode === null) return;
-      const canSync = runtimes.length === 0 || canResolveMode;
-      if (runtimes.length > 0 && canSync) {
+      const canSync = fileRuntimes.length === 0 || canResolveMode;
+      if (fileRuntimes.length > 0 && canSync) {
         const code = await runInstall({
-          runtimes,
+          runtimes: fileRuntimes,
           targetDir: flags.targetDir,
           dryRun: flags.dryRun,
           yes: true,
@@ -4070,7 +4995,7 @@ Flags disponibles: jorgex-stack --help`
           process.exitCode = code;
           return;
         }
-      } else if (runtimes.length > 0) {
+      } else if (fileRuntimes.length > 0) {
         console.error("No hay modo guardado; se omite el sync previo y se contin\xFAa con update. Usa --mode expl\xEDcito si quieres sincronizar.");
       }
       const result = await runInteractiveUpdate(
@@ -4080,13 +5005,16 @@ Flags disponibles: jorgex-stack --help`
         flags.targetDir === void 0
       );
       process.exitCode = result.exitCode;
-      if (result.syncRequired && runtimes.length > 0 && (result.exitCode !== 0 || !canSync)) {
+      if (result.exitCode === 0 && runtimes.includes("pi")) {
+        process.exitCode = Math.max(process.exitCode, await runSelectedPi("update", flags.targetDir));
+      }
+      if (result.syncRequired && fileRuntimes.length > 0 && (result.exitCode !== 0 || !canSync)) {
         p6.log.warn("Skills/stack actualizados, pero el sync con los runtimes sigue pendiente. Ejecuta jorgex-stack sync --mode human|programmatic.");
-      } else if (result.exitCode === 0 && result.syncRequired && runtimes.length > 0 && canSync && !flags.yes && process.stdout.isTTY) {
+      } else if (result.exitCode === 0 && result.syncRequired && fileRuntimes.length > 0 && canSync && !flags.yes && process.stdout.isTTY) {
         const apply = await p6.confirm({ message: "\xBFRe-aplicar a los runtimes ahora? (sync)" });
         if (!p6.isCancel(apply) && apply) {
           process.exitCode = await runInstall({
-            runtimes,
+            runtimes: fileRuntimes,
             targetDir: flags.targetDir,
             dryRun: false,
             yes: false,
@@ -4095,7 +5023,7 @@ Flags disponibles: jorgex-stack --help`
         } else {
           console.log("Sin aplicar. Cuando quieras: jorgex-stack sync");
         }
-      } else if (result.exitCode === 0 && result.syncRequired && runtimes.length > 0 && canSync && (flags.yes || !process.stdout.isTTY)) {
+      } else if (result.exitCode === 0 && result.syncRequired && fileRuntimes.length > 0 && canSync && (flags.yes || !process.stdout.isTTY)) {
         console.log("Skills/stack actualizados. Ejecuta jorgex-stack sync para aplicarlos a los runtimes.");
       }
       return;
@@ -4104,13 +5032,15 @@ Flags disponibles: jorgex-stack --help`
       const runtimes = await resolveRuntimes(flags);
       if (runtimes === null) return;
       if (runtimes.length === 0) {
-        console.error("Ning\xFAn runtime detectado (opencode, claude-code, codex).");
+        console.error("Ning\xFAn runtime detectado (opencode, claude-code, codex, pi).");
         process.exitCode = 1;
         return;
       }
-      const code = await runModelsPicker({ yes: flags.yes, runtimes });
+      const fileRuntimes = runtimes.filter(isFileManagedRuntime);
+      let code = fileRuntimes.length > 0 ? await runModelsPicker({ yes: flags.yes, runtimes: fileRuntimes }) : 0;
+      if (runtimes.includes("pi")) code = Math.max(code, await runSelectedPi("models", flags.targetDir));
       process.exitCode = code;
-      if (code === 0 && !flags.yes && process.stdout.isTTY) {
+      if (code === 0 && fileRuntimes.length > 0 && !flags.yes && process.stdout.isTTY) {
         const apply = await p6.confirm({ message: "\xBFAplicar ahora los modelos a los agentes instalados? (sync)" });
         if (!p6.isCancel(apply) && apply) {
           const preferenceFile = installModePreferenceFile();
@@ -4123,7 +5053,7 @@ Flags disponibles: jorgex-stack --help`
           }
           const mode = await resolveInstallMode(flags, false);
           if (mode === null) return;
-          process.exitCode = await runInstall({ runtimes, targetDir: flags.targetDir, dryRun: flags.dryRun, yes: false, mode });
+          process.exitCode = await runInstall({ runtimes: fileRuntimes, targetDir: flags.targetDir, dryRun: flags.dryRun, yes: false, mode });
         } else {
           console.log("Sin aplicar. Cuando quieras: jorgex-stack sync");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI y OpenCode",
   "type": "module",
   "license": "MIT",