jorgex-pi 0.8.31 → 0.8.32

package/README.md

@@ -132,7 +132,10 @@ Context7 uses the canonical endpoint `https://mcp.context7.com/mcp`. `CONTEXT7_A
 
 The runner's `status` and `doctor` commands report whether Context7 configuration permits registration; `available` does not mean that an HTTP handshake has occurred. `sync` fails closed on a Context7 conflict and does not modify MCP configuration. At `session_start`, JorgeX registers Context7 and strict DevTools through the external adapter's runtime event bus; it does not create a bundled adapter or fallback factory. Missing, duplicate, malformed, unreadable, or conflicting official setup fails closed with a remediation to run `engram setup pi` and correct the external configuration.
 
-When a compatible Stack projection provides `PI_CODING_AGENT_DIR/jorgex-pi/devtools.v1.json`, the bridge validates that optional handoff and registers strict DevTools through the external adapter. The handoff must contain only `schemaVersion: 1`, `enabled: true`, an absolute executable command, and `dlx chrome-devtools-mcp@<exact-stable-version> --isolated --redact-network-headers --no-performance-crux --no-usage-statistics`. Pi accepts only an exact stable semver in the package argument, reads the handoff at bootstrap, and never edits it; Stack owns its lifecycle. This Pi consumer validates the handoff shape, executable path, version form, and privacy flags; it does not download, checksum, or authenticate the DevTools binary. DevTools is advertised only when that managed handoff is valid and the external adapter accepts the registration. The registration is lazy/proxy (`directTools: false`); `MCP_DIRECT_TOOLS` is not used. Changing or removing the handoff requires reloading Pi because registration is created once per session.
+When a compatible Stack projection provides `PI_CODING_AGENT_DIR/jorgex-pi/devtools.v1.json`, the bridge validates the optional handoff and registers strict DevTools through the external adapter. The historical `schemaVersion: 1` form remains accepted for existing receipts: it requires an absolute executable command and `dlx chrome-devtools-mcp@<exact-stable-version> --isolated --redact-network-headers --no-performance-crux --no-usage-statistics`. The new `schemaVersion: 2` form uses an absolute executable Node command and `args: ["/absolute/path/to/managed-devtools.mjs", "--isolated", "--redact-network-headers", "--no-performance-crux", "--no-usage-statistics"]`; the entry must exist as a regular local JS file, and `dlx` is rejected. Both forms have exactly the four fields `schemaVersion`, `enabled: true`, `command`, and `args`; extra fields and changed flags fail closed. Pi reads but never edits the handoff or fetches browser packages. Stack owns its lifecycle, verifies the installed tree and launcher integrity before execution, and must publish the local form only after verifying the package; **Pi validates shape and executability, not the checksum or ownership of the launcher**. DevTools is advertised only after the handoff and external adapter registration succeed. The registration stays lazy/proxy (`directTools: false`), and a change to the handoff requires reloading Pi.
+
+This capability is consumer-only: the currently published Stack release does not produce the v2 handoff. The separate Stack browser PR must implement and verify the byte-bound launcher before enabling new local DevTools installations; publishing Pi alone does not change personal configurations or make v1 `dlx` byte-bound.
+For v2, the executable must resolve to the same Node binary running Pi. If Pi later uses a different Node installation, Stack must re-verify and re-project the local handoff; Pi rejects the old command rather than launching it with an unknown interpreter.
 
 The official setup owns the Engram binary, database, and memories. Pi only validates the external configuration needed for the session and never installs, updates, removes, or takes ownership of that state. Child environment handling is provider/runtime-owned; JorgeX defines no environment allowlist. Provider-managed `gentle-engram` hooks may automatically persist session, prompt, and compaction context; JorgeX does not own or configure those hooks.
 
@@ -181,7 +184,7 @@ The optional Stack handoff is `PI_CODING_AGENT_DIR/jorgex-pi/playwright.v1.json`
 }
 ```
 
-Pi accepts the handoff only when `schemaVersion` is `1`, `enabled` is `true`, `version` is an exact stable semver, `command` is absolute and executable, and invoking that path with `--version` returns exactly the handoff version. The resolver does not search `PATH`, inspect browser profiles, open a user session, or test whether a live browser can launch. Stack owns installation of the global CLI and Chromium, including browser readiness checks; the Pi capability check validates only the executable handoff and does not download, checksum, or authenticate the CLI binary.
+Pi accepts the handoff only when `schemaVersion` is `1`, `enabled` is `true`, `version` is an exact stable semver, `command` is absolute and executable, and invoking that path with `--version` returns exactly the handoff version. The resolver does not search `PATH`, inspect browser profiles, open a user session, or test whether a live browser can launch. Stack owns acquisition of the shared CLI and Chromium, including browser readiness checks; the Pi capability check validates only the executable handoff and does not download, checksum, or authenticate the CLI binary.
 
 When the handoff is absent, malformed, or fails the version check, the capability stays hidden and the browser guidance is omitted. A manually written file that satisfies the same schema and executable/version checks is accepted; Pi does not authenticate its provenance. Once a valid handoff is present, Pi exposes the routing with the managed command path. The bootstrap resolves it in `before_agent_start` for each agent turn and does not rewrite it; changing or removing the file is re-evaluated on the next turn. The capability is advertised as `playwright-handoff-v1`; this resolver state does not certify live browser readiness. Its adoption is a separate Stack change and does not alter Pi's canonical snapshot or shared source commit.
 

