jorgex-stack 1.2.2 → 1.2.3

package/README.md

@@ -97,7 +97,7 @@ Programmatic mode does **not** provide:
 
 ### 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.
+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
@@ -107,10 +107,12 @@ 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.
+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

package/dist/cli.js

@@ -3755,13 +3755,19 @@ function parsePackageSources(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;
+    const sources = packages.map((entry) => ({ entry, source: packageSource(entry) }));
+    return sources.every((value) => value.source !== null) ? sources : null;
   } catch {
     return null;
   }
 }
-function expectedReceipt(candidate, state, scope) {
+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,
@@ -3770,21 +3776,52 @@ function expectedReceipt(candidate, state, scope) {
       tarball: candidate.tarball,
       provenance: candidate.provenance
     },
-    scope
+    scope,
+    engram: { binary: engramBin }
   };
 }
-function parseReceipt(receiptJson, candidate, scope) {
+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");
-    if (state !== "installing" && state !== "installed") return null;
-    const expected = expectedReceipt(candidate, state, scope);
-    return sameRecord(parsed, expected) ? expected : null;
+    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);
 }
@@ -3798,21 +3835,26 @@ function planPiPackageLifecycle(input) {
   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);
+  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)) {
+  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, {
+    const parsedReceipt = parseReceipt(input.receiptJson, input.candidate, {
       kind: input.scope.kind,
       codingAgentDir: path29.resolve(input.scope.codingAgentDir)
-    });
-    if (receipt === null) return blocked(input, "receipt-corrupt");
+    }, 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");
-    if (exactSources.length !== 1) 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 {
@@ -3839,7 +3881,7 @@ function planPiPackageLifecycle(input) {
     receipt: expectedReceipt(input.candidate, "installing", {
       kind: input.scope.kind,
       codingAgentDir: path29.resolve(input.scope.codingAgentDir)
-    }),
+    }, input.engramBin),
     ownership: ownership(true)
   };
 }
@@ -3910,47 +3952,25 @@ function executePiPackageLifecycle(input, deps) {
   }
   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 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(isJorgeXPiSource);
+  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 receipt = readReceiptCandidate(input.receiptJson);
-  if (receipt === null) return { kind: "blocked", reason: "receipt-corrupt" };
+  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, {
@@ -3963,8 +3983,12 @@ function validateOwnedOperationState(input) {
   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;
-  if (matchingSources.length !== 1 || matchingSources[0] !== 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 };
@@ -4048,16 +4072,16 @@ function runPiPackageManagedOperation(input, deps) {
 var PI_RUNTIME_CANDIDATE = {
   package: {
     name: "jorgex-pi",
-    version: "0.1.0",
-    source: "npm:jorgex-pi@0.1.0"
+    version: "0.2.2",
+    source: "npm:jorgex-pi@0.2.2"
   },
   provenance: {
-    commit: "791db79e33efd6661899995b5491e4dff5caa363"
+    commit: "99631aa3712f51a625d196e949e48e27f55031a2"
   },
   tarball: {
-    bytes: 89066153,
-    sha256: "6243bf8e3a8dbe7be9103d7ca9b03e196c41ac9eef6578f47ea6d03655366feb",
-    sha512: "07590abec9e9594b001e28d75eb810259c4088f9f2f6d1d5b9fe456bb2d15a7259ff31ee225d5f1f59b27a1c337a1f1f8e3e57089656bf7bbad966e653110ddd"
+    bytes: 89101513,
+    sha256: "e1c6b63719995cf7ba2c96c3b753f19d8f2f0be74f2af9bc319576b7383913f4",
+    sha512: "7b81dc1eb6030d562c70857dcf739798df94c88bddd240b2752c558fc1d21403faa411aa88e182a01664a17e06e2caeef35f1507eff45c97f4acc521469c45a1"
   },
   pi: {
     testedVersions: ["0.84.2"]
@@ -4074,7 +4098,8 @@ var PI_RUNTIME_CANDIDATE = {
       "goal-continuation-v1",
       "mcp-adapter-v1",
       "engram-runtime-tools-v1",
-      "runner-json-v1"
+      "runner-json-v1",
+      "tui-branding-v1"
     ],
     runner: {
       bin: "jorgex-pi",
@@ -4134,11 +4159,11 @@ async function resolvePiEngramRequirement(input, deps) {
     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) {
+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] ?? "0.1.0",
+    version: match?.[1] ?? PI_RUNTIME_CANDIDATE.package.version,
     source: candidate.source
   };
   return {
@@ -4149,7 +4174,8 @@ function flatCandidateReceipt(candidate, scope, state) {
       tarball: { bytes: candidate.bytes, sha256: candidate.sha256, sha512: candidate.sha512 },
       provenance: candidate.provenance ?? { commit: PI_RUNTIME_CANDIDATE.provenance.commit }
     },
-    scope
+    scope,
+    engram: { binary: engramBin }
   };
 }
 function normalizeInstalledSource(settingsJson, alias, canonical) {
@@ -4158,8 +4184,9 @@ function normalizeInstalledSource(settingsJson, alias, canonical) {
     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));
+    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;
@@ -4179,7 +4206,7 @@ function healthyDoctor(stdout, stderr, packageRunner, candidate) {
 }
 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 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" };
@@ -4189,7 +4216,7 @@ function installPiFromVerifiedTarball(input, deps) {
     kind: input.targetDir === void 0 ? "real" : "target-dir",
     codingAgentDir: path30.resolve(paths.codingAgentDir)
   };
-  const installing = flatCandidateReceipt(input.candidate, scope, "installing");
+  const installing = flatCandidateReceipt(input.candidate, scope, "installing", input.engramBin);
   deps.writeReceiptAtomic(`${JSON.stringify(installing)}
 `);
   const alias = `npm:jorgex-pi@file:${artifact.path}`;
@@ -4210,7 +4237,7 @@ function installPiFromVerifiedTarball(input, deps) {
   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");
+  const receipt = flatCandidateReceipt(input.candidate, scope, "installed", input.engramBin);
   deps.writeReceiptAtomic(`${JSON.stringify(receipt)}
 `);
   return { kind: "installed", receipt };
@@ -4430,11 +4457,11 @@ async function acquirePiTarball(destination) {
   }
   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", {
+  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@0.1.0 (${response.status}).`);
+  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 {
@@ -4501,7 +4528,7 @@ async function runPiRuntimeSystem(input) {
         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");
+    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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.2.2",
+  "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",