agent-bios 0.19.2 → 0.19.3

package/docs/instructions.md

@@ -104,6 +104,7 @@ instruction does not prove that a model read or followed it.
 | --- | --- |
 | `cli-multi-model-workflow` | multi-model CLI workflow: Default Frame, role slots/tiers, delegation mechanics, driving Codex CLI directly, cache economy, unattended-batch safety, halt/resume, handoff contract, Environment Binding |
 | `coding-staged-workflow` | staged development: design → process → implement, lightweight path, review loop, severity contract, stop conditions |
+| `ui-design` | operational task flows, evidence and authority, visual hierarchy, design tokens and layout; conditional visual-direction companion |
 | `verification-discipline` | verification depth and per-domain mix (owns the Verification Menus), case space, what a green result is worth |
 | `concept-economy` | concept-surface economy: reuse / extend / rename / split, split triggers, migration compatibility |
 | `documentation-hygiene` | where comments, history, and handoffs belong; how to phrase rules others follow |

package/docs/releases/0.19.3.md

@@ -0,0 +1,107 @@
+# agent-bios 0.19.3
+
+Release changes relative to 0.19.2.
+
+## Windows without npm or WSL
+
+Windows installs as scripts and data bound to an approved CPython 3.13, with no
+custom executable and no EXE installer. It targets machines whose application
+control permits PowerShell and Python but blocks unrecognized executables. The
+bootstrap reuses an approved CPython already on the machine, or provisions the
+pinned official embeddable runtime into an application-private folder; neither an
+existing Python nor its packages are modified.
+
+The installed commands are `agent-bios` and `agent-launch`. Each is a static
+wrapper plus a generated `.cmd` shim, because Windows does not treat `.ps1` as
+executable: without the shim a PATH directory holding only wrappers is reachable
+from PowerShell alone, and the Command Prompt, the Run box and any program that
+spawns a command find nothing while PATH is correct. The shim is generated at
+installation rather than shipped, since Authenticode cannot sign a `.cmd`; its
+bytes are fixed and recorded in the deployment's ownership inventory, so a
+modified shim is refused exactly like a modified command.
+
+`agent-bios uninstall` removes owned commands, shims, shortcuts and the owned
+PATH entry. Private instructions, session records and any preexisting Python are
+retained.
+
+## A fixed installation address
+
+The project's installation page serves one explicitly promoted release at a fixed
+URL, so publishing another release does not silently change what the address
+installs. It carries a one-line command per platform.
+
+Each command relaxes the PowerShell execution policy for the single process it
+starts, because the default policy on an unconfigured Windows client is
+Restricted and refuses a downloaded script. The machine's saved policy is not
+edited, and a domain-imposed policy still refuses through the invocation's own
+error. The Windows command names the interpreter, so it can be pasted into the
+Command Prompt or the Run box rather than only into an open PowerShell.
+
+The macOS and Linux command installs the published npm release and stops, naming
+the command that deploys the work environment: `curl | bash` gives the shell a
+pipe, and the interactive chooser needs a terminal. It also reports the case npm
+leaves behind — a successful global install whose command the caller's PATH does
+not carry.
+
+Windows releases come in two channels. Stable is Authenticode-signed and
+timestamped. Preview is published without a signing identity and refuses to run
+unless the caller adds `-AcceptUnsignedPreview`; the hashes pinned inside the
+bootstrap still guard the manifest, the application archive and the runtime
+archive.
+
+## Claude Desktop
+
+Claude Desktop opens conversations without a launcher and exposes no skill folder an
+installer can reach ahead of time, so agent-bios reaches it as a local extension the
+user installs once. `agent-bios app desktop` writes a `.mcpb` file under the private
+state root; opening it with Desktop installs a standard-library stdio MCP server with
+four tools: status, preview, use and off. agent-bios writes nothing into Desktop's own
+folders or configuration.
+
+`use` returns the saved installation selection, or a selection named in the request,
+as context for that conversation only. Nothing reaches a conversation that did not
+ask, including one already in progress. Desktop sends no conversation identity with a
+tool call, so the first preview or use returns a `session_id` that later calls pass
+back; a repeated use with it returns the same text without recording a second
+delivery. The returned text ends with an `agent-bios end` line, and reporting that
+line through status records that the text was read to its end. It does not record
+whether Desktop kept the text in the message or saved it to a file, which Desktop
+does not reveal to the extension.
+
+The file names the absolute Python that generated it, because Desktop resolves a bare
+`python3` through the login shell's PATH, which on stock macOS reaches 3.9. The server
+finds the current installation on every call, so an agent-bios update needs no new
+file; changing that Python does. Desktop delivery has no project scope, so
+project-scoped imported instructions are not included, in chat or in the Code tab.
+
+## Installation reports an unreachable launcher
+
+Installation now says when the `agent-launch` it deposits cannot be typed: when
+`~/.local/bin` is not on the shell's PATH, and when the optional zsh connection that
+routes a bare `claude` or `codex` through the launcher is off. Both used to end in a
+success message followed by `command not found`. A reachable installation reports
+nothing new. The terminal interface, the conversation client and the non-interactive
+path share the message.
+
+## Instruction guides
+
+The multi-model workflow, staged coding workflow, LLM capability boundary,
+tooling gotchas, verification discipline and UI design guides were revised, and
+lessons paid for on a separate deployment line were carried across where this
+line had not already removed them. The tooling-gotchas hook was updated with
+them.
+
+## Not established by this release
+
+No signing identity exists yet, so the published Windows channel is the unsigned
+preview. Approval by an organization policy or endpoint-protection product is not
+established: a green workflow proves the route on a hosted runner where
+PowerShell and Python are permitted. Migration of an existing EXE installation
+into the script route is refused rather than attempted.
+
+The Claude Desktop route was measured on Desktop 2.16120.0 for macOS, in chat and in
+the Code tab. It is not available on Windows, and a later Desktop version is not
+established to load the file until someone checks it.
+
+Domain knowledge, Decision memory and shared environment editions remain design
+directions rather than features of this release.

