afucontext 0.0.0-stage → 0.1.18

package/bin/host-autoload.py

@@ -0,0 +1,546 @@
+"""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
+from afu_context.host_command import host_command
+from afu_context.platform_runtime import redirected
+
+
+def node_binary():
+    """The Node.js running this launcher (npx), so Windows needs no PATH lookup."""
+    return os.environ.get("AFU_NODE") or shutil.which("node") or "node"
+
+
+def dsh_command():
+    """argv that starts DSH, plus the path of its real entry script.
+
+    npm installs a POSIX symlink to lib/bin.js, but on Windows a dsh.cmd shim
+    that subprocess cannot run without a shell. Running node on the package's
+    own entry script works on both and needs no shell.
+    """
+    found = shutil.which("dsh")
+    if not found:
+        raise ValueError("dsh is not installed")
+    if not WINDOWS():
+        return [found], os.path.realpath(found)
+    command = host_command(found, "dsh", platform="nt")
+    return command, command[-1]
+
+
+def run(*args, stdin=None):
+    args = [str(a) for a in args]
+    if args and args[0] == "node":
+        args[0] = node_binary()
+    result = subprocess.run(
+        args, input=stdin, capture_output=True, text=True, encoding="utf-8" if WINDOWS() else None, timeout=30
+    )
+    if result.returncode:
+        raise ValueError("Host configuration could not be loaded")
+    return result.stdout
+
+
+def WINDOWS():
+    return os.name == "nt"
+
+
+def is_link(path):
+    """A symlink, or on Windows a directory junction (both point elsewhere)."""
+    if WINDOWS():
+        return redirected(path)
+    if path.is_symlink():
+        return True
+    is_junction = getattr(path, "is_junction", None)
+    return bool(is_junction and is_junction())
+
+
+def create_junction(target, link):
+    import _winapi
+    # COSEC: native junction API preserves literal paths without cmd expansion.
+    _winapi.CreateJunction(target, link)
+
+
+def link_directory(link, target):
+    """Point link at target. Windows uses a junction: no admin rights needed."""
+    if WINDOWS():
+        create_junction(str(target), str(link))
+        return
+    link.symlink_to(target, target_is_directory=True)
+
+
+def unlink_directory(link):
+    if WINDOWS() and not link.is_symlink():
+        os.rmdir(link)  # Removes the junction itself, never the target files.
+    else:
+        link.unlink()
+
+
+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(encoding="utf-8" if WINDOWS() else None) == content:
+        return
+    if file.exists() and not file.read_text(encoding="utf-8" if WINDOWS() else None).startswith(marker):
+        raise ValueError("Existing extension belongs to another installation")
+    fs.atomic(file, content)
+
+
+# Host releases AFU is built and tested against. Older releases lack hooks the
+# adapters need (Pi below 0.84.3: agent_settled / session_compact_failed /
+# buildContextEntries; DSH 0.1.x: a different session format).
+SUPPORTED = {
+    "pi": {"package": "@earendil-works/pi-coding-agent", "min": (0, 84, 3), "below": (2, 0, 0),
+           "range": ">=0.84.3 <2", "upgrade": "npm install -g @earendil-works/pi-coding-agent"},
+    "dsh": {"package": "@deepseek-ai/dsh", "min": (0, 2, 2), "below": (0, 2, 3),
+            "range": "0.2.2", "upgrade": "npm install -g @deepseek-ai/dsh@0.2.2-rc.1"},
+}
+LEGACY_PI_PACKAGE = "@mariozechner/pi-coding-agent"
+
+
+def _version_tuple(text):
+    m = re.match(r"(\d+)\.(\d+)\.(\d+)", text or "")
+    return tuple(int(x) for x in m.groups()) if m else None
+
+
+def host_package(host):
+    """(package name, version) of the host on PATH, read from its own package.json."""
+    found = shutil.which(host)
+    if not found:
+        return None, None
+    path = Path(os.path.realpath(found))
+    for parent in path.parents:
+        manifest = parent / "package.json"
+        if manifest.is_file():
+            try:
+                data = json.loads(manifest.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                return None, None
+            if data.get("name") in (SUPPORTED[host]["package"], LEGACY_PI_PACKAGE):
+                return data["name"], data.get("version")
+        if parent.name == "node_modules":
+            break
+    return None, None
+
+
+def check_host_version(host):
+    """Refuse an unsupported host before anything is written. Returns the version."""
+    if os.environ.get("AFU_SKIP_HOST_VERSION_CHECK") == "1":
+        return None
+    spec = SUPPORTED[host]
+    name, version = host_package(host)
+    if name is None:
+        # Not an npm install AFU can read (a custom build or wrapper): no claim.
+        return None
+    if name == LEGACY_PI_PACKAGE:
+        raise ValueError(
+            f"Pi {version} ({name}) is not supported; AFU needs {spec['package']} {spec['range']}. "
+            f"Upgrade with: npm uninstall -g {LEGACY_PI_PACKAGE} && {spec['upgrade']}")
+    current = _version_tuple(version)
+    if current is None or not (spec["min"] <= current < spec["below"]):
+        raise ValueError(
+            f"{host} {version} is not supported; AFU needs {spec['package']} {spec['range']}. "
+            f"Upgrade with: {spec['upgrade']}")
+    return version
+
+
+def pi_loads_from_directory(extensions_dir, entry):
+    """Whether Pi's directory discovery loads entry (Pi loads only index.ts/index.js,
+    or a package.json manifest, when the extensions directory has one)."""
+    if (extensions_dir / "package.json").is_file():
+        try:
+            manifest = json.loads((extensions_dir / "package.json").read_text(encoding="utf-8"))
+            listed = (manifest.get("pi") or {}).get("extensions") or []
+            if any((extensions_dir / item).resolve() == entry.resolve() for item in listed):
+                return True
+            if listed:
+                return False
+        except (OSError, ValueError, AttributeError):
+            pass
+    return not ((extensions_dir / "index.ts").exists() or (extensions_dir / "index.js").exists())
+
+
+def register_pi_setting(agent, entry):
+    """List entry in <agent>/settings.json "extensions" when discovery would skip it.
+
+    Only AFU's own path is appended; other entries stay as they are. Returns
+    True when AFU added it (removal then takes it out again), False when it was
+    already listed by someone else or not needed.
+    """
+    if pi_loads_from_directory(entry.parent, entry):
+        return False
+    path = agent / "settings.json"
+    config = fs.read(path) if path.exists() else {}
+    if not isinstance(config, dict):
+        raise ValueError("Pi settings.json is not a JSON object; user file preserved")
+    listed = config.get("extensions", [])
+    if not isinstance(listed, list):
+        raise ValueError("Pi settings.json extensions is not a list; user file preserved")
+    if any(isinstance(item, str) and Path(item).expanduser() == entry for item in listed):
+        return False
+    config["extensions"] = [*listed, str(entry)]
+    fs.write(path, config)
+    return True
+
+
+def unregister_pi_setting(agent, entry):
+    path = agent / "settings.json"
+    config = fs.read(path) if path.exists() else {}
+    listed = config.get("extensions") if isinstance(config, dict) else None
+    if not isinstance(listed, list) or str(entry) not in listed:
+        return
+    config["extensions"] = [item for item in listed if item != str(entry)]
+    if not config["extensions"]:
+        config.pop("extensions")
+    fs.write(path, config)
+
+
+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.
+    # A file: URL imports on every OS (a bare "C:\\..." path is not a valid specifier).
+    body = marker + "import register from " + json.dumps(Path(adapter).resolve().as_uri()) + ";\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.replace(/\\\\/g, '/').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)
+    added = register_pi_setting(agent, entry) or bool(previous and previous.get("settings_entry"))
+    return {"entry": str(entry), "digest": hashlib.sha256(body.encode()).hexdigest(),
+            **({"settings_entry": True} if added else {})}
+
+
+def profile_manifest(command, entry, platform, profile):
+    tree = run(*command, "--profile", profile, "--dump-config")
+    info = json.loads(
+        run("node", platform / "scripts/dsh-web-probe.mjs", entry, profile)
+    )
+    return Path(info["profileDir"]) / "package.json", tree
+
+
+def install_dsh(root, platform, adapter, settings, profile, previous):
+    command, binary = dsh_command()
+    manifest, tree = profile_manifest(command, 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(encoding="utf-8" if WINDOWS() else None)
+    config = json.loads(original)
+    bundles = config["dsh"]["profile"]["bundles"]
+    deps = config.setdefault("dependencies", {})
+    if any(name.split("/")[-1] == "afu-dsh-plugin" for name in deps):
+        raise ValueError("AFU is already installed in this profile with dsh plugin add; remove the plugin first")
+    owned_dep = "file:" + str(bundle)
+    if is_link(link.parent):
+        raise ValueError("Cannot register a bundle in a shared node_modules symlink")
+    if (is_link(link) and link.resolve() != bundle.resolve()) or (
+        link.exists() and not is_link(link)
+    ):
+        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.
+    # A registered bundle whose files are gone (state directory cleared) is
+    # rebuilt the same way as a new one.
+    if bundle_name not in bundles or not (bundle / "package.json").exists() or not (bundle / "cordis.patch.yml").exists():
+        if bundle_name in bundles:
+            bundles.remove(bundle_name)
+            deps.pop(bundle_name, None)
+            fs.write(manifest, config)
+            original = manifest.read_text(encoding="utf-8" if WINDOWS() else None)
+            tree = run(*command, "--profile", profile, "--dump-config")
+        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), ensure_ascii=not WINDOWS()) + ");"
+            source = preset.read_text(encoding="utf-8" if WINDOWS() else None)
+            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"
+    # Extend the engine the running DSH ships (its session format changes
+    # between releases); fall back to AFU's bundled copy if it cannot be found.
+    content += (
+        "import {createRequire} from 'node:module';\n"
+        "import {pathToFileURL} from 'node:url';\n"
+        "try {\n"
+        "  const host=createRequire(" + json.dumps(str(binary)) + ");\n"
+        "  const load=name=>import(pathToFileURL(host.resolve(name)).href);\n"
+        "  const [basic,llm]=await Promise.all([load('@deepseek-ai/dsh-compaction-basic'),load('@deepseek-ai/dsh-llm')]);\n"
+        "  globalThis.__afuDshHost={BasicCompactionEngine:basic.BasicCompactionEngine,BlockAssembler:llm.BlockAssembler,createUserMessage:llm.createUserMessage};\n"
+        "} catch {}\n"
+        "export default (await import(" + json.dumps(adapter.as_uri()) + ")).default;\n"
+    )
+    write_owned(entry, content, marker)
+    # /afuctx-status and /afuctx-dashboard (overlay inserts commands.mjs beside the provider).
+    write_owned(bundle / "commands.mjs",
+                marker + "Object.assign(process.env," + json.dumps(settings) + ");\n"
+                + "export * from " + json.dumps((Path(adapter).parent / "commands.js").as_uri()) + ";\n"
+                + "export { default } from " + json.dumps((Path(adapter).parent / "commands.js").as_uri()) + ";\n",
+                marker)
+    if not link.exists():
+        link.parent.mkdir(parents=True, exist_ok=True)
+        link_directory(link, bundle)
+    if bundle_name not in bundles:
+        bundles.append(bundle_name)
+        deps[bundle_name] = owned_dep
+        if manifest.read_text(encoding="utf-8" if WINDOWS() else None) != original:
+            raise ValueError("Concurrent DSH configuration change")
+        fs.write(manifest, config)
+        try:
+            composed = run(*command, "--profile", profile, "--dump-config")
+            # The composed tree may print paths with either separator.
+            flat = composed.replace("\\\\", "/").replace("\\", "/")
+            if not any(
+                (str(p).replace("\\", "/") in flat or (WINDOWS() and p.as_uri() in composed))
+                for p in (entry, bundle / "presets.mjs")
+            ):
+                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()
+        if record.get("settings_entry"):
+            unregister_pi_setting(entry.parent.parent, entry)
+        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 is_link(link) and link.resolve() == Path(record["bundle"]).resolve():
+        unlink_directory(link)
+
+
+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")
+    p.add_argument("--runtime-only", action="store_true", help="prepare the runtime used by `dsh plugin add`; no profile is changed")
+    args = p.parse_args()
+    root = (args.state or state_root()).expanduser().resolve()
+    host = args.host
+    if args.runtime_only and (host != "dsh" or args.profile):
+        p.error("--runtime-only applies to dsh without --profile")
+    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 and not args.runtime_only:
+                    remove_record(host, registrations.pop(item))
+            plugin_runtime = bool(old.get("plugin_runtime"))
+            if host == "dsh" and not args.profile:
+                (root / "dsh-runtime.json").unlink(missing_ok=True)
+                plugin_runtime = False
+            fs.write(
+                path,
+                {
+                    **old,
+                    "host": host,
+                    "autoload": registrations,
+                    "plugin_runtime": plugin_runtime,
+                    "removed": not registrations and not plugin_runtime,
+                },
+            )
+        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)
+            host_version = check_host_version(host)
+            settings["AFU_STATE_CLI"] = json.dumps([sys.executable, "-m", "afu_context.local_cli"])
+            if args.runtime_only:
+                fs.write(root / "dsh-runtime.json", {"adapter": adapter.as_uri(), "settings": settings})
+            elif host == "pi":
+                record = install_pi(root, adapter, settings, previous)
+                registrations[key] = {**record, "window": window, "ratio": ratio}
+            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,
+                    "plugin_runtime": args.runtime_only or bool(old.get("plugin_runtime")),
+                    **({"host_version": host_version} if host_version else {}),
+                    "window": window,
+                    "ratio": ratio,
+                    "build": fs.read(platform / "release.json")["build"],
+                    "version": fs.read(platform / "release.json").get("version"),
+                    "autoload": registrations,
+                },
+            )
+    print(
+        json.dumps(
+            {
+                "host": host,
+                "installed": bool(registrations) or args.runtime_only,
+                "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,56 @@
+import {spawnSync} from 'node:child_process';
+import {accessSync,statSync,constants,mkdirSync,rmSync,mkdtempSync,readFileSync,realpathSync} from 'node:fs';
+import {join,delimiter,resolve,dirname,relative,isAbsolute} from 'node:path';
+import {homedir} from 'node:os';
+import {createInterface} from 'node:readline/promises';
+export function hostCommand(host,env=process.env,platform=process.platform){
+ if(platform!=='win32')return [host];
+ const packages={pi:'@earendil-works/pi-coding-agent',dsh:'@deepseek-ai/dsh'};
+ if(!packages[host])return [host];
+ for(const dir of (env.PATH??env.Path??'').split(delimiter)){
+  for(const ext of ['.exe','.cmd','.bat']){
+   const binary=join(dir,host+ext);
+   try{if(!statSync(binary).isFile())continue;}catch{continue;}
+   if(ext==='.exe')return [binary];
+   const folder=dirname(realpathSync(binary));
+   for(const base of [join(folder,'node_modules',packages[host]),join(folder,'..',packages[host])]){
+    let data;try{data=JSON.parse(readFileSync(join(base,'package.json'),'utf8'));}catch(e){if(e.code==='ENOENT')continue;throw e;}
+    const entry=typeof data.bin==='string'?data.bin:data.bin?.[host];
+    if(data.name!==packages[host]||typeof entry!=='string')continue;
+    const target=realpathSync(resolve(base,entry)),path=relative(realpathSync(base),target);
+    if(path==='..'||path.startsWith('..\\')||path.startsWith('../')||isAbsolute(path)||!statSync(target).isFile())throw Error('INVALID_HOST_ENTRY');
+    return [process.execPath,target];
+   }
+   throw Error('HOST_NPM_ENTRY_UNAVAILABLE');
+  }
+ }
+ throw Error('HOST_EXECUTABLE_UNAVAILABLE');
+}
+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);
+ 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');}
+ });
+}