@afu_context/afu-context 0.0.0-stage → 0.1.7

package/bin/host-autoload.py

@@ -0,0 +1,328 @@
+"""Install npm-hosted AFU extensions in Pi and DSH's normal discovery paths."""
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from afu_context import native_install as fs
+from afu_context.diagnostics import state_root
+from afu_context.management import report, validate_policy
+
+
+def run(*args, stdin=None):
+    result = subprocess.run(
+        args, input=stdin, capture_output=True, text=True, timeout=30
+    )
+    if result.returncode:
+        raise ValueError("Host configuration could not be loaded")
+    return result.stdout
+
+
+def write_owned(file, content, marker):
+    if file.is_symlink():
+        raise ValueError("Refusing to replace an extension symlink")
+    if file.exists() and file.read_text() == content:
+        return
+    if file.exists() and not file.read_text().startswith(marker):
+        raise ValueError("Existing extension belongs to another installation")
+    fs.atomic(file, content)
+
+
+def install_pi(root, adapter, settings, previous):
+    agent = (
+        Path(os.environ.get("PI_CODING_AGENT_DIR", "~/.pi/agent"))
+        .expanduser()
+        .resolve()
+    )
+    entry = agent / "extensions" / "afu-context.ts"
+    if previous and str(entry) != previous["entry"]:
+        raise ValueError(
+            "Remove the previous Pi agent registration before switching directories"
+        )
+    if (
+        entry.exists()
+        and previous
+        and hashlib.sha256(entry.read_bytes()).hexdigest() != previous["digest"]
+    ):
+        raise ValueError("Pi extension changed since installation; user file preserved")
+    marker = "// Managed by AFU " + root.as_uri() + "\n"
+    # The explicit launcher supplies its own extension; avoid installing hooks twice.
+    body = marker + "import register from " + json.dumps(str(adapter)) + ";\n"
+    body += "export default function(pi) {\n if (process.env.AFU_EXPLICIT_EXTENSION === 'pi' || (process.env.AFU_CONTEXT_COMPACT_WORKER_COMMAND && process.argv.some(a => a.endsWith('/afu_host_integrations/pi/dist/index.js')))) return;\n"
+    body += (
+        " Object.assign(process.env, "
+        + json.dumps(settings)
+        + ");\n register(pi);\n}\n"
+    )
+    write_owned(entry, body, marker)
+    return {"entry": str(entry), "digest": hashlib.sha256(body.encode()).hexdigest()}
+
+
+def profile_manifest(binary, platform, profile):
+    args = [binary, "--profile", profile, "--dump-config"]
+    tree = run(*args)
+    info = json.loads(
+        run("node", platform / "scripts/dsh-web-probe.mjs", binary, profile)
+    )
+    return Path(info["profileDir"]) / "package.json", tree
+
+
+def install_dsh(root, platform, adapter, settings, profile, previous):
+    binary = shutil.which("dsh")
+    manifest, tree = profile_manifest(binary, platform, profile)
+    if previous and previous["manifest"] != str(manifest):
+        raise ValueError(
+            "DSH profile directory changed; existing registration preserved"
+        )
+    profile_dir = manifest.parent
+    key = hashlib.sha256(str(profile_dir).encode()).hexdigest()[:20]
+    bundle_name = "afu-context-profile-" + key
+    bundle = root / "autoload" / key
+    entry = bundle / "provider.mjs"
+    link = profile_dir / "node_modules" / bundle_name
+    marker = "// Managed by AFU " + root.as_uri() + "\n"
+    original = manifest.read_text()
+    config = json.loads(original)
+    bundles = config["dsh"]["profile"]["bundles"]
+    deps = config.setdefault("dependencies", {})
+    owned_dep = "file:" + str(bundle)
+    if link.parent.is_symlink():
+        raise ValueError("Cannot register a bundle in a shared node_modules symlink")
+    if (link.is_symlink() and link.resolve() != bundle) or (
+        link.exists() and not link.is_symlink()
+    ):
+        raise ValueError("Existing DSH bundle directory conflicts with AFU")
+    if bundle_name in deps and deps[bundle_name] != owned_dep:
+        raise ValueError("DSH bundle dependency has been edited")
+    if bundle_name in bundles and deps.get(bundle_name) != owned_dep:
+        raise ValueError("DSH bundle is not owned by this installation")
+    bundle.mkdir(parents=True, exist_ok=True, mode=0o700)
+    # Bundle membership is read on host startup. Never edit watched cordis.patch.yml.
+    if bundle_name not in bundles:
+        patches = run(
+            "node",
+            platform / "scripts/dsh-overlay.mjs",
+            entry,
+            bundle,
+            binary,
+            stdin=tree,
+        )
+        preset = bundle / "presets.mjs"
+        if preset.exists():
+            old_arg = ", " + json.dumps(str(bundle)) + ");"
+            source = preset.read_text()
+            if old_arg not in source:
+                raise ValueError("Unsupported preset loader format")
+            cleanup = (
+                "import {mkdtempSync,rmSync} from 'node:fs';\n"
+                "import {tmpdir} from 'node:os';\nimport {join} from 'node:path';\n"
+                "const scratch=mkdtempSync(join(tmpdir(),'afu-dsh-presets-'));\n"
+                "process.once('exit',()=>rmSync(scratch,{recursive:true,force:true}));\n"
+            )
+            fs.atomic(preset, cleanup + source.replace(old_arg, ", scratch);"))
+        fs.atomic(bundle / "cordis.patch.yml", patches)
+        fs.write(
+            bundle / "package.json",
+            {
+                "name": bundle_name,
+                "version": "1.0.0",
+                "dsh": {"bundle": {"patch": "./cordis.patch.yml"}},
+            },
+        )
+    content = marker + "Object.assign(process.env," + json.dumps(settings) + ");\n"
+    content += (
+        "export default (await import(" + json.dumps(adapter.as_uri()) + ")).default;\n"
+    )
+    write_owned(entry, content, marker)
+    if not link.exists():
+        link.parent.mkdir(parents=True, exist_ok=True)
+        link.symlink_to(bundle, target_is_directory=True)
+    if bundle_name not in bundles:
+        bundles.append(bundle_name)
+        deps[bundle_name] = owned_dep
+        if manifest.read_text() != original:
+            raise ValueError("Concurrent DSH configuration change")
+        fs.write(manifest, config)
+        try:
+            composed = run(binary, "--profile", profile, "--dump-config")
+            if (
+                str(entry) not in composed
+                and str(bundle / "presets.mjs") not in composed
+            ):
+                raise ValueError("DSH did not resolve the AFU provider")
+        except Exception:
+            if fs.read(manifest) == config:
+                fs.atomic(manifest, original)
+            raise
+    return {"manifest": str(manifest), "bundle": str(bundle), "name": bundle_name}
+
+
+def remove_record(host, record):
+    if host == "pi":
+        entry = Path(record["entry"])
+        if entry.exists():
+            if (
+                entry.is_symlink()
+                or hashlib.sha256(entry.read_bytes()).hexdigest() != record["digest"]
+            ):
+                raise ValueError(
+                    "Pi extension changed since installation; user file preserved"
+                )
+            entry.unlink()
+        return
+    manifest, name = Path(record["manifest"]), record["name"]
+    config = fs.read(manifest)
+    if not config:
+        return
+    bundles = config["dsh"]["profile"]["bundles"]
+    deps = config.get("dependencies", {})
+    if name in deps and deps[name] != "file:" + record["bundle"]:
+        raise ValueError(
+            "DSH dependency changed since installation; user file preserved"
+        )
+    if name in bundles and name not in deps:
+        raise ValueError("DSH bundle ownership changed; user configuration preserved")
+    if name in bundles:
+        bundles.remove(name)
+    deps.pop(name, None)
+    fs.write(manifest, config)
+    # Keep bundle files for running sessions (some presets resolve lazily).
+    link = manifest.parent / "node_modules" / name
+    if link.is_symlink() and link.resolve() == Path(record["bundle"]):
+        link.unlink()
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("action", choices=["install", "upgrade", "remove", "status"])
+    p.add_argument("host", choices=["pi", "dsh"], nargs="?")
+    p.add_argument("--profile")
+    p.add_argument("--state", type=Path)
+    p.add_argument("--ratio")
+    p.add_argument("--context-window")
+    p.add_argument("--json", action="store_true")
+    args = p.parse_args()
+    root = (args.state or state_root()).expanduser().resolve()
+    host = args.host
+    if args.profile and (
+        host != "dsh"
+        or not re.fullmatch(r"[\w-]+", args.profile)
+        or args.profile == "node_modules"
+    ):
+        p.error("invalid DSH profile")
+    key = args.profile or ("web" if host == "dsh" else "user")
+    if args.action == "status":
+        data = report(host, root=root)
+        for install in data["installations"]:
+            name = install["host"]
+            receipt = fs.read(root / "integrations" / (name + ".json"))
+            if receipt.get("autoload"):
+                install.update(
+                    mode="host",
+                    launch=name if name == "pi" else "dsh --profile PROFILE",
+                    registrations=sorted(receipt["autoload"]),
+                )
+        print(json.dumps(data))
+        return
+    path = root / "integrations" / (host + ".json")
+    with fs.lock(path.parent):
+        old = fs.read(path)
+        registrations = dict(old.get("autoload", {}))
+        previous = registrations.get(key, {})
+        if args.action == "remove":
+            for item in [key] if args.profile or host == "pi" else list(registrations):
+                if item in registrations:
+                    remove_record(host, registrations.pop(item))
+            fs.write(
+                path,
+                {
+                    **old,
+                    "host": host,
+                    "autoload": registrations,
+                    "removed": not registrations,
+                },
+            )
+        else:
+            platform = Path(os.environ["AFU_INSTALL_ROOT"]).resolve()
+            adapter = platform / "src/afu_host_integrations" / host / "dist/index.js"
+            if not adapter.is_file():
+                raise ValueError("Adapter not installed")
+
+            def policy(raw, field, cast):
+                if raw is None:
+                    return previous.get(
+                        field, old.get(field) if not registrations else None
+                    )
+                return None if raw == "auto" else cast(raw)
+
+            ratio = policy(args.ratio, "ratio", float)
+            window = policy(args.context_window, "window", int)
+            validate_policy(window, ratio)
+            if window and ratio and int(window * ratio) < 1:
+                raise ValueError("The configured threshold must be at least one token")
+            settings = {
+                "AFU_CONTEXT_COMPACT_WORKER_COMMAND": sys.executable,
+                "AFU_CONTEXT_COMPACT_WORKER_ARGS": json.dumps(
+                    [
+                        "-m",
+                        "afu_context",
+                        "compact",
+                        "worker",
+                        "--factory",
+                        "afu_context.local_worker:create_plugin",
+                    ]
+                ),
+                "AFU_CONTEXT_COMPACT_WORKER_CWD": str(platform),
+                "AFU_INSTALL_ROOT": str(platform),
+                "AFU_STATE_DIR": str(root),
+                "AFU_HOST_CONTEXT_WINDOW_OVERRIDE": str(window or "auto"),
+            }
+            if ratio is not None:
+                settings["AFU_TRIGGER_RATIO"] = str(ratio)
+            if host == "pi":
+                record = install_pi(root, adapter, settings, previous)
+            else:
+                record = install_dsh(root, platform, adapter, settings, key, previous)
+            registrations[key] = {**record, "window": window, "ratio": ratio}
+            fs.write(
+                path,
+                {
+                    **old,
+                    "host": host,
+                    "mode": "host",
+                    "removed": False,
+                    "window": window,
+                    "ratio": ratio,
+                    "build": fs.read(platform / "release.json")["build"],
+                    "autoload": registrations,
+                },
+            )
+    print(
+        json.dumps(
+            {
+                "host": host,
+                "installed": bool(registrations),
+                "upgraded": args.action == "upgrade",
+                "mode": "host",
+                "registrations": sorted(registrations),
+                "launch": "pi" if host == "pi" else "dsh --profile " + key,
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (OSError, ValueError, KeyError, subprocess.TimeoutExpired) as error:
+        sys.exit(
+            "AFU registration failed: " + str(error)
+            if type(error) is ValueError
+            else "AFU registration failed: " + type(error).__name__
+        )

package/bin/install-guide.mjs

@@ -0,0 +1,34 @@
+import {spawnSync} from 'node:child_process';
+import {accessSync,statSync,constants,mkdirSync,rmSync,mkdtempSync} from 'node:fs';
+import {join,delimiter,resolve} from 'node:path';
+import {homedir} from 'node:os';
+import {createInterface} from 'node:readline/promises';
+export function hostAvailable(host,env=process.env){
+ return (env.PATH??env.Path??'').split(delimiter).some(dir=>['',...(process.platform==='win32'?['.exe','.cmd']:[])].some(ext=>{try{accessSync(join(dir,host+ext),constants.X_OK);return statSync(join(dir,host+ext)).isFile();}catch{return false;}}));
+}
+export async function guide(args,env=process.env){
+ if(args[0]!=='install'&&args[0]!=='upgrade')return args;
+ const hosts=['claude','codex','pi','dsh'];let host=hosts.includes(args[1])?args[1]:null;
+ if(!host){
+  const available=hosts.filter(h=>hostAvailable(h,env));
+  if(!available.length)throw Error('HOST_NOT_FOUND: install and sign into your host first');
+  if(available.length===1)host=available[0];
+  else{
+   if(!process.stdin.isTTY)throw Error('HOST_SELECTION_REQUIRED: use install '+available.join('|'));
+   const input=createInterface({input:process.stdin,output:process.stderr});
+   try{console.error(available.map((h,i)=>`${i+1}. ${h}`).join('\n'));host=available[Number(await input.question('Select host: '))-1];}finally{input.close();}
+   if(!host)throw Error('INVALID_HOST_SELECTION');
+  }
+  args=[args[0],host,...args.slice(1)];
+ }
+ if(!hostAvailable(host,env))throw Error('HOST_NOT_FOUND: '+host);
+ if(process.platform==='win32'&&host==='codex')throw Error('WINDOWS_CODEX_NATIVE_UNSUPPORTED');
+ const at=args.indexOf('--state');const state=at>=0?resolve(args[at+1]):env.AFU_STATE_DIR??join(homedir(),'.local/share/afu-context');
+ mkdirSync(state,{recursive:true,mode:0o700});const check=mkdtempSync(join(state,'.write-check-'));rmSync(check,{recursive:true});
+ if(['claude','codex'].includes(host)&&!args.includes('--no-autostart')){
+  const probe=process.platform==='linux'?['systemctl',['--user','show-environment']]:process.platform==='darwin'?['launchctl',['print',`gui/${process.getuid()}`]]:null;
+  if(probe&&spawnSync(probe[0],probe[1],{env,stdio:'ignore',timeout:5000}).status!==0)throw Error(process.platform==='linux' ? `USER_SERVICE_UNAVAILABLE: no host settings changed. Enable your systemd user service, or rerun the same command with --no-autostart (example: afu ${args[0]} ${host} --no-autostart). Keep your existing --config-dir/--state and other options. Manual mode starts the gateway now but does not register login/reboot recovery; rerun it after reboot before using the host.` : 'USER_SERVICE_UNAVAILABLE: no host settings changed; enable your user service manager first');
+ }
+ console.error(`AFU: preflight passed for ${host}; preparing private runtime`);
+ return args;
+}

package/bin/install-process.mjs

@@ -0,0 +1,19 @@
+/** Bounded child lifetime, restricted to the process group created by this call. */
+import {spawn} from 'node:child_process';
+export function runInstall(command,args,env=process.env,onChild=()=>{}){
+ const ms=Number(env.AFU_INSTALL_TIMEOUT_MS??180000);
+ if(!Number.isFinite(ms)||ms<1||ms>600000)throw Error('INVALID_INSTALL_TIMEOUT');
+ return new Promise((resolve,reject)=>{
+  const child=spawn(command,args,{env,stdio:['inherit',2,2],shell:false,detached:process.platform!=='win32'});
+  let reason=null,killTimer;
+  const signal=s=>{if(!child.pid||child.exitCode!==null)return;try{process.platform==='win32'?child.kill(s):process.kill(-child.pid,s);}catch(e){if(e.code!=='ESRCH')throw e;}};
+  const cancel=code=>{if(reason)return;reason=code;signal('SIGTERM');killTimer=setTimeout(()=>signal('SIGKILL'),2000);};
+  const interrupted=()=>cancel('INSTALL_INTERRUPTED');
+  const timer=setTimeout(()=>cancel('INSTALL_TIMEOUT'),ms);
+  process.on('SIGINT',interrupted);process.on('SIGTERM',interrupted);
+  const cleanup=()=>{clearTimeout(timer);clearTimeout(killTimer);process.off('SIGINT',interrupted);process.off('SIGTERM',interrupted);};
+  child.once('error',()=>{cleanup();reject(Error('INSTALL_EXECUTABLE_UNAVAILABLE'));});
+  child.once('exit',code=>{cleanup();code===0&&!reason?resolve():reject(Error(reason??'INSTALL_FAILED_CHECK_DOWNLOAD_LOG'));});
+  try{if(child.pid)onChild(child.pid);}catch{cancel('INSTALL_OWNERSHIP_LOST');}
+ });
+}

package/bin/platform.mjs

@@ -0,0 +1,74 @@
+import {obtainPack} from './prebuilt.mjs';
+import {runInstall} from './install-process.mjs';
+/** Host-only dependencies live outside the installed npm package. */
+import {mkdirSync,readFileSync,writeFileSync,existsSync,rmSync,cpSync,renameSync,realpathSync} from 'node:fs';
+import {join,dirname,delimiter} from 'node:path';
+import {homedir} from 'node:os';
+
+import {spawnSync} from 'node:child_process';
+import {pathToFileURL} from 'node:url';
+import {randomUUID} from 'node:crypto';
+import {recoverLock} from './runtime.mjs';
+const read=p=>{try{return JSON.parse(readFileSync(p,'utf8'));}catch{return null;}};
+export function npmInvocation(env=process.env,platform=process.platform){
+  if(platform!=='win32')return ['npm',[]];
+  const candidates=[join(dirname(process.execPath),'node_modules/npm/bin/npm-cli.js'),
+    ...String(env.PATH??env.Path??'').split(delimiter).map(p=>join(p,'node_modules/npm/bin/npm-cli.js'))];
+  const cli=candidates.find(p=>existsSync(p));
+  if(!cli)throw Error('Cannot locate npm-cli.js; install Node.js with npm');
+  return [process.execPath,[cli]];
+}
+export async function preparePlatform(root,manifest,args,env=process.env){
+  const host=['install','upgrade'].includes(args[0])?args[1]:args[0];
+  if(!['pi','dsh'].includes(host))return root;
+  const dependencies=read(join(root,'platform-dependencies.json'))?.[host];
+  if(!dependencies)throw Error('Missing platform dependency manifest');
+  const base=env.AFU_RUNTIME_DIR??join(homedir(),'.local/share/afu-context/runtimes');
+  const canonical=join(base,manifest.build+'-'+host),pointer=canonical+'.location.json',lock=canonical+'.lock',token=randomUUID();
+  let target=canonical;
+  const refresh=()=>{const name=read(pointer)?.name;target=typeof name==='string'&&name.startsWith(manifest.build+'-'+host)&&!/[\\/]/.test(name)?join(base,name):canonical;};
+  refresh();
+  const ready=()=>read(join(target,'platform-ready.json'))?.build===manifest.build && Object.keys(dependencies).every(name=>existsSync(join(target,'node_modules',name,'package.json'))) && spawnSync(process.execPath,['--input-type=module','-e','await import(process.argv[1])',pathToFileURL(join(target,'src/afu_host_integrations',host,'dist/index.js')).href],{env,stdio:'ignore',timeout:10000}).status===0;
+  mkdirSync(base,{recursive:true,mode:0o700});
+  const deadline=Date.now()+180000;
+  while(true){
+    refresh();if(ready())return target;
+    try{mkdirSync(lock);writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,token}));break;}
+    catch(e){if(e.code!=='EEXIST')throw e;}
+    recoverLock(lock);if(Date.now()>deadline)throw Error('Platform installation still pending');
+    await new Promise(r=>setTimeout(r,300));
+  }
+  const owns=()=>read(join(lock,'owner.json'))?.token===token;
+  if(!owns())return target;
+  let createdTarget;
+  try{
+    refresh();if(ready())return target;
+    // Never repair in place: an older host may still import files from this tree.
+    target=canonical+'-generation-'+randomUUID();
+    createdTarget=target;
+    mkdirSync(target,{recursive:true,mode:0o700});
+    for(const name of ['src/afu_host_integrations','scripts'])cpSync(join(root,name),join(target,name),{recursive:true});
+    cpSync(join(root,'release.json'),join(target,'release.json'));
+    cpSync(join(root,'platform-locks',host,'package.json'),join(target,'package.json'));
+    cpSync(join(root,'platform-locks',host,'package-lock.json'),join(target,'package-lock.json'));
+    // COSEC: fixed package names/versions from the release, no shell interpolation.
+    const [executable,prefix]=npmInvocation(env);
+    if(manifest.prebuilt && process.platform!=='win32'){
+      const payload=await obtainPack(root,manifest,host,env,pid=>writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,childPid:pid,token}),{mode:0o600}));
+      cpSync(join(payload,'node_modules'),join(target,'node_modules'),{recursive:true,verbatimSymlinks:true});
+    }else {
+      // npm treats a Windows junction alias as a linked package. Use its real
+      // prefix so npm ci validates the shipped lock against the actual root.
+      const installTarget=process.platform==='win32'?realpathSync(target):target;
+      await runInstall(executable,[...prefix,'ci','--registry=https://registry.npmjs.org','--prefix',installTarget,'--ignore-scripts','--no-audit','--no-fund'],env,pid=>writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,childPid:pid,token})));
+    }
+    // Import the real adapters: a package.json marker alone misses broken files
+    // and corrupt transitive dependencies. No model request is made by imports.
+    await runInstall(process.execPath,['--input-type=module','-e','await import(process.argv[1])',pathToFileURL(join(target,'src/afu_host_integrations',host,'dist/index.js')).href],env);
+    writeFileSync(join(target,'platform-ready.json'),JSON.stringify({build:manifest.build,cache_protocol:1}),{mode:0o600});
+    const temp=pointer+'.'+token;writeFileSync(temp,JSON.stringify({name:target.slice(base.length+1)}),{mode:0o600});renameSync(temp,pointer);return target;
+  }catch(error){
+    if(owns()&&createdTarget)rmSync(createdTarget,{recursive:true,force:true});
+    throw error;
+  }finally{if(owns())rmSync(lock,{recursive:true,force:true});}
+}