package/docs/session-model.md

@@ -46,6 +46,14 @@ and returned text do not prove native app discovery or model reading. Off stops
 further managed use, but cannot retract earlier context; a new task is needed for
 clean exclusion. Management and instruction capture do not activate task context.
 
+## Claude Desktop conversations
+
+Desktop conversations pull through the [Desktop extension](setup.md#use-instructions-in-claude-desktop).
+Use returns the selected snapshot as a tool result and records a `returned-as-context`
+receipt under an identity agent-bios mints, because Desktop sends none. An end-marker line
+reported back confirms the text was read to its end, not that it stayed inline. Nothing
+reaches a conversation that did not ask, including one already in progress.
+
 ## Storage layout
 
 From a clone, `bash install.sh install` is the same default path. The release lives

package/docs/setup.md

@@ -140,6 +140,42 @@ it does not replay uncertain operations. The agent follows the full procedure in
 [START.md](../compose/setup/START.md), including exact review preservation and verified
 entrypoint handoff. Source and reviewed artifacts remain available for recovery.
 
+## Use instructions in Claude Desktop
+
+Claude Desktop has no launcher to start its conversations and no skill folder an
+installer can reach, so agent-bios reaches it through a local extension:
+
+```bash
+agent-bios app desktop --dry-run --json
+agent-bios app desktop
+```
+
+The command writes `agent-bios.mcpb` under the private state root and prints its path.
+Open that file with Claude Desktop and confirm the installation dialog; agent-bios never
+writes into Desktop's own folders or configuration. The extension runs Python at the
+absolute path the file names — the interpreter that ran the command, which must be 3.11
+or newer. Run the command again after changing that Python; an agent-bios update alone
+needs no new file, because the extension finds the current installation on every call.
+
+In a conversation, ask for your agent-bios instructions. The assistant calls `use`, which
+returns your saved installation selection, or a selection you name in the request.
+Desktop sends no conversation identity, so the first preview or use returns a
+`session_id` that later calls in the same conversation pass back. Desktop delivery has
+no project scope: imported instructions scoped to a project folder are not included.
+
+The returned text ends with a line beginning `agent-bios end`. When the assistant reports
+that line through `status`, the receipt records that the text was read to its end. It
+does not show whether Desktop kept the text in the message or saved it to a file, and a
+delivery never reported back stays unconfirmed. Off stops further use in that
+conversation but cannot remove text already returned; start a new conversation for clean
+exclusion.
+
+The extension adds four tools to every Desktop conversation, in chat and in the Code tab.
+Remove it from Desktop's extension settings to stop that cost. The Code tab also has a
+working folder, but the extension cannot see it, so project-scoped instructions stay
+excluded there as well. This route was measured on Claude Desktop 2.16120.0 for macOS;
+Windows is not supported yet.
+
 ## Use instructions in a Codex app task
 
 Choose **Connect to the Codex app** during setup, or explicitly run:

package/docs/windows.md

@@ -0,0 +1,99 @@
+# Windows native installation
+
+The Windows build provides a per-user installer and `agent-bios.exe` with its own
+Python runtime. Node.js, npm, a system Python installation and WSL are not required
+for the Instructions library and setup. Model host CLIs remain separate dependencies.
+
+Run the Windows x64 setup executable, then open setup from the final page or the
+Start menu. A newly opened PowerShell can run `agent-bios install` or
+`agent-bios instructions`. Existing terminal processes need restarting to pick up
+user PATH changes. The installer does not change PowerShell execution policy or
+intercept bare model commands.
+
+Re-running the installer updates program files. `agent-bios install` refreshes the
+private library while retaining saved selection and personal authoring. Removing
+the application removes its owned PATH entry; private instructions and session
+records remain in the user's home. Windows and WSL have separate homes and stores.
+
+The native build is experimental until the Windows workflow's artifact and lifecycle
+checks pass for the exact candidate. Fixture tests do not establish live host login,
+model execution, app skill discovery or interactive Korean IME behavior. Native
+hooks and the shell-based multi-model worker adapters require separate Windows
+qualification. File contents are flushed; process-recovery tests are not proof of
+power-loss durability on Windows.
+
+## Script distribution with an approved Python
+
+A second Windows route installs agent-bios as scripts and data without a custom
+EXE launcher or an EXE installer. It targets organizations whose application
+control permits PowerShell and CPython but blocks unrecognized executables. The
+Windows workflow builds and exercises this route on every change; the Windows
+script release workflow publishes it as a GitHub release whose page carries the
+one-line PowerShell command for that exact release.
+
+The repository's GitHub Pages installation page also provides a shorter command
+at a fixed address. It names `powershell` and relaxes that process's execution
+policy, so it runs from the Command Prompt and the Run box as well as from an open
+PowerShell, and on a machine whose policy nobody changed. It saves the script to a
+fixed name under the temporary directory and invokes that file, rather than
+evaluating the downloaded text: the bootstrap authenticates itself through its own
+file path, which text piped into the shell does not have. The command carries no
+PowerShell variable, because a command pasted into PowerShell is expanded by that
+shell before the child starts. This convenience command trusts the HTTPS
+site for the initial script; it does not check that script's hash before execution.
+Dependent downloads still undergo the installer's checks. The fixed address
+serves an explicitly promoted release, so publishing another release does not
+silently change it. Preview commands retain `-AcceptUnsignedPreview`.
+
+The same page carries a `curl` one-liner for macOS and Linux. That route is not
+this Windows distribution: it installs the published npm package, which needs
+Node.js and python3 already present, and then names the command that deploys the
+work environment rather than opening its chooser over a pipe.
+
+Releases come in two channels. A stable release is Authenticode-signed with the
+project's release signing identity. Copy the version-specific command from its
+release page: the command carries the SHA-256 of that final bootstrap and the
+approved signer thumbprint, and checks both before invoking the saved script.
+The generic latest URL is not an execution command: a moving asset cannot match
+a fixed digest indefinitely. Release publication generates the command only after
+all script signing is complete.
+
+A preview release is published as a prerelease without a signing identity. Its
+bootstrap refuses to run unless the caller adds `-AcceptUnsignedPreview`, and
+it prints a warning when accepted; the manifest and asset hashes pinned inside
+the script are still enforced. New preview release pages carry a tag-pinned command with that flag and a
+bootstrap digest check before execution. Older preview pages may require the user
+to compare the published bootstrap digest separately; their assets are not rewritten. Each published
+command relaxes the execution policy for the process it starts, because a machine
+nobody configured refuses scripts under the default Restricted policy. Neither
+that relaxation nor anything installed edits the machine's saved policy, and a
+policy imposed by a domain still refuses: the invocation's own error names it.
+
+After caller-side verification, the bootstrap verifies the pinned release manifest
+and dependent archives before running downloaded application or runtime code. It reuses an approved
+CPython 3.13 x64 installation found on the machine, or provisions the pinned
+official embeddable runtime into an application-private folder. Neither an
+existing Python nor its packages are modified. The bootstrap adds the command
+directory to the current PowerShell session, so `agent-bios` and `agent-launch`
+work without reopening the terminal; other open terminals are unaffected.
+
+The installed commands are static signed wrappers, `agent-bios.ps1` and
+`agent-launch.ps1`, that read a local deployment binding and run the bundled
+application through the bound interpreter. Beside each one the installer writes a
+generated `.cmd` shim, because Windows does not treat `.ps1` as executable: without
+the shim the PATH entry serves PowerShell alone and `agent-bios` is unavailable in
+the Command Prompt, the Run box, and to any program that spawns a command. The
+shim is generated rather than shipped since Authenticode cannot sign a `.cmd`; its
+bytes are fixed and recorded in the deployment's ownership inventory, so a modified
+shim is refused exactly like a modified command. `agent-bios uninstall` removes owned
+commands, shims, shortcuts and the owned PATH entry; private instructions, session
+records and any preexisting Python are retained.
+
+This route is qualified on the Windows workflow runner in PowerShell 5.1 and 7
+with runner-only test signing, and the release workflow re-runs that
+qualification on the exact assets before it publishes them and then verifies
+the published command anonymously. Validation on a policy-managed machine is a
+separate step that no workflow establishes. Executable code still runs:
+PowerShell, curl and Python, plus native modules inside the dependency bundle.
+Migration of an existing EXE installation into this route is refused rather
+than attempted.

package/install.sh

@@ -1764,6 +1764,7 @@ agent-bios — manage private instructions content for explicitly activated sess
   agent-bios app         register an explicit Codex app bridge or manage per-task instructions input
   agent-bios app session use   return selected instructions as context for this Codex app task
   agent-bios app session off   stop future delivery; earlier context requires a new task to exclude
+  agent-bios app desktop       write the Claude Desktop extension file; you install it in Desktop
   agent-bios understand  list instructions learning bundles; --help shows session/discovery commands
   agent-bios shell       show the optional zsh connection status
   agent-bios shell restore   make bare claude/codex open the launcher TUI

package/launch/agent-launch.py

@@ -6,7 +6,6 @@ from __future__ import annotations
 import argparse
 import copy
 import datetime
-import fcntl
 import hashlib
 import json
 import os
@@ -24,6 +23,12 @@ import uuid
 from dataclasses import dataclass, field
 from typing import Any, Callable, NoReturn
 
+if os.name == "nt":
+    sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "compose"))
+    from host_platform import file_locks as fcntl
+else:
+    import fcntl
+
 
 TIER_ORDER = ("frontier", "helm", "workhorse", "sweep")
 # Review is not work any tier can do. A reviewer must be at least this capable; helm or
