agent-bios 0.19.2 → 0.19.3

package/compose/instructions_install.py

@@ -6,6 +6,10 @@ activation path: installed instructions are stored and verifiable, while a launc
 activation creates the per-session snapshot and pin.
 """
 from __future__ import annotations
+try:
+    from host_platform import WINDOWS, runtime_environment
+except ImportError:
+    from .host_platform import WINDOWS, runtime_environment
 
 import argparse
 import base64
@@ -482,7 +486,7 @@ class InstructionsInstaller:
     def _projection_matches(self, entry: dict[str, Any]) -> bool:
         path, after = Path(entry["path"]), entry["after"]
         return self._matches_version(path, after) and (
-            not after.get("exists") or path.stat().st_mode & 0o777 == int(entry["mode"]))
+            not after.get("exists") or WINDOWS or path.stat().st_mode & 0o777 == int(entry["mode"]))
 
     def _old_record(self) -> dict[str, Any] | None:
         return _read_json(self.record_path) if self.record_path.exists() else None
@@ -500,8 +504,8 @@ class InstructionsInstaller:
             if current.is_symlink():
                 raise InstallError(f"owned destination has symlink ancestor: {current}")
 
-    def _expected_owned(self, release: Path) -> dict[str, str]:
-        expected = {str(self.bin_root / "agent-launch"): hashlib.sha256(self._launcher_body(release)).hexdigest(),
+    def _expected_owned(self, release: Path, launcher_runtime=None) -> dict[str, str]:
+        expected = {str(self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch")): hashlib.sha256(self._launcher_body(release, launcher_runtime=launcher_runtime, current=False)).hexdigest(),
                     str(self.launch_root / "profiles.toml"): _sha256(release / "launch" / "agent-launch.toml")}
         i18n = release / "launch" / "i18n"
         for source in sorted(i18n.glob("*.toml")):
@@ -509,11 +513,11 @@ class InstructionsInstaller:
         return expected
 
     def _validate_owned_record(self, record: dict[str, Any], release: Path) -> None:
-        expected = self._expected_owned(release)
+        expected = self._expected_owned(release, record.get("launcher_runtime"))
         launcher = record.get("launcher")
         if launcher is not None:
-            if not isinstance(launcher, dict) or launcher.get("path") != str(self.bin_root / "agent-launch") \
-                    or launcher.get("sha256") != expected[str(self.bin_root / "agent-launch")]:
+            if not isinstance(launcher, dict) or launcher.get("path") != str(self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch")) \
+                    or launcher.get("sha256") != expected[str(self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch"))]:
                 raise InstallError("private install record has an invalid launcher ownership claim")
             self._safe_owned_path(Path(launcher["path"]), self.bin_root)
         seen: set[str] = set()
@@ -535,7 +539,7 @@ class InstructionsInstaller:
         return None
 
     def _write_owned(self, path: Path, content: bytes, old: dict[str, Any] | None, mode: int) -> dict[str, str] | None:
-        root = self.bin_root if path == self.bin_root / "agent-launch" else self.launch_root
+        root = self.bin_root if path == self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch") else self.launch_root
         self._safe_owned_path(path, root)
         expected = self._owned_hash(old, path)
         if path.exists() and (path.is_symlink() or (expected is None and _sha256(path) != hashlib.sha256(content).hexdigest())
@@ -544,7 +548,35 @@ class InstructionsInstaller:
         _atomic_bytes(path, content, mode)
         return {"path": str(path), "sha256": hashlib.sha256(content).hexdigest()}
 
-    def _launcher_body(self, package_root: Path) -> bytes:
+    def _current_launcher_runtime(self):
+        if not WINDOWS:
+            return None
+        env = runtime_environment(self.env)
+        return {'schema_version': 1, 'python': env.get('AGENT_BIOS_PYTHON_EXECUTABLE', str(Path(sys.executable).resolve())),
+                'environment': env}
+
+    def _launcher_body(self, package_root: Path, *, launcher_runtime=None, current=True) -> bytes:
+        if WINDOWS:
+            spec = self._current_launcher_runtime() if current else launcher_runtime
+            if spec is None:
+                # Exact pre-binding Windows source format, for existing receipts.
+                return ('@echo off\r\n"' + sys.executable + '" "' + str(package_root / "compose/native_cli.py") + '" launch %*\r\n').encode("utf-8")
+            if (not isinstance(spec, dict) or set(spec) != {'schema_version', 'python', 'environment'}
+                    or spec['schema_version'] != 1 or not isinstance(spec['python'], str)
+                    or not Path(spec['python']).is_absolute() or not isinstance(spec['environment'], dict)):
+                raise InstallError('invalid recorded launcher runtime')
+            env = spec['environment']
+            allowed = {'AGENT_BIOS_PYTHON_ENTRY', 'AGENT_BIOS_PYTHON_DEPS', 'AGENT_BIOS_PYTHON_EXECUTABLE'}
+            if env and (set(env) != allowed or any(not isinstance(v, str) or not Path(v).is_absolute() for v in env.values())):
+                raise InstallError('invalid recorded launcher dependency binding')
+            argv = [spec['python']]
+            if env:
+                argv += ['-I', '-X', 'utf8', env['AGENT_BIOS_PYTHON_ENTRY'], '--dependencies', env['AGENT_BIOS_PYTHON_DEPS'], '--script']
+            argv += [str(package_root / 'compose/native_cli.py'), 'launch']
+            if any(any(c in value for c in '\r\n\0"') for value in argv):
+                raise InstallError('unsafe launcher runtime argument')
+            command = ' '.join('"' + value.replace('%', '%%') + '"' for value in argv)
+            return ('@echo off\r\nsetlocal DisableDelayedExpansion\r\nchcp 65001 >nul\r\n' + command + ' %*\r\n').encode('utf-8')
         quoted = shlex.quote(str(package_root))
         # Verify historical ownership using the exact released launcher vocabulary.
         canonical = (package_root / "compose/instructions_store.py").is_file()
@@ -564,6 +596,36 @@ class InstructionsInstaller:
         spec.loader.exec_module(module)
         return module.ShellIntegration(self.env, self.repo)
 
+    def launcher_reachability(self) -> dict[str, Any]:
+        """Report whether the launcher this install deposits can actually be typed.
+
+        Both answers are known here and invisible in the installed tree: install
+        writes the launcher into a directory the caller's PATH may not carry, and
+        the shell connection that reaches it for bare host commands is opt-in. A
+        completion summary that omits them reports a success the caller cannot use.
+        Read-only, and never raises: a summary is not worth failing an install
+        that succeeded, and reporting must not become a reason to write.
+        """
+        launcher = self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch")
+        connected: bool | None = None
+        if not WINDOWS:
+            # zsh is the only shell this connection speaks; elsewhere the question
+            # has no answer rather than a negative one.
+            try:
+                connected = bool(self._shell_manager().status().get("enabled"))
+            except (InstallError, OSError, RuntimeError, ValueError):
+                connected = False
+        try:
+            target = os.path.normcase(os.path.realpath(self.bin_root))
+            # No expanduser: a shell does not tilde-expand PATH entries when it
+            # searches, so a literal ~ there really does not find the command.
+            on_path = any(os.path.normcase(os.path.realpath(part)) == target
+                          for part in self.env.get("PATH", "").split(os.pathsep) if part)
+        except (OSError, ValueError):
+            on_path = True  # Undecidable; do not tell the caller PATH is wrong on a guess.
+        return {"path": str(launcher), "directory": str(self.bin_root),
+                "on_path": on_path, "shell_connected": connected}
+
     def setup_catalog(self) -> dict[str, Any]:
         return self._catalog(self.repo)
 
@@ -650,6 +712,8 @@ class InstructionsInstaller:
         return result
 
     def _shell_paths(self, action: str) -> list[dict[str, Any]]:
+        if WINDOWS:
+            return []
         try:
             manager = self._shell_manager()
             # A receipt-less managed script may survive an interrupted opt-in.
@@ -736,7 +800,7 @@ class InstructionsInstaller:
         if not isinstance(baseline_ref, str):
             raise InstallError("private instructions store candidate has no baseline ref")
         owned: list[tuple[Path, bytes, int]] = [
-            (self.bin_root / "agent-launch", self._launcher_body(release), 0o755),
+            (self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch"), self._launcher_body(release), 0o755),
             (self.launch_root / "profiles.toml", (release / "launch" / "agent-launch.toml").read_bytes(), 0o644),
         ]
         owned.extend((self.launch_root / "i18n" / source.name, source.read_bytes(), 0o644)
@@ -759,6 +823,8 @@ class InstructionsInstaller:
             "launcher": launcher, "config_files": config, "created_at": int(time.time()),
             "mode": "private-session-scoped", "needs_action": [],
         }
+        if WINDOWS:
+            record["launcher_runtime"] = self._current_launcher_runtime()
         if selection_mode is not None:
             record["selection_mode"] = selection_mode
         paths = [{"path": str(path), "before": self._file_version(path),
@@ -990,7 +1056,7 @@ class InstructionsInstaller:
         local = [self.launch_root / name for name in ("presets.local.toml", "review-methods.local.toml", "launcher.local.toml")]
         connections = self.launch_root.parent / "agent-bios"
         cleanup = [*local, connections / "ingest-url", self.user_root / "understand" / "state.json"]
-        owned = [(self.bin_root / "agent-launch", self._launcher_body(release), 0o755),
+        owned = [(self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch"), self._launcher_body(release, launcher_runtime=record.get("launcher_runtime"), current=False), 0o755),
                  (self.launch_root / "profiles.toml", (release / "launch" / "agent-launch.toml").read_bytes(), 0o644)]
         owned.extend((self.launch_root / "i18n" / p.name, p.read_bytes(), 0o644)
                      for p in sorted((release / "launch" / "i18n").glob("*.toml")))
@@ -1190,7 +1256,7 @@ class InstructionsInstaller:
             ("wrappers/codex-run.sh", self.codex_root / "bin" / "codex-run"),
             ("wrappers/codex-helm.sh", self.codex_root / "bin" / "codex-helm"),
             ("wrappers/claude-run.sh", self.claude_root / "bin" / "claude-run"),
-            ("launch/agent-launch.py", self.bin_root / "agent-launch"),
+            ("launch/agent-launch.py", self.bin_root / ("agent-launch.cmd" if WINDOWS else "agent-launch")),
             ("launch/agent-launch.toml", self.launch_root / "profiles.toml"),
             ("launch/agent-launch.zsh", self.launch_root / "shell.zsh"),
         )

package/compose/instructions_session.py

@@ -4,6 +4,10 @@ Native homes stay native. The only files this module writes are private activati
 records and pins; no global instructions, auth, or discovery registration is copied.
 """
 from __future__ import annotations