package/bin/prebuilt.mjs

@@ -0,0 +1,64 @@
+/** Release-owned platform packs, copied only after manifest verification. */
+import {createRequire} from 'node:module';
+import {readFileSync,existsSync,lstatSync,realpathSync,readdirSync,mkdirSync,mkdtempSync,renameSync,rmSync,writeFileSync} from 'node:fs';
+import {join,resolve,sep} from 'node:path';
+import {createHash} from 'node:crypto';
+import {homedir} from 'node:os';
+import {runInstall} from './install-process.mjs';
+export function packName(kind){
+ if(!['runtime','pi','dsh'].includes(kind))throw Error('INVALID_PACK_KIND');
+ if(!['darwin','linux','win32'].includes(process.platform)||!['arm64','x64'].includes(process.arch))throw Error('UNSUPPORTED_PLATFORM');
+ return `afu-context-${kind}-${process.platform}-${process.arch}`;
+}
+export function verifyPack(folder,manifest,kind){
+ const info=JSON.parse(readFileSync(join(folder,'pack-manifest.json'),'utf8'));
+ if(info.build!==manifest.build||info.kind!==kind||info.platform!==process.platform||info.arch!==process.arch)throw Error('PLATFORM_PACK_MISMATCH');
+ const root=realpathSync(folder);
+ const listed=new Set(Object.keys(info.files));
+ function walk(dir){for(const entry of readdirSync(dir,{withFileTypes:true})){const file=join(dir,entry.name);if(entry.isDirectory())walk(file);else {const name=file.slice(root.length+1).split(sep).join('/');if(!listed.has(name))throw Error('PACK_UNLISTED_FILE');if(lstatSync(file).isSymbolicLink()&&lstatSync(realpathSync(file)).isDirectory())throw Error('PACK_DIRECTORY_LINK');}}}
+ walk(join(root,'payload'));
+ // COSEC: signed npm integrity plus per-file release hashes; forbid escaping
+ // paths/symlinks before copying any executable into the private runtime.
+ for(const [name,hash] of Object.entries(info.files)){
+  const file=resolve(root,name);
+  if(!file.startsWith(root+sep)||!realpathSync(file).startsWith(root+sep))throw Error('PACK_PATH_ESCAPE');
+  const stat=lstatSync(file);
+  const actual=createHash('sha256').update(readFileSync(file)).digest('hex');
+  if(!stat.isFile()&&!stat.isSymbolicLink()||actual!==hash)throw Error('PACK_INTEGRITY_FAILED');
+ }
+ if(!info.files['payload/'+(kind==='runtime'?'bin/python3':'package.json')])throw Error('PACK_ENTRY_MISSING');
+ return join(folder,'payload');
+}
+export async function obtainPack(root,manifest,kind,env=process.env,onChild=()=>{}){
+ const name=packName(kind);let folder;
+ if(env.AFU_BUNDLE_DIR)folder=join(resolve(env.AFU_BUNDLE_DIR),name);
+ else{
+  try{folder=createRequire(join(root,'package.json')).resolve(name+'/package.json').replace(/[/\\]package.json$/,'');}catch{}
+  if(!folder){
+   const base=resolve(env.AFU_RUNTIME_DIR??join(homedir(),'.local/share/afu-context/runtimes'),'downloads',manifest.build+'-'+kind);
+   // COSEC: only release-owned sibling generations can be selected by this pointer.
+   let cached=base;
+   try{const selected=JSON.parse(readFileSync(base+'.json','utf8')).generation;
+    if(typeof selected==='string'&&selected.startsWith(manifest.build+'-'+kind+'-')&&!/[\\/]/.test(selected))cached=join(resolve(base,'..'),selected);
+   }catch{}
+   try{return verifyPack(join(cached,'node_modules',name),manifest,kind);}catch{}
+   mkdirSync(resolve(base,'..'),{recursive:true,mode:0o700});
+   const stage=mkdtempSync(base+'-');let committed=false;
+   try{
+    console.error(`AFU: downloading ${kind} pack for ${process.platform}/${process.arch}`);
+    // npm retries transient fetch failures and validates its content-addressed cache.
+    await runInstall('npm',['install','--prefix',stage,'--registry=https://registry.npmjs.org','--ignore-scripts','--no-audit','--no-fund','--package-lock=false','--fetch-retries=2','--fetch-retry-mintimeout=1000','--fetch-retry-maxtimeout=5000','--fetch-timeout=30000',name+'@'+manifest.version],env,onChild);
+    folder=join(stage,'node_modules',name);
+    const payload=verifyPack(folder,manifest,kind);
+    const temporary=stage+'.json';
+    writeFileSync(temporary,JSON.stringify({generation:stage.slice(resolve(base,'..').length+1)}),{mode:0o600});
+    renameSync(temporary,base+'.json');committed=true;
+    return payload;
+   }finally{
+    // Never delete a previously usable pack; only this attempt's unpublished files.
+    if(!committed){rmSync(stage,{recursive:true,force:true});rmSync(stage+'.json',{force:true});}
+   }
+  }
+ }
+ return verifyPack(folder,manifest,kind);
+}

