pi-session-mcp 0.8.3 → 0.12.0

package/docs/evaluation/node24-followup-2026-10-17/isolated-package.json

@@ -0,0 +1,12 @@
+{
+  "name": "pi-profile-extension-evaluation-private",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "pi-lens": "4.4.3",
+    "context-mode": "1.0.169",
+    "pi-cache-optimizer": "2.9.3",
+    "@gotgenes/pi-permission-system": "40.3.0"
+  }
+}

package/docs/evaluation/node24-followup-2026-10-17/launcher-review.json

@@ -0,0 +1,17 @@
+{
+  "kind": "independent-read-only-review",
+  "reviewed_at": "2026-10-17T09:22:18.303Z",
+  "status": "PASS",
+  "findings": [],
+  "reviewed": [
+    "actual Pi and MCP launchers",
+    "fixed selector, child PATH and fail-closed routing",
+    "original backup and current hashes",
+    "MCP module hash preservation",
+    "launcher test evidence"
+  ],
+  "limitation": "Three existing Node 22 MCP connections still require client-side reconnect. New-start qualification does not imply all existing processes were migrated.",
+  "changes": 0,
+  "test_runs": 0,
+  "provider_calls": 0
+}

package/docs/evaluation/node24-followup-2026-10-17/launcher-switch.json

@@ -0,0 +1,28 @@
+{
+  "kind": "owned-node-launcher-switch",
+  "scope": "node24-extension-followup-04470d85-3a99-47e3-b356-ce96e77de0dd",
+  "created_at": "2026-10-17T09:18:15.784Z",
+  "node_version": "24.22.0",
+  "runtime_target": ".local/opt/node-v24.22.0",
+  "selector": ".local/share/pi-node/current",
+  "selector_original": null,
+  "pi": {
+    "entry": ".pi/agent/bin/pi",
+    "original_type": "file",
+    "original_hash": "sha256:da0c6a49fe94aadc9765cc7afc6ba6b17e553eed0247d0385c160bc188f5cfbb",
+    "original_mode": 493,
+    "backup_file": "pi-launcher.original",
+    "new_hash": "sha256:e1e9e3d2ae03af319cae5dfca8aff98e496ef68fe4ec67b37f5f96bbb91ac445"
+  },
+  "mcp": {
+    "entry": ".npm-global/bin/pi-session-mcp",
+    "original_type": "symlink",
+    "original_target": "../lib/node_modules/pi-session-mcp/dist/main.js",
+    "new_hash": "sha256:ef635778496a95ea1d51916ce860b91fbc87b1753c229a64f67e230f8c8db646",
+    "module_hash": "sha256:47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7"
+  },
+  "system_node_changed": false,
+  "production_profiles_changed": false,
+  "status": "APPLIED",
+  "backup_scope": ".local/state/pi-node24-switch/node24-extension-followup-04470d85-3a99-47e3-b356-ce96e77de0dd"
+}

package/docs/evaluation/node24-followup-2026-10-17/mcp-launcher-test.json

@@ -0,0 +1,24 @@
+{
+  "kind": "actual-installed-mcp-launcher-node24-handshake",
+  "status": "PASS",
+  "runtime": {
+    "node": "24.22.0",
+    "expected_interpreter": true,
+    "child_path_prefers_runtime": true
+  },
+  "tools": [
+    "pi_capabilities_get",
+    "pi_session_start",
+    "pi_session_list",
+    "pi_session_get",
+    "pi_session_prompt",
+    "pi_session_abort",
+    "pi_session_close",
+    "pi_turn_get"
+  ],
+  "capabilities": "PASS",
+  "session_starts": 0,
+  "provider_calls": 0,
+  "stderr_bytes_discarded": 0,
+  "observed_process_cleanup": "PASS"
+}

package/docs/evaluation/node24-followup-2026-10-17/migrate-client-node.mjs

