jorgex-stack 1.2.1 → 1.2.3

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,26 @@ 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 published package **`jorgex-pi@0.2.2`** 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. The managed Pi package entry is the exact source object `{ "source": "npm:jorgex-pi@0.2.2", "skills": [] }`: Pi discovers the canonical shared skills from `~/.agents/skills`, so the package copy is disabled and does not create duplicate skill loading. A scope-bound receipt under `~/.jorgex-stack/pi-receipt.json` records ownership only after the package runner reports a healthy install and stores the verified Engram executable as `engram.binary`, using the schema v1 consumed by `jorgex-pi@0.2.2`. Receipts created before the Engram binding existed require deliberate removal with the previous Stack release followed by reinstall; they are never adopted automatically. 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.
+
+The 24-hour npm maturity rule applies to the managed adoption boundary: development and PR validation may start against the exact published artifact, but merging the adoption PR, publishing that Stack adoption, and running the real managed installation wait until the package has been public for at least 24 hours unless Jorge explicitly documents an exception in the PR.
+
+`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,883 @@ 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((entry) => ({ entry, source: packageSource(entry) }));
+    return sources.every((value) => value.source !== null) ? sources : null;
+  } catch {
+    return null;
+  }
+}
+function isExactManagedPackage(entry, source) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false;
+  const keys = Object.keys(entry);
+  const skills = Reflect.get(entry, "skills");
+  return keys.length === 2 && keys.includes("source") && keys.includes("skills") && Reflect.get(entry, "source") === source && Array.isArray(skills) && skills.length === 0;
+}
+function expectedReceipt(candidate, state, scope, engramBin) {
+  return {
+    schemaVersion: 1,
+    state,
+    candidate: {
+      package: candidate.package,
+      tarball: candidate.tarball,
+      provenance: candidate.provenance
+    },
+    scope,
+    engram: { binary: engramBin }
+  };
+}
+function parseReceiptShape(receiptJson) {
+  try {
+    const parsed = JSON.parse(receiptJson);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const schemaVersion = Reflect.get(parsed, "schemaVersion");
+    if (schemaVersion !== 1) return null;
+    const state = Reflect.get(parsed, "state");
+    const candidate = Reflect.get(parsed, "candidate");
+    if (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");
+    const engram = Reflect.get(parsed, "engram");
+    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");
+    const scopeKind = Reflect.get(scope, "kind");
+    const codingAgentDir = Reflect.get(scope, "codingAgentDir");
+    if (name !== "jorgex-pi" || typeof version !== "string" || typeof source !== "string" || source !== `npm:jorgex-pi@${version}` || scopeKind !== "real" && scopeKind !== "target-dir" || typeof codingAgentDir !== "string") {
+      return null;
+    }
+    if (engram === void 0) return "upgrade-required";
+    if (engram === null || typeof engram !== "object" || Array.isArray(engram) || typeof Reflect.get(engram, "binary") !== "string" || !path29.isAbsolute(Reflect.get(engram, "binary"))) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function parseReceipt(receiptJson, candidate, scope, engramBin) {
+  const parsed = parseReceiptShape(receiptJson);
+  if (parsed === null || parsed === "upgrade-required") return parsed;
+  const expected = expectedReceipt(candidate, parsed.state, scope, engramBin);
+  return sameRecord(parsed, expected) ? expected : 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(({ source }) => isJorgeXPiSource(source));
+  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) {
+    const parsedReceipt = parseReceipt(input.receiptJson, input.candidate, {
+      kind: input.scope.kind,
+      codingAgentDir: path29.resolve(input.scope.codingAgentDir)
+    }, input.engramBin);
+    if (parsedReceipt === "upgrade-required") return blocked(input, "receipt-upgrade-required");
+    if (parsedReceipt === null) return blocked(input, "receipt-corrupt");
+    receipt = parsedReceipt;
+    if (receipt.state === "installing") return blocked(input, "partial-state");
+    const exactSource = exactSources[0];
+    if (exactSources.length !== 1 || exactSource === void 0 || !isExactManagedPackage(exactSource.entry, input.candidate.package.source)) {
+      return blocked(input, "source-divergent");
+    }
+  }
+  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)
+    }, input.engramBin),
+    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 receiptUpgradeRequired() {
+  return {
+    kind: "blocked",
+    reason: "receipt-upgrade-required",
+    remedy: "El receipt no enlaza Engram; usa la versi\xF3n anterior de Stack para desinstalarlo y luego reinstala."
+  };
+}
+function validateOwnedOperationState(input) {
+  const sources = parsePackageSources(input.detected.settingsJson);
+  if (sources === null) return { kind: "blocked", reason: "settings-corrupt" };
+  const matchingSources = sources.filter(({ source: source2 }) => isJorgeXPiSource(source2));
+  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 parsedReceipt = parseReceiptShape(input.receiptJson);
+  if (parsedReceipt === "upgrade-required") return receiptUpgradeRequired();
+  if (parsedReceipt === null) return { kind: "blocked", reason: "receipt-corrupt" };
+  const receipt = parsedReceipt;
+  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" };
+  }
+  if (input.engramBin !== null && path29.resolve(receipt.engram.binary) !== path29.resolve(input.engramBin)) {
+    return { kind: "blocked", reason: "receipt-corrupt" };
+  }
+  const source = receipt.candidate.package.source;
+  const matchingSource = matchingSources[0];
+  if (matchingSources.length !== 1 || matchingSource === void 0 || matchingSource.source !== source || !isExactManagedPackage(matchingSource.entry, 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.2.2",
+    source: "npm:jorgex-pi@0.2.2"
+  },
+  provenance: {
+    commit: "99631aa3712f51a625d196e949e48e27f55031a2"
+  },
+  tarball: {
+    bytes: 89101513,
+    sha256: "e1c6b63719995cf7ba2c96c3b753f19d8f2f0be74f2af9bc319576b7383913f4",
+    sha512: "7b81dc1eb6030d562c70857dcf739798df94c88bddd240b2752c558fc1d21403faa411aa88e182a01664a17e06e2caeef35f1507eff45c97f4acc521469c45a1"
+  },
+  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",
+      "tui-branding-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, engramBin) {
+  const match = /^npm:jorgex-pi@([^\s]+)$/.exec(candidate.source);
+  const packageValue = candidate.package ?? {
+    name: "jorgex-pi",
+    version: match?.[1] ?? PI_RUNTIME_CANDIDATE.package.version,
+    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,
+    engram: { binary: engramBin }
+  };
+}
+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;
+    const hasCanonical = packages.some((entry) => entry === canonical || entry !== null && typeof entry === "object" && !Array.isArray(entry) && Reflect.get(entry, "source") === canonical);
+    if (packages.filter((entry) => entry === alias).length !== 1 || hasCanonical) return null;
+    Reflect.set(parsed, "packages", packages.map((entry) => entry === alias ? { source: canonical, skills: [] } : 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-${PI_RUNTIME_CANDIDATE.package.version}.tgz`) : path30.join(path30.resolve(input.targetDir), "downloads", `jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.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", input.engramBin);
+  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", input.engramBin);
+  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-${PI_RUNTIME_CANDIDATE.package.version}.tgz`, {
+    redirect: "error",
+    headers: { accept: "application/octet-stream" }
+  });
+  if (!response.ok || response.body === null) throw new Error(`No se pudo descargar jorgex-pi@${PI_RUNTIME_CANDIDATE.package.version} (${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-${PI_RUNTIME_CANDIDATE.package.version}.tgz`) : path30.join(path30.resolve(input.targetDir), "downloads", `jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.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 +4788,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 +4870,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 +4917,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 +4963,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 +5022,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 +5032,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 +5050,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 +5059,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 +5080,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.3",
   "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",