package/bin/runtime.mjs

@@ -0,0 +1,111 @@
+import {obtainPack} from './prebuilt.mjs';
+import {cpSync} from 'node:fs';
+import {runInstall} from './install-process.mjs';
+/** Isolated, recoverable bootstrap. Never touches host integrations. */
+import {spawnSync} from 'node:child_process';
+import {existsSync,mkdirSync,readFileSync,writeFileSync,rmSync,statSync,renameSync} from 'node:fs';
+import {join,resolve,dirname,basename} from 'node:path';
+import {homedir} from 'node:os';
+import {randomUUID} from 'node:crypto';
+const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+const read=p=>{try{return JSON.parse(readFileSync(p,'utf8'));}catch{return null;}};
+const alive=pid=>{if(!Number.isSafeInteger(pid)||pid<=0)return false;try{process.kill(pid,0);return true;}catch(e){return e.code!=='ESRCH';}};
+export function recoverLock(lock, now=Date.now()) {
+  // Serialize recovery contenders inside the old lock. Never steal a living owner.
+  const guard=join(lock,'recover');
+  let age;
+  try{age=now-(statSync(lock).birthtimeMs || statSync(lock).mtimeMs);}catch{return false;}
+  try{mkdirSync(guard);writeFileSync(join(guard,'owner.json'),JSON.stringify({pid:process.pid}));}
+  catch{
+    try {
+      const reaper=read(join(guard,'owner.json'));
+      if(reaper ? !alive(reaper.pid) : now-statSync(guard).mtimeMs>180000)rmSync(guard,{recursive:true,force:true});
+    } catch {}
+    return false;
+  }
+  let moved=false;
+  try{
+    const owner=read(join(lock,'owner.json'));
+    if(owner && (alive(owner.pid)||alive(owner.childPid)))return false;
+    // Missing/partial ownership may be a just-created lock, not a crashed install.
+    if(!owner && age<180000)return false;
+    const tomb=lock+'.abandoned-'+randomUUID();
+    renameSync(lock,tomb);moved=true;rmSync(tomb,{recursive:true,force:true});return true;
+  }catch{return false;}finally{if(!moved)rmSync(guard,{recursive:true,force:true});}
+}
+export function runtimeReady(location, build) {
+  const marker=read(join(location,'afu-ready.json'));
+  const python=join(location,process.platform==='win32'?'Scripts/python.exe':'bin/python');
+  if(marker?.build!==build || !existsSync(python))return false;
+  // A surviving marker is not proof that imports and the interpreter still work.
+  return spawnSync(python,['-c','import afu_context.local_cli, aiohttp, tiktoken'],{stdio:'ignore',timeout:10000}).status===0;
+}
+export async function prepareRuntime(root,manifest,env=process.env) {
+  const base=env.AFU_RUNTIME_DIR ?? join(homedir(),'.local/share/afu-context/runtimes');
+  const location=join(base,manifest.build), lock=location+'.lock';
+  const token=randomUUID();
+  const current=()=>{
+    const pointer=read(join(base,manifest.build+'.location.json'))?.location;
+    // COSEC: a cache pointer may select only this build's sibling repair directories.
+    if(typeof pointer==='string' && dirname(resolve(pointer))===resolve(base) && basename(pointer).startsWith(manifest.build+'-repair-'))return pointer;
+    return location;
+  };
+  mkdirSync(base,{recursive:true,mode:0o700});
+  if(runtimeReady(current(),manifest.build))return current();
+  const deadline=Date.now()+180000;
+  while(true){
+    try{mkdirSync(lock,{mode:0o700});writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,token}),{mode:0o600});break;}
+    catch(e){if(e.code!=='EEXIST')throw e;}
+    recoverLock(lock);
+    if(runtimeReady(current(),manifest.build))return current();
+    if(Date.now()>deadline)throw Error('Runtime installation is still owned by another process: '+lock);
+    await sleep(300);
+  }
+  const owns=()=>read(join(lock,'owner.json'))?.token===token;
+  const run=async(command,args)=>{
+    if(!owns())throw Error('Runtime installation ownership changed');
+    try{await runInstall(command,args,env,pid=>writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,childPid:pid,token}),{mode:0o600}));}
+    finally{if(owns())writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,token}),{mode:0o600});}
+  };
+  let createdTarget;
+  try{
+    if(runtimeReady(current(),manifest.build))return current();
+    if(manifest.prebuilt && process.platform!=='win32'){
+      const payload=await obtainPack(root,manifest,'runtime',env,pid=>writeFileSync(join(lock,'owner.json'),JSON.stringify({pid:process.pid,childPid:pid,token}),{mode:0o600}));
+      const target=existsSync(location)?location+'-repair-'+randomUUID():location;
+      createdTarget=target;
+      cpSync(payload,target,{recursive:true,verbatimSymlinks:true});
+      const python=join(target,'bin/python');
+      await run(python,['-c','import afu_context.local_cli, aiohttp, tiktoken']);
+      writeFileSync(join(target,'afu-release.json'),JSON.stringify(manifest),{mode:0o600});
+      writeFileSync(join(target,'afu-ready.json'),JSON.stringify({build:manifest.build,cache_protocol:1}),{mode:0o600});
+      if(target!==location){const pointer=join(base,manifest.build+'.location.json'),temp=pointer+'.'+token;writeFileSync(temp,JSON.stringify({location:target}),{mode:0o600});renameSync(temp,pointer);}
+      return target;
+    }
+    const choices=env.AFU_PYTHON ? [[env.AFU_PYTHON,[]]] : process.platform==='win32' ? [['py',['-3']],['python',[]]] : [['python3',[]],['python',[]]];
+    const selected=choices.find(([cmd,args])=>spawnSync(cmd,[...args,'-c','import sys;sys.exit(sys.version_info<(3,11))'],{stdio:'ignore',timeout:10000}).status===0);
+    if(!selected)throw Error('Python 3.11+ is required. Install it or set AFU_PYTHON.');
+    // Keep a damaged environment at its old path so existing processes/files are not removed.
+    // New preparation uses a fresh directory; the venv must be created at its final path.
+    let target=location;
+    if(existsSync(location))target=location+'-repair-'+randomUUID();
+    const python=join(target,process.platform==='win32'?'Scripts/python.exe':'bin/python');
+    createdTarget=target;
+    await run(selected[0],[...selected[1],'-m','venv',target]);
+    const inputs=['-c',join(root,'python/constraints.txt'),join(root,'python',manifest.wheel)];
+    if(spawnSync('uv',['--version'],{stdio:'ignore',timeout:10000}).status===0)await run('uv',['pip','install','--python',python,...inputs]);
+    else await run(python,['-m','pip','install','--disable-pip-version-check',...inputs]);
+    await run(python,['-c','import afu_context.local_cli, aiohttp, tiktoken']);
+    writeFileSync(join(target,'afu-release.json'),JSON.stringify(manifest),{mode:0o600});
+    writeFileSync(join(target,'afu-ready.json'),JSON.stringify({build:manifest.build,cache_protocol:1}),{mode:0o600});
+    if(target!==location){
+      const pointer=join(base,manifest.build+'.location.json');
+      const temporary=pointer+'.'+token;
+      writeFileSync(temporary,JSON.stringify({location:target}),{mode:0o600});renameSync(temporary,pointer);
+    }
+    return target;
+  }catch(error){
+    if(owns()&&createdTarget)rmSync(createdTarget,{recursive:true,force:true});
+    throw error;
+  }finally{if(owns())rmSync(lock,{recursive:true,force:true});}
+}