@@ -0,0 +1,129 @@
+// Operator-authorized interpreter-only migration, not a general setup replacement.
+import { readFile, rename, lstat, open } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+const home=homedir(), scope='node24-extension-followup-04470d85-3a99-47e3-b356-ce96e77de0dd';
+const state=join(home,'.local/state/pi-node24-switch',scope);
+const root=join(home,'.npm-global/lib/node_modules/pi-session-mcp');
+const {immutableReleaseBinding,registrationFingerprint}=await import(join(root,'dist/setup.js'));
+const {DurableOwnershipStore}=await import(join(root,'dist/setup-ownership.js'));
+class MigrationError extends Error {}
+const hash=b=>createHash('sha256').update(b).digest('hex');
+const oldNode='/usr/bin/node', newNode=join(home,'.local/opt/node-v24.22.0/bin/node');
+const entry=join(root,'dist/main.js');
+const targets=[{client:'codex',scope:'user',alias:'pi-session-mcp'},{client:'claude-code',scope:'user',alias:'pi-session-mcp'}];
+const paths=[join(home,'.codex/config.toml'),join(home,'.claude.json')];
+// Preserve all bytes except the one command string. Refuse ambiguous syntax.
+function registration(text,index,from,to){
+ let start,end,obj,command;
+ if(index===0){
+  const headers=[...text.matchAll(/^\[mcp_servers\.pi-session-mcp\]\r?$/gm)];
+  if(headers.length!==1)throw new MigrationError('codex_header_ambiguous');
+  start=headers[0].index+headers[0][0].length;
+  const next=/^\[/m.exec(text.slice(start));end=next?start+next.index:text.length;
+  const block=text.slice(start,end);
+  const commands=[...block.matchAll(/^command\s*=\s*("[^"\r\n]*")\s*\r?$/gm)];
+  if(commands.length!==1)throw new MigrationError('codex_command_ambiguous');
+  command=commands[0];
+  const args=/^args\s*=\s*(\[[^\r\n]*\])\s*\r?$/m.exec(block);
+  if(!args||JSON.stringify(JSON.parse(args[1]))!==JSON.stringify([entry]))throw new MigrationError('codex_args_mismatch');
+  obj={command:JSON.parse(command[1])};
+ }else{
+  const parsed=JSON.parse(text);obj=parsed.mcpServers?.['pi-session-mcp'];
+  if(!obj||JSON.stringify(obj.args)!==JSON.stringify([entry]))throw new MigrationError('claude_args_mismatch');
+  const keys=[...text.matchAll(/"pi-session-mcp"\s*:\s*\{/g)];
+  if(keys.length!==1)throw new MigrationError('claude_key_ambiguous');
+  start=keys[0].index+keys[0][0].lastIndexOf('{');
+  let depth=0,inString=false,escape=false;
+  for(end=start;end<text.length;end++){
+   const c=text[end];if(inString){if(escape)escape=false;else if(c==='\\')escape=true;else if(c==='"')inString=false;}
+   else if(c==='"')inString=true;else if(c==='{')depth++;else if(c==='}'&&!--depth){end++;break;}
+  }
+  const block=text.slice(start,end);
+  if(JSON.stringify(JSON.parse(block))!==JSON.stringify(obj))throw new MigrationError('claude_scope_mismatch');
+  const commands=[...block.matchAll(/"command"\s*:\s*("(?:\\.|[^"\\])*")/g)];
+  if(commands.length!==1)throw new MigrationError('claude_command_ambiguous');command=commands[0];
+ }
+ if(obj.command!==from)throw new MigrationError('interpreter_diverged');
+ const block=text.slice(start,end), offset=start+command.index+command[0].indexOf(command[1]);
+ return text.slice(0,offset)+JSON.stringify(to)+text.slice(offset+command[1].length);
+}
+async function checkedFile(path){const s=await lstat(path);if(!s.isFile()||s.isSymbolicLink()||s.uid!==process.getuid())throw new MigrationError('config_owner_invalid');return {bytes:await readFile(path),mode:s.mode&0o777};}
+async function syncDirectory(path){const handle=await open(path,'r');try{await handle.sync();}finally{await handle.close();}}
+async function durableCreate(path,bytes,mode){const handle=await open(path,'wx',mode);try{await handle.writeFile(bytes);await handle.sync();}finally{await handle.close();}await syncDirectory(dirname(path));}
+async function replace(path,before,after,mode){
+ if(hash(await readFile(path))!==hash(before))throw new MigrationError('config_concurrent_edit');
+ const temp=path+'.'+scope;await durableCreate(temp,after,mode);
+ const current=await checkedFile(path);
+ if(hash(current.bytes)!==hash(before)||current.mode!==mode)throw new MigrationError('config_concurrent_edit');
+ await rename(temp,path);await syncDirectory(dirname(path));
+}
+
+try{
+ const operation=process.argv[2]??'--check';if(process.argv.length>3||!['--check','--apply','--restore-check','--restore'].includes(operation))throw new MigrationError('usage_invalid');
+ if(await readFile(join(state,'.owner'),'utf8')!==scope)throw new MigrationError('scope_owner_invalid');
+ const release=await immutableReleaseBinding(root);
+ const claude=JSON.parse(await readFile(paths[1],'utf8')).mcpServers['pi-session-mcp'];
+ const config=claude.env?.PI_SESSION_MCP_CONFIG;
+ if(typeof config!=='string'||Object.keys(claude.env).length!==1)throw new MigrationError('config_env_mismatch');
+ const fp=node=>registrationFingerprint({scope:'user',nodePath:node,entryPath:entry,configPath:config},release);
+ const oldFingerprint=fp(oldNode),newFingerprint=fp(newNode);
+ const store=new DurableOwnershipStore(join(home,'.local/state/pi-session-mcp/ownership.json'));
+ const restoring=operation.startsWith('--restore'),applying=operation==='--apply'||operation==='--restore';
+ const result=await store.transaction(async access=>{
+  const files=await Promise.all(paths.map(checkedFile));
+  const records=await Promise.all(targets.map(t=>access.get(t)));
+  let meta;
+  try{meta=JSON.parse(await readFile(join(state,'client-registration-migration.json'),'utf8'));}catch(e){if(e.code!=='ENOENT')throw e;}
+  if(meta&&(meta.scope!==scope||meta.release!==release||meta.oldFingerprint!==oldFingerprint||meta.newFingerprint!==newFingerprint))throw new MigrationError('journal_binding_mismatch');
+  if(restoring&&!meta)throw new MigrationError('restore_journal_missing');
+  for(let i=0;i<2;i++){
+   const r=records[i];
+   if(!r||r.phase!=='owned'||![oldFingerprint,...(meta?[newFingerprint]:[])].includes(r.fingerprint))throw new MigrationError('owned_release_binding_mismatch');
+   if(meta&&JSON.stringify({...r,fingerprint:oldFingerprint})!==JSON.stringify(meta.records[i]))throw new MigrationError('ownership_record_changed');
+  }
+  // Existing CLI adapters prove each complete registration, including env and scope.
+  const {createProcessRunner}=await import(join(root,'dist/setup-process.js'));
+  const {createCodexAdapter,createClaudeCodeAdapter}=await import(join(root,'dist/client-adapters/index.js'));
+  const runner=createProcessRunner();
+  const adapters=[createCodexAdapter({runner}),createClaudeCodeAdapter({runner})];
+  const currentNodes=[];
+  const destination=restoring?oldNode:newNode;
+  const replacements=[];
+  for(let i=0;i<2;i++){
+   const text=files[i].bytes.toString('utf8');let current;
+   for(const candidate of [oldNode,...(meta?[newNode]:[])]){
+    try{registration(text,i,candidate,destination);current=candidate;break;}catch{}
+   }
+   if(!current)throw new MigrationError('registration_command_diverged');
+   const inspected=await adapters[i].inspect('user',{scope:'user',nodePath:current,entryPath:entry,configPath:config});
+   if(inspected.state!=='equivalent')throw new MigrationError('registration_not_equivalent');
+   currentNodes.push(current);replacements.push(Buffer.from(registration(text,i,current,destination)));
+  }
+  if(meta)for(let i=0;i<2;i++)if(hash(await readFile(join(state,`client-${i}.original`)))!==meta.files[i].before)throw new MigrationError('original_backup_changed');
+  if(!applying)return {status:'CHECK_PASS',operation,mutations:0,targets:2,owned_release_proved:true,recovery_journal_present:!!meta};
+  const journal=async()=>{
+   const stage=join(state,'client-registration-migration.next');
+   await durableCreate(stage,JSON.stringify(meta,null,2)+'\n',0o600);
+   await rename(stage,join(state,'client-registration-migration.json'));await syncDirectory(state);
+  };
+  if(!meta){
+   for(let i=0;i<2;i++)await durableCreate(join(state,`client-${i}.original`),files[i].bytes,0o600);
+   meta={scope,release,oldFingerprint,newFingerprint,files:files.map((f,i)=>({before:hash(f.bytes),after:hash(replacements[i]),mode:f.mode})),records,steps:[]};
+   await journal(); // Durable recovery intent precedes every configuration/ownership mutation.
+  }
+  for(let i=0;i<2;i++){
+   access.assertHealthy();
+   if(currentNodes[i]!==destination)await replace(paths[i],files[i].bytes,replacements[i],files[i].mode);
+   if(hash(await readFile(paths[i]))!==hash(replacements[i]))throw new MigrationError('postwrite_mismatch');
+   meta.steps.push({operation,index:i,event:'config_verified'});await journal();
+   const inspected=await adapters[i].inspect('user',{scope:'user',nodePath:destination,entryPath:entry,configPath:config});
+   if(inspected.state!=='equivalent')throw new MigrationError('postwrite_registration_mismatch');
+   await access.put({...records[i],fingerprint:restoring?oldFingerprint:newFingerprint});
+   meta.steps.push({operation,index:i,event:'ownership_updated'});await journal();
+  }
+  return {status:restoring?'RESTORED':'APPLIED',operation,targets:2,owned_release_proved:true,only_command_tokens_changed:true,skills_changed:false,release};
+ });
+ console.log(JSON.stringify(result));
+}catch(e){console.error(JSON.stringify({status:'REFUSED',code:e instanceof MigrationError?e.message:'migration_failed'}));process.exitCode=1;}

package/docs/evaluation/node24-followup-2026-10-17/node-runtime-report.md

@@ -0,0 +1,127 @@
+# Node 24 installation and launcher binding
+
+Date: 2026-10-17. The operator approved continuing the previously proposed Node
+24 update, explicit Pi/MCP interpreter selection and provider-free verification.
+
+Node **24.22.0**, Linux x64, was downloaded from the official versioned Node
+distribution endpoint. The archive's SHA-256 matched the versioned official
+HTTPS `SHASUMS256.txt` exactly. [Download evidence](download.json) records both
+URLs, byte count and hash. No detached-signature verification is claimed.
+
+The runtime was installed alongside existing installations in the user's local
+opt directory. The system Node 22.23.2 package and the separate existing Node
+24.20.0 installation were preserved. Pi remains version 1.1.0; the evaluated
+project and its SDK remain 0.8.3 and 1.2.0. No SDK or Pi package upgrade was
+substituted for a Node update.
+
+## Explicit launch paths
+
+The shared selector is `$HOME/.local/share/pi-node/current`, pointing to the new
+24.22.0 installation. Both the managed Pi launcher and the installed
+`pi-session-mcp` executable now explicitly execute this selector's Node binary.
+They prepend the same runtime's `bin` directory to child PATH and fail if the
+runtime is missing. They do not depend on an optional `XDG_DATA_HOME` override or
+fall back silently to the system interpreter.
+
+The MCP executable's former npm-owned symlink was replaced with the scoped
+wrapper; the installed package's JavaScript entry was not edited. Pi's managed
+version selection is retained. The global shell PATH was not edited.
+
+A subsequent inspection found that both actual user registrations, Codex and
+Claude Code, bypass this wrapper: they directly invoked `/usr/bin/node` with the
+installed server entry. Both registrations were migrated to the real Node
+24.22.0 executable. Only their command string changed; args, environment and all
+other configuration bytes were preserved. The existing owned release binding was
+proved before mutation, and only the two registration fingerprints were updated.
+Managed skills were preserved. The normal setup CLI has no interpreter migration
+operation; its refusal to replace a divergent binding was retained. The explicit
+operator-authorized migration uses a separate reviewed helper with the existing
+ownership fence, private backups and a persistent recovery journal.
+[Migration](client-registration-migration.json),
+[independent review](client-migration-review.json).
+
+Direct client registrations bind the **server** to Node 24. They do not prepend
+PATH like the wrappers. Children that select `node` through PATH can therefore
+still use the client's original runtime. Likewise a bare `node` in an unrelated
+shell can remain Node 22. No host-wide or child-runtime migration is claimed.
+
+The new official runtime bundles npm 11.19.1. The existing user-prefix npm 12.2.0
+was not replaced. PATH inherited from these launchers prefers the runtime's
+bundled npm; the isolated package install used that recorded version with
+lifecycle scripts disabled.
+
+For an optional shell-local selection:
+
+```sh
+export PATH="$HOME/.local/share/pi-node/current/bin:$PATH"
+node --version
+```
+
+## Verification
+
+- The real `pi --version` path returned **1.1.0**. A preload receipt independently
+  observed Node **24.22.0**, the expected executable and child PATH, even when
+  the incoming PATH selected only system locations. [Pi result](pi-launcher-test.json).
+- The real installed MCP executable completed initialize, `tools/list` and
+  `pi_capabilities_get` with a fresh synthetic configuration and isolated HOME.
+  Its receipt likewise observed Node **24.22.0**. Eight tools were listed;
+  zero sessions were started and zero providers were called. Child termination
+  was observed. [MCP result](mcp-launcher-test.json).
+- The full provider-free suite passed **1,459 tests**, six skipped, zero failures,
+  across 60 files. The standalone offline CLI passed **308 tests** with no failures
+  or skips. These counts overlap. Typecheck and both builds passed.
+  [Source-bound checks](node24-checks.json).
+- Evaluated source digest remained
+  `sha256:686887d57899c2e55593bb7dd98b78be08ea0fc6c471a6dd4eab3298f890d160`.
+- An independent read-only review found no concrete launcher/ownership issue.
+  [Review](launcher-review.json).
+- Offline Doctor, exact registration inspection and the normal setup verification
+  were run against the actual installed package and existing configuration.
+  A separate bounded direct-registration handshake invokes only initialize,
+  `tools/list` and `pi_capabilities_get`. No session or provider was started.
+  [Actual-client verification](client-registration-verification.json).
+
+Three pre-existing MCP stdio connections were still running Node 22 when checked:
+one belongs to a Codex client and two to Claude clients. Their processes cannot
+change interpreter in place. This session has no client reconnect control API;
+it did not terminate peers whose sessions and pipes it does not own. Those clients
+must reconnect their MCP server to apply the new command. The successful
+fresh-start test does not mean that all existing connections were migrated.
+For Codex, the documented desktop path is Settings → MCP servers → Restart;
+the IDE extension exposes Restart extension after saving the server settings.
+[Official Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
+
+## Ownership and restoration
+
+The original Pi launcher, original MCP symlink target, file modes, original/current
+hashes and an ownership marker are stored under the user's local state directory
+in scope `node24-extension-followup-04470d85-3a99-47e3-b356-ce96e77de0dd`.
+The [switch record](launcher-switch.json) is path-free relative to user home.
+
+The [restoration helper](restore-launchers.mjs) defaults to a non-mutating check.
+It refuses to act if the owner, backups, current wrappers or selector diverged.
+Its check passed. With an explicit `--apply`, it restores the original launcher
+and symlink and removes only this switch's selector; it retains the installed
+Node distribution and evaluation artifacts.
+
+The launcher helper does **not** restore the two direct client registrations.
+For a complete interpreter rollback, first run the separate
+[client migration helper](migrate-client-node.mjs) with `--restore-check`, then
+explicitly `--restore`, and only then restore launchers. The client helper
+revalidates release binding, ownership and exact registration, replaces only the
+current command token, and preserves other client edits. Its journal can recover
+proved old/new intermediate states after interruption; unrecognized divergence
+is refused. Leftover staging files fail closed and require inspection. Both
+helpers were checked; neither restoration was applied. Private full configuration
+backups remain outside the repository and are never copied into this dossier.
+
+```sh
+"$HOME/.local/opt/node-v24.22.0/bin/node" \
+  "$HOME/.local/state/pi-node24-switch/node24-extension-followup-04470d85-3a99-47e3-b356-ce96e77de0dd/restore-launchers.mjs" \
+  --check
+```
+
+Future npm or managed-Pi upgrades can regenerate these launcher files. Their Node
+binding must then be checked again; restoring over later unrelated edits is
+deliberately refused. No authentication store, production profile, deployment or
+external repository was changed by this installation.

package/docs/evaluation/node24-followup-2026-10-17/node24-checks.json

@@ -0,0 +1,44 @@
+{
+  "kind": "node24-provider-free-verification",
+  "verified_at": "2026-10-17T09:22:18.294Z",
+  "node": "24.22.0",
+  "source_binding": {
+    "commit": "406dae7e6b99aa5715960490e869bd3fc668cca2",
+    "digest": "sha256:686887d57899c2e55593bb7dd98b78be08ea0fc6c471a6dd4eab3298f890d160"
+  },
+  "source_unchanged": true,
+  "full_suite": {
+    "exit_code": 0,
+    "passed": 1459,
+    "failed": 0,
+    "skipped": 6,
+    "total": 1465,
+    "files": 60,
+    "command": "npm test -- --maxWorkers=2 --reporter=json",
+    "raw_result_hash": "sha256:a032b98a5d34ef1db38f5fd2c5a0f11dd018bccfac9fecec5f4f239ba06c9c35"
+  },
+  "standalone_offline": {
+    "exit_code": 0,
+    "harness_status": "PASS",
+    "summary": {
+      "numTotalTests": 308,
+      "numPassedTests": 308,
+      "numFailedTests": 0,
+      "numPendingTests": 0,
+      "success": true
+    },
+    "model_starts": 0,
+    "provider_calls": 0
+  },
+  "typecheck": {
+    "exit_code": 0
+  },
+  "build": {
+    "exit_code": 0
+  },
+  "build_cli": {
+    "exit_code": 0
+  },
+  "root_package_lock_changed": false,
+  "note": "Offline subset overlaps full suite. Raw tests remain in owned ignored scope; sanitized summary is archived."
+}

package/docs/evaluation/node24-followup-2026-10-17/pi-launcher-test.json

@@ -0,0 +1,13 @@
+{
+  "kind": "actual-pi-launcher-runtime-probe",
+  "invocation": "pi --version",
+  "exit_code": 0,
+  "pi_version": "1.1.0",
+  "runtime": {
+    "node": "24.22.0",
+    "expected_interpreter": true,
+    "child_path_prefers_runtime": true
+  },
+  "stderr_bytes_discarded": 0,
+  "provider_calls": 0
+}

package/docs/evaluation/node24-followup-2026-10-17/publication-export.json

@@ -0,0 +1,11 @@
+{
+  "kind": "derived-publication-export",
+  "source_artifact": "cursor-headless-run.mjs",
+  "original_artifact_sha256": "5b35c97784a54fcd9a43114fc565fccd88c87e9b76dc9c188258619f23fd861f",
+  "public_artifact_sha256": "bb94f8702be86f406f98a08be0d8e5bae7293a677953e560341202e36e14203a",
+  "original_integrity_index_sha256": "112a79eff3f7f8cdcb649d119076bc65f56c4126c55442e817fbc17505bb6fc5",
+  "transformation": "Replace a private absolute interpreter path with process.execPath. Preserve the original v24.22.0 version requirement and all existing run receipts.",
+  "original_preservation": "Original script and index retained in the owned ignored publication scope.",
+  "limits": "This public script is a portability/privacy edit, not the exact byte sequence executed in the historical attempt. No historical run was repeated or reclassified.",
+  "exported_at": "2026-10-17T15:49:24.587910+00:00"
+}

package/docs/evaluation/node24-followup-2026-10-17/restore-launchers.mjs

@@ -0,0 +1,26 @@
+import { readFile, writeFile, rename, symlink, unlink, readlink, lstat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+const scope='node24-extension-followup-04470d85-3a99-47e3-b356-ce96e77de0dd';
+const base=join(homedir(),'.local/state/pi-node24-switch',scope);
+const hash=b=>'sha256:'+createHash('sha256').update(b).digest('hex');
+try{
+ const args=process.argv.slice(2);if(args.length>1||args.some(a=>!['--check','--apply'].includes(a)))throw new Error('invalid_arguments');
+ const metadata=JSON.parse(await readFile(join(base,'restore-metadata.json'),'utf8'));
+ if((await readFile(join(base,'.owner'),'utf8'))!==scope||metadata.scope!==scope)throw new Error('ownership_mismatch');
+ if(metadata.pi.entry!=='.pi/agent/bin/pi'||metadata.mcp.entry!=='.npm-global/bin/pi-session-mcp'||metadata.selector!=='.local/share/pi-node/current'||metadata.runtime_target!=='.local/opt/node-v24.22.0'||metadata.mcp.original_target!=='../lib/node_modules/pi-session-mcp/dist/main.js')throw new Error('metadata_target_mismatch');
+ const pi=join(homedir(),metadata.pi.entry),mcp=join(homedir(),metadata.mcp.entry),selector=join(homedir(),metadata.selector);
+ const original=await readFile(join(base,'pi-launcher.original'));if(hash(original)!==metadata.pi.original_hash)throw new Error('original_backup_changed');
+ const stat=await lstat(mcp),currentPi=await readFile(pi);
+ if(hash(currentPi)===metadata.pi.original_hash&&stat.isSymbolicLink()&&await readlink(mcp)===metadata.mcp.original_target){console.log(JSON.stringify({status:'ALREADY_RESTORED',scope}));process.exit(0);}
+ if(hash(currentPi)!==metadata.pi.new_hash||stat.isSymbolicLink()||hash(await readFile(mcp))!==metadata.mcp.new_hash)throw new Error('launcher_changed_since_switch');
+ if(resolve(await readlink(selector))!==join(homedir(),metadata.runtime_target))throw new Error('selector_changed_since_switch');
+ if(args[0]!=='--apply'){console.log(JSON.stringify({status:'CHECK_PASS',scope,restorable:true,mutations:0}));process.exit(0);}
+ const piStage=pi+'.node24-restore',mcpStage=mcp+'.node24-restore';
+ await writeFile(piStage,original,{flag:'wx',mode:metadata.pi.original_mode});
+ await symlink(metadata.mcp.original_target,mcpStage);
+ await rename(piStage,pi);await rename(mcpStage,mcp);await unlink(selector);
+ const result={status:'RESTORED',scope,restored_at:new Date().toISOString(),node_install_retained:true,system_node_changed:false};
+ await writeFile(join(base,'restoration-result.json'),JSON.stringify(result,null,2)+'\n',{flag:'wx',mode:0o600});console.log(JSON.stringify(result));
+}catch(e){process.stderr.write(JSON.stringify({status:'REFUSED',code:e.message??'restore_failed'})+'\n');process.exitCode=1;}

package/docs/evaluation/node24-followup-2026-10-17/verify-client-node.mjs

@@ -0,0 +1,36 @@
+// Offline Doctor + exact registration inspection + bounded MCP metadata handshake.
+import {readFile,writeFile} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import {join,resolve} from 'node:path';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+const exec=promisify(execFile),home=homedir();
+const root=join(home,'.npm-global/lib/node_modules/pi-session-mcp');
+const node=join(home,'.local/opt/node-v24.22.0/bin/node');
+const output=process.argv[2];
+if(!output)throw Error('output_required');
+const registration=JSON.parse(await readFile(join(home,'.claude.json'),'utf8')).mcpServers['pi-session-mcp'];
+const config=registration.env.PI_SESSION_MCP_CONFIG;
+const env={...process.env,PI_SESSION_MCP_CONFIG:config};
+async function command(entry,args){
+ try{const r=await exec(node,[entry,...args],{env,timeout:45000,maxBuffer:262144});return {exit_code:0,result:JSON.parse(r.stdout)};}
+ catch(e){let result;try{result=JSON.parse(e.stdout);}catch{}return {exit_code:typeof e.code==='number'?e.code:1,...(result?{result}:{}),diagnostics_discarded:true};}
+}
+const doctor=await command(join(root,'scripts/doctor.mjs'),['--json']);
+const verify=[];
+for(const target of ['codex:user:pi-session-mcp','claude-code:user:pi-session-mcp'])verify.push({target,...await command(join(root,'dist/setup-main.js'),['--verify','--target',target,'--json'])});
+const {createProcessRunner,createMcpStdioLauncher}=await import(join(root,'dist/setup-process.js'));
+const {createCodexAdapter,createClaudeCodeAdapter}=await import(join(root,'dist/client-adapters/index.js'));
+const {verifyMcpCapabilities}=await import(join(root,'dist/client-adapters/mcp-verifier.js'));
+const runner=createProcessRunner(),intent={scope:'user',nodePath:node,entryPath:join(root,'dist/main.js'),configPath:config};
+const inspections=[];
+for(const adapter of [createCodexAdapter({runner}),createClaudeCodeAdapter({runner})])inspections.push(await adapter.inspect('user',intent));
+const direct=await verifyMcpCapabilities({launch:createMcpStdioLauncher({nodePath:registration.command,entryPath:registration.args[0],configPath:config})});
+const runtime=(await exec(registration.command,['--version'],{timeout:5000})).stdout.trim();
+const result={kind:'node24-actual-client-registration-verification',verified_at:new Date().toISOString(),runtime,
+ direct_command_matches_expected:registration.command===node,doctor,setup_verify:verify,registration_inspections:inspections,
+ direct_registration_handshake:direct,session_starts:0,provider_calls:0,
+ limits:'The direct Node executable is bound to 24.22.0. It does not prepend PATH; child commands selected by PATH retain the client environment. Existing client stdio connections were not restarted.'};
+result.status=doctor.exit_code===0&&verify.every(v=>v.exit_code===0)&&inspections.every(i=>i.state==='equivalent')&&direct.status==='verified'&&runtime==='v24.22.0'?'PASS':'CHECK_FINDINGS';
+await writeFile(resolve(output),JSON.stringify(result,null,2)+'\n',{flag:'wx',mode:0o600});
+console.log(JSON.stringify({status:result.status,doctor_exit:doctor.exit_code,setup_verify:verify.map(v=>({target:v.target,exit_code:v.exit_code})),direct_handshake:direct.status,session_starts:0,provider_calls:0}));

package/docs/evaluation/permission-gates-2026-10-17/README.md

@@ -0,0 +1,23 @@
+# Permission policy and hook checks
+
+This record tests `@gotgenes/pi-permission-system@40.3.0` from the isolated package prefix with Node 24.22.0. The actual package entry loaded through the evaluation's SDK adapter. The setup used a fresh temporary home and workspace, a synthetic permission configuration, and the existing fixture provider. It made no provider requests and submitted no prompts.
+
+The policy service was obtained through the package's documented root export `getPermissionsService(sessionId)`. The probe checked a general allow and deny, an allowed and denied path, a matching and unmatched MCP target, and the `ask` state for a headless bash operation. All seven states matched the configured policy.
+
+For mediation, the probe called the actual registered `tool_call` handler through the SDK's public API: `AgentSession.extensionRunner.emitToolCall()`. The SDK declarations expose `AgentSession` at `dist/index.d.ts`, `extensionRunner` at `dist/core/agent-session.d.ts`, and `emitToolCall` at `dist/core/extensions/runner.d.ts` for the pinned SDK 1.2.0. The allowed fixture tool passed the hook; a denied write, a headless ask, and an unregistered tool were blocked. An in-memory synthetic counter advanced only after an unblocked result.
+
+No actual executor ran. The evidence establishes deterministic policy resolution and hook mediation for these synthetic inputs. It does not establish operating-system sandboxing, enforcement inside collectors or tool implementations, live UI behavior, MCP transport enforcement, or interactive-client integration. The MCP checks cover the policy surface only; they did not connect to an MCP server. The adapter used print mode without a dialog-capable UI; no model prompt was submitted.
+
+The final sanitized, process-supervised result is archived as [permission-gates-result-verified.json](permission-gates-result-verified.json); matching ignored run receipts have unique UUID filenames under `eval/results/`. Earlier successful public-seam receipts are preserved. The initial diagnostic receipt is retained as [superseded-initial-receipt.json](superseded-initial-receipt.json) because that attempt read a private adapter-handle field. The corrected probe injects the public SDK `createAgentSessionRuntime()` seam and captures its public `runtime.session` result.
+
+Run the supervisor from the repository root with:
+
+```sh
+"$HOME/.local/opt/node-v24.22.0/bin/node" \
+  docs/evaluation/permission-gates-2026-10-17/permission-gate-probe.mjs \
+  eval/results/operator-selected-fresh-gate-archive.json
+```
+
+The archive path must be fresh; an existing path is refused before starting the worker. The supervisor requires worker exit, an empty worker process group, SDK disposal completion, the fixture's `session_shutdown` event, and removal of both temporary homes before it marks the result PASS. It configures a 45-second deadline, SIGTERM then SIGKILL escalation after one second, and a 64-KiB output cap. A triggered deadline forbids PASS. Neither limit was triggered in the successful run. The receipt is published only after cleanup checks. The exact attempt history, including the superseded private-field receipt and corrected harness assumptions, is in [attempts.json](attempts.json); hashes are in [integrity.json](integrity.json).
+
+The JavaScript network/child-process guards are instrumentation, not an OS sandbox. The independent [review](review.json) confirms the narrow public-API and hook-decision scope.

package/docs/evaluation/permission-gates-2026-10-17/attempts.json

@@ -0,0 +1,53 @@
+{
+  "schema_version": "1.0.0",
+  "scope": "provider-free @gotgenes/pi-permission-system@40.3.0 policy and tool_call gate checks",
+  "attempts": [
+    {
+      "attempt": 1,
+      "status": "discarded_harness",
+      "finding": "The SDK public root did not export loadExtensions; an initial fake API approach could not provide registered tools or prove package-hook mediation.",
+      "resolution": "Replaced it with SdkPiSessionAdapter and the public AgentSession.extensionRunner.emitToolCall() seam."
+    },
+    {
+      "attempt": 2,
+      "status": "failed_configuration_context",
+      "finding": "Policy checks all resolved to the default ask state because the isolated agent-directory variables were not set before loading the candidate entry.",
+      "resolution": "Set HOME, PI_CODING_AGENT_DIR, and XDG directories to the fresh temporary scope before extension initialization."
+    },
+    {
+      "attempt": 3,
+      "status": "failed_fixture_policy",
+      "finding": "The fixture tool inherited the configured deny fallback because no explicit fixture_tool allow rule existed.",
+      "resolution": "Added the exact synthetic fixture_tool allow rule, retained the global deny fallback, then reran the full probe."
+    },
+    {
+      "attempt": 4,
+      "status": "superseded_receipt",
+      "evidence": "superseded-initial-receipt.json",
+      "finding": "Policy and hook outcomes were correct, but the probe reached the SDK session through the private SdkPiSessionAdapter handle.session property.",
+      "resolution": "Retained the sanitized diagnostic and replaced access with the public extensionSdk.createRuntime seam and AgentSessionRuntime.session getter."
+    },
+    {
+      "attempt": 5,
+      "status": "pass",
+      "evidence": "permission-gates-result.json",
+      "ignored_receipt": "eval/results/permission-gates-514fd082-4f96-46bf-b520-514130f1d790.json",
+      "evidence_id": "a522f14a-9b44-49dd-b738-d39c56571910",
+      "summary": "Seven policy checks matched. Actual registered hook passed the allowed fixture tool and blocked denied write, headless ask, and unregistered tool; the in-memory counter advanced once. SDK dispose resolved, fixture shutdown was observed, worker exit and empty process group were confirmed, and both temporary scopes were removed."
+    },
+    {
+      "attempt": 6,
+      "status": "pass",
+      "evidence": "permission-gates-result-final.json",
+      "ignored_receipt": "eval/results/permission-gates-f6fa21fd-c64b-4905-900a-e01d2fc2db5f.json",
+      "summary": "Rerun after adding supervisor SIGKILL escalation, bounded output capture and fresh archive-path preflight. Seven policy queries and four hook outcomes passed, with observed process and temporary-scope cleanup."
+    },
+    {
+      "attempt": 7,
+      "status": "pass_final",
+      "evidence": "permission-gates-result-verified.json",
+      "ignored_receipt": "eval/results/permission-gates-b9552de2-bb69-42cd-be37-4e8a0ce3f9dd.json",
+      "summary": "Final rerun records timeout_triggered explicitly and forbids PASS when the deadline fires. All policy/hook outcomes and cleanup checks passed; timeout was not triggered."
+    }
+  ]
+}

package/docs/evaluation/permission-gates-2026-10-17/integrity.json

@@ -0,0 +1,46 @@
+{
+  "kind": "evaluation-continuation-dossier-integrity",
+  "created_at": "2026-10-17T12:04:43.297432+00:00",
+  "source_binding": {
+    "commit": "406dae7e6b99aa5715960490e869bd3fc668cca2",
+    "digest": "sha256:a4524626851448908b8d21ecbd7248c9956ce830406e81c45fda46c8eb6fffc5"
+  },
+  "files": [
+    {
+      "path": "README.md",
+      "hash": "sha256:4a3f91dfa2f244a10114e68ed8ecc60f3c9099cc26f79eaa0ce270e353a9197c"
+    },
+    {
+      "path": "attempts.json",
+      "hash": "sha256:14f39c91db0f8104e19f79596fa3445d9d82234deda58585d1a481856bababdc"
+    },
+    {
+      "path": "permission-gate-probe.mjs",
+      "hash": "sha256:743e949692cf739579db698c30a2f2e26eeccf784aa94b0fb932e9d57c7ee1c5"
+    },
+    {
+      "path": "permission-gate-worker.mjs",
+      "hash": "sha256:78e4574d9dc753f43d2bdccd9751b5276b90b94e788f74d5e63fb664ca09194e"
+    },
+    {
+      "path": "permission-gates-result-final.json",
+      "hash": "sha256:f8c0034630063d74f7cf4e191965b0084151f8bb09ce0ae5ef84da542de56f3d"
+    },
+    {
+      "path": "permission-gates-result-verified.json",
+      "hash": "sha256:903d8ff9775d59c8149f797ac3505a117f876661341547f8cd63fa76c14d8185"
+    },
+    {
+      "path": "permission-gates-result.json",
+      "hash": "sha256:c91913d046a0d76c1cc8ea8928ada3ce5b55940d6fec5b4034f114f6a4dc3628"
+    },
+    {
+      "path": "review.json",
+      "hash": "sha256:eaa0fc63b6b7c2b6a911f22a6aa30b2b7b0d9fdb9d72f06d69976c652fa247f4"
+    },
+    {
+      "path": "superseded-initial-receipt.json",
+      "hash": "sha256:e10b610f7bea50f224282511b1a4f28f45f871fa86df00022c2ac55417f86168"
+    }
+  ]
+}