@@ -4123,6 +4128,8 @@ _UI_RUNTIME_RELEASE: Callable[[], None] | None = None
 def exec_backend(command: str, args: list[str], env: dict[str, str] | None = None) -> NoReturn:
     if _UI_RUNTIME_RELEASE is not None:
         _UI_RUNTIME_RELEASE()
+    if os.name == "nt":
+        raise SystemExit(subprocess.call([command, *args], env=os.environ.copy() if env is None else env))
     os.execve(command, [command, *args], os.environ.copy() if env is None else env)
 
 
@@ -4208,7 +4215,8 @@ def _snapshot_from_config(store, config_path, generation, host, selected, *, dry
 
 def open_instructions_studio() -> None:
     root = instructions_package_root()
-    result = subprocess.run([sys.executable, str(root / "compose/instructions.py"), "--repo", str(root)])
+    from host_platform import python_argv
+    result = subprocess.run(python_argv(root / "compose/instructions.py", "--repo", str(root)))
     if result.returncode:
         print(f"agent-launch: Instructions Studio exited {result.returncode}", file=sys.stderr)
 
@@ -6618,7 +6626,7 @@ def register_reviewer_wizard(
             # a planted symlink and truncates whatever it points at, merely by
             # opening the wizard.
             lock_fd = os.open(
-                lock_path, os.O_CREAT | os.O_WRONLY | os.O_NOFOLLOW, 0o600
+                lock_path, os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0), 0o600
             )
             with os.fdopen(lock_fd, "w") as lock_handle:
                 fcntl.flock(lock_handle, fcntl.LOCK_EX)
@@ -7667,7 +7675,7 @@ def save_preset(
     try:
         target.parent.mkdir(parents=True, exist_ok=True)
         lock_path = target.with_name(target.name + ".lock")
-        lock_fd = os.open(lock_path, os.O_CREAT | os.O_WRONLY | os.O_NOFOLLOW, 0o600)
+        lock_fd = os.open(lock_path, os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0), 0o600)
         with os.fdopen(lock_fd, "w") as lock_handle:
             fcntl.flock(lock_handle, fcntl.LOCK_EX)
             try:

package/launch/agent-launch.zsh

@@ -17,7 +17,17 @@ _agent_launch_direct() {
   # provide is handed to whatever the user's function does. `builtin` cannot be shadowed,
   # so the resolution is the one the comment above already promised.
   if [[ "$host" == "claude" && -z "${_agent_launch_private_connection:-}" ]]; then
-    builtin command claude --dangerously-skip-permissions "$@"
+    case "${1-}" in
+      # These six background-session verbs are dispatched only from the first argument:
+      # with a flag in front, `claude attach <id>` is a new session whose prompt is
+      # "attach <id>". Measured on 2.1.280 over all 21 subcommand spellings — only these
+      # six are displaced, and the other fifteen (mcp, doctor, plugin, project, auth,
+      # agents, ultrareview, update ...) parse the flag in front, which is what makes the
+      # list this short rather than every verb. They act on a session that already exists,
+      # so no permission default belongs in front of them.
+      logs|attach|stop|kill|respawn|rm) builtin command claude "$@" ;;
+      *) builtin command claude --dangerously-skip-permissions "$@" ;;
+    esac
   else
     builtin command "$host" "$@"
   fi

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-bios",
-  "version": "0.19.2",
-  "releaseDate": "2026-09-14",
+  "version": "0.19.3",
+  "releaseDate": "2026-09-29",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Stores private, editable instructions for explicitly activated sessions.",
   "bin": {
     "agent-bios": "install.sh"
@@ -64,6 +64,7 @@
     "compose/instructions_import.py",
     "compose/instructions_app.py",
     "compose/app_bridge/",
+    "compose/app_desktop/",
     "compose/instructions_transaction.py",
     "compose/instructions_understand.py",
     "compose/bootstrap/",
@@ -83,7 +84,11 @@
     "README.md",
     "INSTALL.md",
     "DEPENDENCIES.md",
-    "provenance.json"
+    "provenance.json",
+    "compose/native_cli.py",
+    "compose/host_platform.py",
+    "compose/runtime_entry.py",
+    "compose/windows_deploy.py"
   ],
   "scripts": {
     "postinstall": "printf '\\n> agent-bios installed. Deploy into this environment with:  agent-bios install\\n> Then: agent-bios verify | status | uninstall\\n\\n'",

package/provenance.json

@@ -1 +1 @@
-{"commit":"172928b728c7048ef77b810da61261594ddd75aa","committedAt":"2026-09-14T01:42:28+09:00","dirty":false}
+{"commit":"338a16e35f0b6262107a808c9cc20721b6f4facd","committedAt":"2026-09-30T20:23:32+09:00","dirty":false}