package/contract/jorgex-pi.v1.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "package": {
     "name": "jorgex-pi",
-    "version": "0.8.31",
-    "source": "npm:jorgex-pi@0.8.31"
+    "version": "0.8.32",
+    "source": "npm:jorgex-pi@0.8.32"
   },
   "pi": {
     "minimumVersion": "0.84.2",

package/extensions/mcp-engram.ts

@@ -1,4 +1,4 @@
-import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { accessSync, constants, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { inspectContext7Config, inspectOfficialPackages, resolvePiAgentDir } from "./context7-config.mjs";
@@ -25,6 +25,7 @@ const DEVTOOLS_FIXED_SUFFIX_ARGS = [
   "--no-performance-crux",
   "--no-usage-statistics",
 ];
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
 
 // The bridge never invokes setup or writes settings/MCP state. It inspects the
 // official external setup and reports the state; the bootstrap registers only
@@ -198,16 +199,19 @@ function readChromeDevToolsHandoff({ env, platform }) {
   if (keys.join("\0") !== ["args", "command", "enabled", "schemaVersion"].join("\0")) {
     throw new Error(`Chrome DevTools handoff has an invalid schema at ${handoffPath}`);
   }
-  if (handoff.schemaVersion !== 1 || handoff.enabled !== true) {
+  if ((handoff.schemaVersion !== 1 && handoff.schemaVersion !== 2) || handoff.enabled !== true) {
     throw new Error(`Chrome DevTools handoff has an unsupported schema at ${handoffPath}`);
   }
-  if (typeof handoff.command !== "string" || !paths.isAbsolute(handoff.command)) {
+  if (typeof handoff.command !== "string" || CONTROL_CHARACTERS.test(handoff.command) || !paths.isAbsolute(handoff.command)) {
     throw new Error(`Chrome DevTools handoff command must be an absolute path at ${handoffPath}`);
   }
   if (!isExecutable(handoff.command, platform)) {
     throw new Error(`Chrome DevTools handoff command is not executable at ${handoffPath}`);
   }
-  if (!isDevToolsArgs(handoff.args)) {
+  if (handoff.schemaVersion === 2 && !isCurrentNode(handoff.command, paths, platform)) {
+    throw new Error(`Chrome DevTools handoff command must be this Pi runtime's Node executable at ${handoffPath}`);
+  }
+  if (handoff.schemaVersion === 1 ? !isDevToolsArgs(handoff.args) : !isLocalDevToolsArgs(handoff.args, paths)) {
     throw new Error(`Chrome DevTools handoff has invalid arguments at ${handoffPath}`);
   }
   return { command: handoff.command, args: handoff.args };
@@ -219,6 +223,27 @@ function isDevToolsArgs(args) {
   return args.slice(2).every((arg, index) => arg === DEVTOOLS_FIXED_SUFFIX_ARGS[index]);
 }
 
+function isLocalDevToolsArgs(args, paths) {
+  if (!Array.isArray(args) || args.length !== DEVTOOLS_FIXED_SUFFIX_ARGS.length + 1) return false;
+  const entry = args[0];
+  if (typeof entry !== "string" || CONTROL_CHARACTERS.test(entry) || !paths.isAbsolute(entry)
+    || ![".js", ".mjs"].includes(paths.extname(entry).toLowerCase())) return false;
+  try {
+    if (!lstatSync(entry).isFile()) return false;
+  } catch {
+    return false;
+  }
+  return args.slice(1).every((arg, index) => arg === DEVTOOLS_FIXED_SUFFIX_ARGS[index]);
+}
+
+function isCurrentNode(command, paths, platform) {
+  try {
+    return samePath(realpathSync(command), realpathSync(process.execPath), paths, platform);
+  } catch {
+    return false;
+  }
+}
+
 function isDevToolsPackageArg(arg) {
   if (typeof arg !== "string" || !arg.startsWith(DEVTOOLS_PACKAGE_PREFIX)) return false;
   return isStableExactVersion(arg.slice(DEVTOOLS_PACKAGE_PREFIX.length));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-pi",
-  "version": "0.8.31",
+  "version": "0.8.32",
   "description": "Pi-native runtime package for the JorgeX harness.",
   "license": "MIT",
   "repository": {