+try:
+    from host_platform import sync_directory, cli_argv
+except ImportError:
+    from .host_platform import sync_directory, cli_argv
 
 import hashlib
 import json
@@ -144,18 +148,14 @@ def atomic_json(path, data):
         raise SessionError(f"refusing symlink: {path}")
     tmp = path.with_name(path.name + '.' + uuid.uuid4().hex + '.tmp')
     try:
-        with open(tmp, 'x', encoding='utf-8') as out:
+        with open(tmp, 'x', encoding='utf-8', newline='\n') as out:
             os.chmod(tmp, 0o600)
             json.dump(data, out, ensure_ascii=False, indent=2)
             out.write('\n')
             out.flush()
             os.fsync(out.fileno())
         os.replace(tmp, path)
-        fd = os.open(path.parent, os.O_RDONLY)
-        try:
-            os.fsync(fd)
-        finally:
-            os.close(fd)
+        sync_directory(path.parent)
     finally:
         tmp.unlink(missing_ok=True)
 

package/compose/instructions_setup.py

@@ -6,6 +6,11 @@ import json
 import os
 from pathlib import Path
 import platform
+
+try:
+    from host_platform import runtime_environment
+except ImportError:
+    from .host_platform import runtime_environment
 import re
 import shlex
 import shutil
@@ -44,7 +49,7 @@ def dependency_inventory(repo: Path, environ: dict[str, str] | None = None, *,
     env["PYTHONDONTWRITEBYTECODE"] = "1"
     home = Path(env.get("HOME", str(Path.home())))
     system = system or platform.system()
-    supported = system in {"Darwin", "Linux"}
+    supported = system in {"Darwin", "Linux", "Windows"}
     paths = {name: which(name, path=env.get("PATH", os.defpath))
              for name in ("bash", "python3", "node", "npm", "brew", "git", "zsh", "claude", "codex", "cp", "mktemp")}
 
@@ -76,7 +81,7 @@ def dependency_inventory(repo: Path, environ: dict[str, str] | None = None, *,
     brew_row = add("homebrew", "Homebrew", "optional package manager", "Offers local package installation recipes when available.",
         path=paths["brew"], argv=[paths["brew"], "--version"] if paths["brew"] else None,
         reason="Optional: use an existing operating-system package manager or the official host installer.")
-    brew = paths["brew"] if brew_row["status"] == "available" else None
+    brew = paths["brew"] if brew_row["status"] == "available" and system != "Windows" else None
 
     def formula(name: str) -> list[str] | None:
         return [brew, "install", name] if brew else None
@@ -84,7 +89,7 @@ def dependency_inventory(repo: Path, environ: dict[str, str] | None = None, *,
     add("bash", "Bash", "runtime", "Runs the package entry point and bundled shell tools.",
         path=paths["bash"], argv=[paths["bash"], "--version"] if paths["bash"] else None,
         action=formula("bash"), scope="Homebrew prefix", reason="Install Bash using your operating system package manager.")
-    py = paths["python3"]
+    py = sys.executable if system == "Windows" else paths["python3"]
     add("python3", "Python 3.11+", "runtime", "Runs installation, instructions storage, and terminal interfaces.", path=py,
         argv=[py, "-c", "import sys; print(sys.version.split()[0]); raise SystemExit(sys.version_info < (3,11))"] if py else None,
         action=formula("python"), scope="Homebrew prefix", reason="Install Python 3.11+ and ensure python3 resolves to it.")
@@ -139,12 +144,16 @@ def dependency_inventory(repo: Path, environ: dict[str, str] | None = None, *,
             code += "; from jsonschema import Draft202012Validator"
         if managed and name in pins:
             code += f"; import sys; raise SystemExit(sys.version_info < (3, 11) or actual != {pins[name]!r})"
+        binding = runtime_environment(env)
+        if binding and name == "jsonschema" and not managed:
+            return [interpreter, "-I", "-X", "utf8", binding['AGENT_BIOS_PYTHON_ENTRY'],
+                    '--dependencies', binding['AGENT_BIOS_PYTHON_DEPS'], '--probe', name]
         return [interpreter, "-c", code]
 
     bootstrap = add("python-venv", "Python venv / pip bootstrap", "managed dependency prerequisite", "Creates the managed environment using AGENT_LAUNCH_PYTHON when set, otherwise python3.", path=bootstrap_python,
         argv=[bootstrap_python, "-c", "import sys, venv, ensurepip; print('venv; bundled pip ' + ensurepip.version()); raise SystemExit(sys.version_info < (3, 11))"] if bootstrap_python else None,
         reason="Install venv/ensurepip for Python 3.11+; check AGENT_LAUNCH_PYTHON if configured. An existing managed environment does not need this bootstrap.")
-    can_provision = bool(paths["bash"] and provisioner.is_file() and (vpy.is_file() or bootstrap["status"] == "available"))
+    can_provision = system != "Windows" and bool(paths["bash"] and provisioner.is_file() and (vpy.is_file() or bootstrap["status"] == "available"))
     try:
         from .instructions_ui_runtime import runtime_inventory
     except ImportError:
@@ -181,6 +190,8 @@ def dependency_inventory(repo: Path, environ: dict[str, str] | None = None, *,
         row = add(identifier, title, "optional job / personal integration", purpose, present=False,
                   reason="Configure this only for a workflow that requires it; setup cannot choose your job environment or account.")
         row["status"] = "not assessed"
+    if system == "Windows":
+        rows = [row for row in rows if row["id"] not in {"homebrew", "bash", "zsh", "cp", "mktemp", "python-bootstrap", "python-venv"}]
     return rows
 
 
@@ -226,6 +237,25 @@ def format_setup_result(result: dict[str, Any], language: str = "en", *, interfa
     def recovery_hint() -> str:
         return t("Use the returned review_id with agent-bios setup status or agent-bios setup resume before continuing.")
 
+    def reachability_lines() -> list[str]:
+        """Name the two ways a finished install still cannot be reached.
+
+        install() leaves a launcher in a directory the caller's PATH may not
+        carry, and the shell connection that reaches it for bare host commands is
+        opt-in. Neither is visible in the installed tree, so a summary that omits
+        them reports a success the caller cannot use. Absent facts say nothing.
+        """
+        reach = result.get("launcher") or {}
+        lines: list[str] = []
+        if reach.get("on_path") is False:
+            lines.append(t("The launcher is installed at {path}, but {directory} is not on this shell's PATH.",
+                           path=str(reach.get("path")), directory=str(reach.get("directory"))))
+            lines.append(t("Add {directory} to the PATH in your shell startup file, or run the launcher by its full path.",
+                           directory=str(reach.get("directory"))))
+        if reach.get("shell_connected") is False:
+            lines.append(t("Typing claude or codex alone does not open the launcher: the optional shell connection is off. Turn it on with agent-bios shell restore."))
+        return lines
+
     if result.get("cancelled"):
         if result.get("cancelled_after_start"):
             lines = [t("Setup stopped after the current operation finished.")]
@@ -262,6 +292,7 @@ def format_setup_result(result: dict[str, Any], language: str = "en", *, interfa
             lines.append(t("The app command registration is retained; instruction capture did not complete."))
         if completed:
             lines.append(t("Dependencies installed: {dependencies}.", dependencies=", ".join(completed)))
+        lines.extend(reachability_lines())
         lines.append(recovery_hint() if interface == "conversation" else t("Open Instructions Studio: agent-bios instructions (terminal or Codex app terminal panel)."))
         return "\n".join(lines)
     if not result.get("applied"):
@@ -301,6 +332,7 @@ def format_setup_result(result: dict[str, Any], language: str = "en", *, interfa
             if request == f"Use $agent-bios to import capture {captured['capture_id']}":
                 request = t("Use $agent-bios to import capture {capture_id}", capture_id=captured["capture_id"])
             lines.append(t("In Codex: {request}", request=request))
+    lines.extend(reachability_lines())
     lines.append(t("Continue in the conversation using the returned verified entrypoint.") if interface == "conversation"
                  else t("Open Instructions Studio: agent-bios instructions (terminal or Codex app terminal panel)."))
     return "\n".join(lines)
@@ -516,6 +548,11 @@ class SetupController:
         except (OSError, RuntimeError, ValueError) as exc:
             result["installation_error"] = str(exc)
             return result
+        # Read once the installation is durable, so the extras failure path reports
+        # the same reachability as the clean one: both leave a launcher behind.
+        reachability = getattr(self.installer, "launcher_reachability", None)
+        if callable(reachability):
+            result["launcher"] = reachability()
         if cancelled():
             return result
         try:

package/compose/instructions_setup_cli.py

@@ -20,6 +20,11 @@ from typing import Any, Callable
 if __name__ == "__main__":
     sys.dont_write_bytecode = True
 
+try:
+    from host_platform import sync_directory, cli_argv, python_argv, runtime_environment
+except ImportError:
+    from .host_platform import sync_directory, cli_argv, python_argv, runtime_environment
+
 try:
     from instructions_install import InstructionsInstaller
     from instructions_setup import SetupController, SetupError, format_setup_result, review_summary
@@ -91,6 +96,24 @@ def _identity() -> dict[str, Any]:
 
 
 def _process_identity(pid: int) -> str | None:
+    if os.name == "nt":
+        import ctypes
+        from ctypes import wintypes
+        kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+        kernel.OpenProcess.restype = wintypes.HANDLE
+        kernel.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+        kernel.GetProcessTimes.argtypes = [wintypes.HANDLE] + [ctypes.POINTER(wintypes.FILETIME)] * 4
+        kernel.CloseHandle.argtypes = [wintypes.HANDLE]
+        handle = kernel.OpenProcess(0x1000, False, pid)
+        if not handle:
+            return None
+        try:
+            times = [wintypes.FILETIME() for _ in range(4)]
+            if not kernel.GetProcessTimes(handle, *(ctypes.byref(t) for t in times)):
+                return None
+            return str((times[0].dwHighDateTime << 32) | times[0].dwLowDateTime)
+        finally:
+            kernel.CloseHandle(handle)
     if sys.platform.startswith("linux"):
         try:
             fields = (Path("/proc") / str(pid) / "stat").read_text().rsplit(")", 1)[1].split()
@@ -131,11 +154,7 @@ def _write_json(path: Path, value: dict[str, Any]) -> None:
             os.fsync(output.fileno())
         temporary.chmod(0o600)
         os.replace(temporary, path)
-        directory = os.open(path.parent, os.O_RDONLY)
-        try:
-            os.fsync(directory)
-        finally:
-            os.close(directory)
+        sync_directory(path.parent)
     finally:
         temporary.unlink(missing_ok=True)
 
@@ -191,7 +210,7 @@ class SetupService:
 
     def start(self, language: str | None = None) -> dict[str, Any]:
         package = Path(self.installer.repo).resolve()
-        cli = ["/bin/bash", str(package / "install.sh")]
+        cli = cli_argv(package)
         return {"schema_version": SCHEMA_VERSION, "kind": "agent-bios-setup-start",
                 "languages": [{"label": label, "id": identifier} for label, identifier in LANGUAGES],
                 "suggested_language": detect_language(self.installer.env), "language": self._language(language),
@@ -302,6 +321,7 @@ class SetupService:
                                   "AGENT_BIOS_INSTRUCTIONS_DIR": context["user_dir"], "CODEX_HOME": context["codex_dir"],
                                   "AGENT_BIOS_CORPUS_DIR": context["user_dir"],
                                   "CLAUDE_CONFIG_DIR": context["claude_dir"]}, "needs_action": []}
+        result["environment"].update(runtime_environment())
         try:
             with try_transaction_lock(Path(context["state_dir"])) as acquired:
                 if not acquired:
@@ -312,7 +332,8 @@ class SetupService:
                 return self._verified_handoff(context, result)
         except (OSError, RuntimeError, ValueError) as exc:
             result["needs_action"].append(str(exc))
-            return result
+            result["environment"].update(runtime_environment())
+        return result
 
     def _verified_handoff(self, context: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
         record = Path(context["state_dir"]) / "runtime/private-install.json"
@@ -322,8 +343,8 @@ class SetupService:
                 reject_symlink_ancestors(record)
                 release = confirmed_release(Path(context["state_dir"]))
                 result.update(package_verified=True, package_root=str(release), release_digest=release.name,
-                              cli_argv=["/bin/bash", str(release / "install.sh")],
-                              setup_argv=["/bin/bash", str(release / "install.sh"), "setup"], guide_path=str(release / "compose/setup/START.md"))
+                              cli_argv=cli_argv(release),
+                              setup_argv=cli_argv(release, "setup"), guide_path=str(release / "compose/setup/START.md"))
                 result["environment"].update(AGENT_BIOS_PACKAGE_ROOT=str(release), AGENT_BIOS_PRIVATE_INSTRUCTIONS="1", AGENT_BIOS_PRIVATE_CORPUS="1", AGENT_BIOS_LEGACY_INSTALL="0")
             except (OSError, RuntimeError, ValueError) as exc:
                 result["needs_action"].append(str(exc))
@@ -348,7 +369,7 @@ class SetupService:
             result["needs_action"].extend(bridge.get("needs_action", []))
             if bridge.get("registered") and not bridge.get("needs_action"):
                 helper = manager.target / "scripts/bridge.py"
-                result.update(helper_verified=True, helper_argv=[sys.executable, str(helper)])
+                result.update(helper_verified=True, helper_argv=python_argv(helper))
             if "AGENT_LAUNCH_VENV" in self.installer.env:
                 result["environment"]["AGENT_LAUNCH_VENV"] = self.installer.env["AGENT_LAUNCH_VENV"]
         except (OSError, RuntimeError, ValueError) as exc:

package/compose/instructions_setup_i18n.py

@@ -172,6 +172,9 @@ MESSAGES: dict[str, tuple[str, str]] = {
     "Open Instructions Studio: agent-bios instructions (terminal or Codex app terminal panel).": ("Instructions Studio 열기: 터미널 또는 Codex 앱 터미널 패널에서 agent-bios instructions를 실행하세요.", "Instructions Studioを開くには、ターミナルまたはCodexアプリのターミナルパネルでagent-bios instructionsを実行してください。"),
     "Setup did not complete.": ("설정을 완료하지 못했습니다.", "セットアップを完了できませんでした。"),
     "Setup complete. Private runtime installed.": ("설정을 완료하고 개인 실행 환경을 설치했습니다.", "セットアップが完了し、専用の実行環境をインストールしました。"),
+    "The launcher is installed at {path}, but {directory} is not on this shell's PATH.": ("실행기를 {path}에 설치했지만, 현재 셸의 PATH에 {directory} 경로가 없습니다.", "ランチャーを{path}にインストールしましたが、{directory}は現在のシェルのPATHにありません。"),
+    "Add {directory} to the PATH in your shell startup file, or run the launcher by its full path.": ("셸 시작 파일의 PATH에 {directory} 경로를 추가하거나, 실행기를 전체 경로로 실행하세요.", "シェルの起動ファイルのPATHに{directory}を追加するか、ランチャーをフルパスで実行してください。"),
+    "Typing claude or codex alone does not open the launcher: the optional shell connection is off. Turn it on with agent-bios shell restore.": ("claude 또는 codex만 입력해도 실행기가 열리지 않습니다. 선택적 셸 연결이 꺼져 있습니다. agent-bios shell restore로 켜세요.", "claudeまたはcodexだけを入力してもランチャーは開きません。任意のシェル連携が無効です。agent-bios shell restoreで有効にしてください。"),
     "Instructions for future activated sessions: none.": ("앞으로 활성화하는 세션에서는 지침을 사용하지 않습니다.", "今後有効にするセッションでは指示を使用しません。"),
     "Instructions for future activated sessions: {instructions}.": ("앞으로 활성화하는 세션에서 사용할 지침: {instructions}.", "今後有効にするセッションで使用する指示：{instructions}。"),
     "Instructions policy: core, infrastructure and personal instructions.": ("지침 정책: 핵심·기반·개인 지침을 사용합니다.", "指示ポリシー：コア・基盤・個人指示を使用します。"),

package/compose/instructions_store.py

@@ -6,6 +6,10 @@ does not alter a host configuration or claim that a snapshot was loaded by a
 host; that is the launch adapter's job.
 """
 from __future__ import annotations
+try:
+    from host_platform import sync_directory, cli_argv
+except ImportError:
+    from .host_platform import sync_directory, cli_argv
 
 import copy
 import contextlib
@@ -126,11 +130,7 @@ def _atomic_write(path: Path, value: Any) -> None:
             tmp.chmod(path.stat().st_mode & 0o777)
         os.replace(tmp, path)
         # Persist the directory entry as well as the file bytes.
-        directory = os.open(path.parent, os.O_RDONLY)
-        try:
-            os.fsync(directory)
-        finally:
-            os.close(directory)
+        sync_directory(path.parent)
     finally:
         with contextlib.suppress(FileNotFoundError):
             tmp.unlink()
@@ -151,7 +151,7 @@ def _rewrite_staged_paths(staging: Path, destination: Path) -> None:
         except UnicodeDecodeError as exc:
             raise InstructionsStoreError(f"snapshot compiler emitted non-text member: {path}") from exc
         if old in text:
-            path.write_text(text.replace(old, new), encoding="utf-8")
+            path.write_text(text.replace(old, new), encoding="utf-8", newline="\n")
 
 
 def _snapshot_relative_paths(files: Any) -> list[str]:

package/compose/instructions_transaction.py

@@ -9,7 +9,10 @@ from __future__ import annotations
 
 import contextlib
 import base64
-import fcntl
+try:
+    from host_platform import file_locks as fcntl, redirected
+except ImportError:
+    from .host_platform import file_locks as fcntl, redirected
 import hashlib
 import json
 import os
@@ -57,7 +60,7 @@ def reject_symlink_ancestors(path: Path) -> None:
     a same-named link elsewhere, or a user-owned link.
     """
     for ancestor in (path, *path.parents):
-        if not ancestor.is_symlink():
+        if not redirected(ancestor):
             continue
         system_alias = (sys.platform == "darwin" and ancestor != path
                         and ancestor in {Path("/var"), Path("/tmp"), Path("/etc")}
@@ -82,10 +85,9 @@ def _depths(name: str) -> dict[str, int]:
 @contextlib.contextmanager
 def _transaction_lock(state_root: Path, *, readonly: bool) -> Iterator[bool]:
     root = Path(state_root).expanduser()
-    if root.is_symlink():
+    if redirected(root):
         raise TransactionError(f"unsafe instructions state root: {root}")
-    if readonly:
-        reject_symlink_ancestors(root)
+    reject_symlink_ancestors(root)
     key = _key(root)
     depths = _depths("lock_depths")
     if depths.get(key, 0):
@@ -101,7 +103,7 @@ def _transaction_lock(state_root: Path, *, readonly: bool) -> Iterator[bool]:
     lock = root / ".corpus-store.lock"
     if lock.is_symlink():
         raise TransactionError(f"unsafe instructions transaction lock: {lock}")
-    flags = (os.O_RDONLY | os.O_NONBLOCK if readonly else os.O_CREAT | os.O_RDWR) | getattr(os, "O_NOFOLLOW", 0)
+    flags = ((os.O_RDWR if os.name == "nt" else os.O_RDONLY) | getattr(os, "O_NONBLOCK", 0) if readonly else os.O_CREAT | os.O_RDWR) | getattr(os, "O_NOFOLLOW", 0)
     try:
         descriptor = os.open(lock, flags, 0o600)
     except FileNotFoundError:

package/compose/instructions_ui_runtime.py

@@ -7,6 +7,7 @@ import hashlib
 import importlib
 import io
 import json
+import os
 from pathlib import Path, PurePosixPath
 import re
 import stat
@@ -255,7 +256,7 @@ def activate_ui_runtime(repo: Path) -> Path:
             return active
         parent = Path(tempfile.gettempdir()).resolve()
         home = Path.home().resolve()
-        if parent == home or home in parent.parents:
+        if os.name != "nt" and (parent == home or home in parent.parents):
             parent = Path("/tmp").resolve()
         temporary = tempfile.TemporaryDirectory(prefix="agent-bios-ui-", dir=parent)
         target = Path(temporary.name)

package/compose/native_cli.py

@@ -0,0 +1,52 @@
+"""Bash-free entrypoint for the installed Windows application and direct Python use."""
+from __future__ import annotations
+import json
+import os
+from pathlib import Path
+import runpy
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'compose'))
+sys.dont_write_bytecode = True
+
+
+def main(args=None):
+    args = list(sys.argv[1:] if args is None else args)
+    os.environ.setdefault('HOME', str(Path.home()))
+    os.environ['PYTHONDONTWRITEBYTECODE'] = '1'
+    if args and args[0] in ('--version', '-V'):
+        print(json.loads((ROOT / 'package.json').read_text(encoding='utf-8'))['version'])
+        return 0
+    command = args.pop(0) if args else ('instructions' if (Path(os.environ.get('AGENT_BIOS_STATE_DIR', str(Path.home()/'.local/share/agent-bios'))) / 'runtime/private-install.json').exists() else 'install')
+    if command in ('help', '--help', '-h'):
+        print('agent-bios: install | instructions | setup | app | import | learn | understand | launch | verify | status | uninstall | reset')
+        return 0
+    modules = {'instructions':'instructions', 'corpus':'instructions', 'setup':'instructions_setup_cli',
+               'app':'instructions_app', 'import':'instructions_import', 'understand':'instructions_understand'}
+    if command in ('install', 'onboard', 'verify', 'status', 'uninstall', 'reset'):
+        import instructions_install
+        return instructions_install.main(['--repo', str(ROOT), command, *args])
+    if command in modules:
+        import importlib
+        module = importlib.import_module(modules[command])
+        if command in ('instructions', 'corpus'):
+            return module.main(['--repo', str(ROOT), *args], bundled_ui=True)
+        return module.main(['--repo', str(ROOT), *args])
+    if command == 'launch':
+        os.environ['AGENT_BIOS_PACKAGE_ROOT'] = str(ROOT)
+        os.environ['AGENT_BIOS_PRIVATE_INSTRUCTIONS'] = '1'
+        os.environ.pop('AGENT_BIOS_PRIVATE_CORPUS', None)
+        sys.argv = [str(ROOT / 'launch/agent-launch.py'), *args]
+        runpy.run_path(sys.argv[0], run_name='__main__')
+        return 0
+    if command == 'learn':
+        sys.argv = [str(ROOT / 'learn/collect-learning.py'), *args]
+        runpy.run_path(sys.argv[0], run_name='__main__')
+        return 0
+    print(f'Unknown or unsupported native command: {command}', file=sys.stderr)
+    return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/compose/runtime_entry.py

@@ -0,0 +1,58 @@
+"""Application dependency entry for ordinary and isolated embeddable Python."""
+from __future__ import annotations
+import argparse
+import importlib
+import importlib.metadata
+import os
+from pathlib import Path
+import runpy
+import sys
+
+
+def main(argv=None):
+    # A Windows PowerShell 5.1 caller may prefix piped input with a UTF-8 BOM.
+    for stream, encoding in ((sys.stdin, "utf-8-sig"), (sys.stdout, "utf-8"), (sys.stderr, "utf-8")):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding=encoding, errors="strict")
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--dependencies', required=True, type=Path)
+    parser.add_argument('--probe', choices=['jsonschema'])
+    if '--script' in argv:
+        index = argv.index('--script')
+        if len(argv) <= index + 1:
+            parser.error('--script requires a file')
+        args = parser.parse_args(argv[:index])
+        script, tail = Path(argv[index+1]), argv[index+2:]
+    else:
+        args = parser.parse_args(argv)
+        script, tail = None, []
+    dependencies = args.dependencies.resolve(strict=True)
+    if not dependencies.is_dir():
+        parser.error('dependencies must be a directory')
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, str(dependencies))
+    os.environ['PYTHONDONTWRITEBYTECODE'] = '1'
+    os.environ['AGENT_BIOS_PYTHON_EXECUTABLE'] = str(Path(sys.executable).resolve())
+    os.environ['AGENT_BIOS_PYTHON_ENTRY'] = str(Path(__file__).resolve())
+    os.environ['AGENT_BIOS_PYTHON_DEPS'] = str(dependencies)
+    if args.probe:
+        module = importlib.import_module(args.probe)
+        getattr(module, 'Draft202012Validator')
+        print(importlib.metadata.version(args.probe))
+        return 0
+    if script is None:
+        parser.error('a script or probe is required')
+    script = script.resolve(strict=True)
+    if not script.is_file() or script.suffix != '.py':
+        parser.error('script must be a Python file')
+    # Isolated Python does not add the script directory to sys.path. Do this only
+    # for the explicitly selected application/helper, not a user's working directory.
+    sys.path.insert(0, str(script.parent))
+    sys.argv = [str(script), *tail]
+    runpy.run_path(str(script), run_name='__main__')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())