agent-bios 0.19.1 → 0.19.3

package/codex/guides/ui-design.md

@@ -0,0 +1,90 @@
+---
+guide_id: ui-design
+language: en
+status: active
+description: For designing, reviewing, or changing task flows, information layout, visual hierarchy, or interaction in operational user interfaces; keep bounded corrections proportionate.
+use_when:
+  - designing or reviewing a work application, operations tool, or interactive work surface
+  - changing information arrangement, visual hierarchy, design tokens, or interaction states
+  - preserving scope, evidence, authority, and continuity through a user interface
+---
+
+# Operational interface design and delivery
+
+Use for interfaces where people inspect evidence, compose work, make decisions
+or act on records. Match the deliverable to the user's requested stage and scope.
+A clear text correction needs that correction and a proportionate check.
+
+1. **Establish what the sources mean now.** Separate implemented behavior,
+   accepted requirements, proposed design choices and illustrative states.
+   Reconcile amendments and decisions before reusing an older screen. A newer
+   date alone does not establish authority. Keep material contradictions and
+   unknowns visible instead of silently choosing a convenient interpretation.
+
+2. **Preserve requested coverage; bound the work at the right level.** Identify
+   the operator, outcome and evidence that would complete this deliverable.
+   Distinguish people consuming work context from those authoring or managing
+   it; do not invent their visit frequency or force a common starting screen.
+   For a complete design request, cover the required operations even when their
+   backend is not built; specify their subjects, inputs, effects, dependencies
+   and recovery rather than claiming implementation. For a bounded change,
+   complete the requested path before expanding neighboring features. Include
+   adjacent repairs when that path depends on them or this change causes a
+   regression, and state why. An unavailable implementation does not erase a
+   requested design contract.
+
+3. **Organize around a meaningful next decision.** Show the working scope,
+   evidence to compare, current state, available action and resulting next step
+   together. Internal modules or protocol phases are not automatically menus
+   or buttons. Combine preparation steps behind one authorized intent when no
+   user choice is needed, while keeping distinct outcomes understandable. Use
+   the team's visual language to assign emphasis according to the task, and
+   make typography, spacing, color and boundaries express meaningful
+   relationships. Test whether actual task content is prominent at the target
+   size; decorative summaries must earn their space. When layout uncertainty
+   matters, compare arrangements at the lowest useful fidelity, explaining the
+   task tradeoff and what evidence would change the choice.
+
+   When a new visual direction or a material arrangement decision remains
+   unresolved, use
+   `${CODEX_HOME:-$HOME/.codex}/guides/ui-design/visual-direction.md`.
+   An established direction or a bounded correction does not require new
+   reference research or multiple designs.
+
+4. **Keep qualifications with the thing they qualify.** Preserve applicable
+   conditions, exceptions, units, source/version, time meaning and affected
+   scope through summaries, edits, comparisons and exports. Keep independent
+   dimensions separate. Missing evidence is not an empty result or a zero, and
+   an index or relationship view is not proof of its underlying body or meaning.
+   Expand technical detail when useful without hiding a consequential limit.
+
+5. **Make each action's authority and effect precise.** Name the exact target,
+   base and changed content when reviewing a change. Recheck a changed base or
+   permission instead of carrying approval onto different input. Distinguish
+   selection, saved draft, approval, execution and recipient use as applicable;
+   one positive state does not prove the next. Preserve request identity when
+   an outcome is uncertain and reconcile its actual result before retrying.
+   UI controls reflect the existing authoritative policy; they do not create it.
+   If policy is unsettled, label proposed choices and the responsible decision
+   owner rather than implying permission or omitting the required design.
+
+6. **Carry the same work across views and people.** Preserve the draft, target,
+   review/request identity and return context when moving between surfaces.
+   Equivalent outcomes need suitable representations, not identical layouts or
+   duplicated business rules. Provide keyboard and structured alternatives for
+   necessary spatial interactions. Verify evidence for the actual recipient;
+   another worker's receipt does not establish their access or delivery.
+
+7. **Verify this deliverable, then finish it.** Walk a design's concrete scenario
+   and relevant exceptions against its sources; inspect its proposed composition.
+   For working changes, exercise the changed runtime path, relevant failures,
+   keyboard and recovery. When a visual change is material, inspect the affected
+   composition with representative content and relevant states at the target
+   size, distinguishing token changes from changes to information arrangement.
+   Check that visual, reading and focus order remain coherent across layouts.
+   Report visual preference separately from observed task performance. Keep
+   simulation, observed runtime and user evidence distinct. Once the required
+   checks are complete, leave the result, material decisions, source bindings
+   and remaining work in ordinary team artifacts. Keep private facts within
+   their permitted boundary. Choose dependencies only when a requirement
+   demands a decision, using the supported environment first.

package/codex/guides/verification-discipline.md

@@ -77,6 +77,7 @@ cheapest one to write.
 - A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
 - Multi-stage pipelines with nondeterministic stages: a final-output diff cannot attribute an effect or a regression to a stage — it conflates the change with run-to-run variance. Persist every stage's output, tabulate what each creates, may edit, and only guards, restrict the suspects to the stages that edit the content in question, and find the first stage where the intended effect disappears or the defect appears. Fix there, preferring a structural recheck over another prompt-level instruction that already failed.
 - Before/after comparisons: pin the input to an immutable copy — a snapshot or versioned artifact — and run both arms against it, because a live artifact (a growing log, a regenerated upstream stage) drifts between runs and any diff over it, a matching one included, is evidence of nothing; when the arms are metered, restore the baseline's exact upstream inputs and re-run only the changed stage. This is input identity, not the separate unit-and-denominator basis rule.
+- Cost figures from provider usage records: before pricing, map every provider's token fields onto one schema — uncached input, cache read, cache write, output. Some providers report input as a total that already includes cached tokens: treating that total as uncached input and then adding the cache-read field again counts the cached portion twice, while charging the inclusive total once at the full rate misprices that portion instead. Other providers exclude cached tokens from the input field. When a provider reports or prices cache writes separately, keep them in their own field. Confirm each provider's field meaning against its own usage documentation or a known sample, never by analogy with another provider, and derive the cache hit rate from the normalized fields.
 - Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
 - Sandbox, replay, or re-adjudication runs on production-derived config: enumerate every outbound channel the stage can reach — publish, upload, notify, external write — and disable or redirect each one before the run, proving each disarm fires as you would prove a path guard; a guard on the input or target path alone leaves egress armed. Fingerprint every external destination before the run and diff it after, so an escaped write is caught by the run rather than by a recipient.
@@ -151,6 +152,11 @@ produce a green with no evidence behind it:
 - **The suspiciously fast or empty run.** When a check goes green unexpectedly quickly, or reports
   nothing at all, dump what it actually ran over before believing it. A harness that crashed early
   and one that found nothing produce the same exit code.
+- **The verdict that ran before its checks.** If a runner computes or prints its overall verdict
+  before all checks finish, later failures cannot change it. Accumulate one failure count across
+  every check, then compute the verdict and exit status once, after the last check. Read a
+  multi-check run from that final count and an exit status verified to derive from it — never from
+  `tail` or collapsed last lines, which hide failures printed earlier.
 - **The control that failed by crashing.** A negative control is evidence only when it fails
   through the assertion it names: a traceback and a caught violation share an exit code, and an
   early crash can pre-empt every control after it. Treat each traceback in a control run as a
@@ -173,7 +179,10 @@ produce a green with no evidence behind it:
 - **The mutant that never ran.** A mutation verdict counts only if the mutant is valid: it
   compiled, sits on a path the exercised test traverses, and changes the guarded behavior, not
   healed downstream or coinciding with a default. The runner must report build failure,
-  unreachable, and equivalent distinctly from KILLED and SURVIVED, and halt on a moved anchor.
+  unreachable, equivalent, and timed out distinctly from KILLED and SURVIVED, and halt on a moved
+  anchor. A timeout is not a kill: it moves with machine load, so set the limit well above the
+  unmutated suite's runtime and accept a verdict only when repeated runs agree on which mutants
+  timed out.
   More tests red than the mutation should touch indicts it; classify a survivor (rebuild,
   discard, genuine gap) before writing a test. **Equivalent is a verdict about the probe as
   much as the mutant**: a probe that is dead or returns a constant reports every mutant as

package/compose/app_bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-bios
-description: Set up or reconfigure agent-bios through conversation, manage its private corpus, or explicitly use corpus context in this Codex task. Loading this skill alone does not activate corpus content.
+description: Set up or reconfigure agent-bios through conversation, manage its private instructions, or explicitly use instructions context in this Codex task. Loading this skill alone does not activate instructions content.
 ---
 
 # agent-bios in this task
@@ -11,7 +11,7 @@ the absolute path to that helper; pass it as a quoted shell argument or set
 `BRIDGE` in the same tool call. Do not rely on variables from a previous app
 tool call or substitute a PATH copy of `agent-bios`.
 
-Distinguish the user's request before reading any corpus body:
+Distinguish the user's request before reading any instructions body:
 
 - **Install, reconfigure or resume setup:** run
   `python3 "$BRIDGE" setup start`, read its returned `guide_path`, and follow
@@ -20,12 +20,12 @@ Distinguish the user's request before reading any corpus body:
   returned choices in the app conversation,
   using a native question control when the current host exposes one and ordinary
   questions otherwise. Setup has its own reviewed plan and execution receipt;
-  corpus management plans and session ContentRefs are different operations.
-  Installation, registration and source capture do not authorize corpus use in
+  instructions management plans and session ContentRefs are different operations.
+  Installation, registration and source capture do not authorize instructions use in
   this task. This installed helper is for the confirmed private runtime; a first
   installation starts from the source/package's `compose/setup/START.md`, without
   requiring this skill to exist.
-- **Use corpus in this task:** run `python3 "$BRIDGE" session preview --json`
+- **Use instructions in this task:** run `python3 "$BRIDGE" session preview --json`
   and then `python3 "$BRIDGE" session use --expected-content-ref REF --json`,
   using the returned ContentRef. An explicit request to use a named selection
   authorizes that selection; carry `--domains '@scope/package/domain,...'` on
@@ -33,18 +33,18 @@ Distinguish the user's request before reading any corpus body:
   Read the complete returned `instruction_text` and use it as the user's chosen
   task context, subject to higher-priority instructions. Do not claim it was
   loaded if tool output was truncated; retrieve the exact retained snapshot
-  through the helper's `corpus snapshot --content-ref REF --json` operation and
+  through the helper's `instructions snapshot --content-ref REF --json` operation and
   read it fully in bounded chunks.
-- **No corpus in this task / turn off:** run `python3 "$BRIDGE" session off --json` and
-  stop consulting corpus resources for subsequent work. Off before first use
-  returns no corpus body. After use, already delivered context cannot be erased;
+- **No instructions in this task / turn off:** run `python3 "$BRIDGE" session off --json` and
+  stop consulting instructions resources for subsequent work. Off before first use
+  returns no instructions body. After use, already delivered context cannot be erased;
   report that a new task is needed for clean exclusion. Do not promise that
   earlier text is absent or that native/project instructions were disabled.
 - **Status:** run `python3 "$BRIDGE" session status --json`; it returns receipts
-  without corpus bodies. Each task starts off and needs its own explicit use.
+  without instructions bodies. Each task starts off and needs its own explicit use.
 - **Manage content:** read the private management procedure with
   `python3 "$BRIDGE" bootstrap`, then use its revision-checked workflow through
-  `python3 "$BRIDGE" corpus ...`. Management changes future snapshots; it does
+  `python3 "$BRIDGE" instructions ...`. Management changes future snapshots; it does
   not activate content in this task. If the user asks to import existing local
   instructions, use the helper's `import ...` commands after inspecting
   `python3 "$BRIDGE" import --help`.
@@ -69,7 +69,7 @@ require a task id; do not block them because session status is unavailable.
 
 The receipt labels delivery `returned-as-context`. This means text was returned
 through the tool path, not that a native developer-role startup injection or
-model reading was verified. Corpus use enables no hooks, agents, permissions or
+model reading was verified. Instructions use enables no hooks, agents, permissions or
 global/project instruction-file edits. Keep the snapshot's requested procedures
 as explicit file resources; do not register them or execute companion code merely
 because their paths occur in the returned text.

package/compose/app_bridge/scripts/bridge.py

@@ -10,9 +10,13 @@ import sys
 
 
 def main() -> int:
+    # 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")
     root = Path(__file__).resolve().parents[1]
     expected = {"SKILL.md", "agents/openai.yaml", "scripts/bridge.py",
-                "scripts/corpus_transaction.py", "bridge.json"}
+                "scripts/instructions_transaction.py", "scripts/host_platform.py", "bridge.json"}
     try:
         paths = list(root.rglob("*"))
         if any(path.is_symlink() for path in paths):
@@ -32,7 +36,9 @@ def main() -> int:
             if not isinstance(config.get(key), str) or not Path(config[key]).is_absolute():
                 raise RuntimeError("registered bridge needs absolute private roots")
         sys.dont_write_bytecode = True
-        from corpus_transaction import confirmed_release, guard_pending, reject_symlink_ancestors
+        sys.path.insert(0, str(root / "scripts"))
+        from host_platform import cli_argv, python_argv, runtime_environment
+        from instructions_transaction import confirmed_release, guard_pending, reject_symlink_ancestors
         state = Path(config["state_root"])
         reject_symlink_ancestors(state)
         reject_symlink_ancestors(Path(config["user_root"]))
@@ -41,8 +47,10 @@ def main() -> int:
         reject_symlink_ancestors(release)
         env = dict(os.environ)
         env.update({"HOME": config["home"], "AGENT_BIOS_STATE_DIR": config["state_root"],
+                    "AGENT_BIOS_INSTRUCTIONS_DIR": config["user_root"],
                     "AGENT_BIOS_CORPUS_DIR": config["user_root"],
-                    "AGENT_BIOS_PACKAGE_ROOT": str(release), "AGENT_BIOS_PRIVATE_CORPUS": "1",
+                    "AGENT_BIOS_PACKAGE_ROOT": str(release), "AGENT_BIOS_PRIVATE_INSTRUCTIONS": "1",
+                    "AGENT_BIOS_PRIVATE_CORPUS": "1",
                     "AGENT_BIOS_LEGACY_INSTALL": "0",
                     "PYTHONDONTWRITEBYTECODE": "1"})
         if "launch_venv" in config:
@@ -50,21 +58,38 @@ def main() -> int:
             if not isinstance(value, str) or (value and not Path(value).is_absolute()):
                 raise RuntimeError("registered bridge has an invalid managed runtime path")
             env["AGENT_LAUNCH_VENV"] = value
+        if "python_binding" in config:
+            bound = config["python_binding"]
+            if not isinstance(bound, dict):
+                raise RuntimeError('registered Python binding must be an object')
+            env.update(runtime_environment(bound))
         args = sys.argv[1:]
         command = args[0] if args else "session"
         tail = args[1:] if args else ["status", "--json"]
         if command == "bootstrap":
-            print((release / "compose/bootstrap/SKILL.md").read_text(encoding="utf-8"), end="")
+            text = (release / "compose/bootstrap/SKILL.md").read_text(encoding="utf-8")
+            if os.name == "nt":
+                prefix = "& '" + sys.executable.replace("'", "''") + "' '" + str(root / "scripts/bridge.py").replace("'", "''") + "' instructions"
+                text = text.replace('bash "$AGENT_BIOS_PACKAGE_ROOT/install.sh" instructions', prefix).replace('agent-bios instructions', prefix)
+            print(text, end="")
             return 0
         if command == "tui":
-            argv = ["/bin/bash", str(release / "install.sh"), "corpus", *tail]
-        elif command in {"setup", "corpus", "import", "learn"}:
-            argv = ["/bin/bash", str(release / "install.sh"), command, *tail]
+            operation = "instructions" if (release / "compose/instructions.py").is_file() else "corpus"
+            argv = python_argv(release / 'compose/native_cli.py', operation, *tail, environ=env) if os.name == 'nt' else cli_argv(release, operation, *tail)
+        elif command in {"setup", "instructions", "corpus", "import", "learn"}:
+            if command == "instructions" and not (release / "compose/instructions.py").is_file():
+                command = "corpus"
+            argv = python_argv(release / 'compose/native_cli.py', command, *tail, environ=env) if os.name == 'nt' else cli_argv(release, command, *tail)
         elif command == "session":
-            argv = [sys.executable, str(release / "compose/corpus_app.py"), "--repo", str(release),
-                    "--state-dir", config["state_root"], "--user-dir", config["user_root"], "session", *tail]
+            manager = release / "compose/instructions_app.py"
+            if not manager.is_file():
+                manager = release / "compose/corpus_app.py"
+            argv = python_argv(manager, "--repo", str(release), "--state-dir", config["state_root"], "--user-dir", config["user_root"], "session", *tail, environ=env)
         else:
-            raise RuntimeError("bridge supports setup, session, corpus, import, learn, bootstrap and tui")
+            raise RuntimeError("bridge supports setup, session, instructions, import, learn, bootstrap and tui")
+        if os.name == "nt":
+            import subprocess
+            return subprocess.call(argv, env=env)
         os.execve(argv[0], argv, env)
     except (OSError, RuntimeError, ValueError, KeyError) as exc:
         print(f"agent-bios app bridge: {exc}", file=sys.stderr)

package/compose/app_desktop/server.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""Claude Desktop MCP server for explicit agent-bios instructions delivery.
+
+It is a transport at the same layer as `compose/app_bridge/scripts/bridge.py`: it
+owns no selection, ContentRef, receipt or identifier. Each tool call resolves the
+confirmed private release again and runs that release's
+`compose/instructions_app.py session <op> --host claude-desktop` in a child
+process, so a package update answers from the next call and this long-lived
+process holds nothing across requests.
+
+Protocol 2025-11-25 over stdio, the revision Desktop speaks; a call that arrives
+without a handshake is still answered, because nothing here depends on one.
+Standard library only; stdout carries protocol messages and nothing else.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+from typing import Any
+
+HERE = Path(__file__).resolve().parent
+PROTOCOL = "2025-11-25"
+KNOWN_PROTOCOLS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+CALL_TIMEOUT = 120
+
+_SESSION_ID = {"type": "string", "description": "The session_id an earlier preview or use returned in this conversation."}
+_DOMAINS = {"type": "array", "items": {"type": "string"},
+            "description": "Only when the user names a selection; omit to use their saved installation selection."}
+# One owner: the bundle builder reads this list for the manifest.
+TOOLS = [
+    {"name": "status",
+     "description": "Show whether agent-bios instructions were delivered to this conversation. After reading a "
+                    "delivery to its last line, call this with end_marker_seen set to that line.",
+     "inputSchema": {"type": "object", "properties": {
+         "session_id": _SESSION_ID,
+         "end_marker_seen": {"type": "string", "description": "The delivery's last line, exactly as read."}},
+         "required": ["session_id"]}},
+    {"name": "preview",
+     "description": "Describe the agent-bios work environment use would return, without delivering it. "
+                    "Call only when the user asks for their agent-bios instructions or environment.",
+     "inputSchema": {"type": "object", "properties": {"session_id": _SESSION_ID, "domains": _DOMAINS}}},
+    {"name": "use",
+     "description": "Return the user's selected agent-bios work environment as context for this conversation. "
+                    "Call only when the user asks for it.",
+     "inputSchema": {"type": "object", "properties": {
+         "session_id": _SESSION_ID, "domains": _DOMAINS,
+         "expected_content_ref": {"type": "string", "description": "The content_ref preview returned, to refuse a changed snapshot."}}}},
+    {"name": "off",
+     "description": "Stop agent-bios delivery in this conversation. Text already returned stays in context.",
+     "inputSchema": {"type": "object", "properties": {"session_id": _SESSION_ID}, "required": ["session_id"]}},
+]
+
+
+class ToolError(RuntimeError):
+    pass
+
+
+def _config() -> dict[str, Any]:
+    config = json.loads((HERE / "desktop.json").read_text(encoding="utf-8"))
+    if config.get("schema_version") != 1:
+        raise ToolError("this agent-bios Desktop bundle has an unsupported configuration; generate it again with agent-bios app desktop")
+    for key in ("home", "state_root", "user_root"):
+        if not isinstance(config.get(key), str) or not Path(config[key]).is_absolute():
+            raise ToolError("this agent-bios Desktop bundle needs absolute private roots")
+    return config
+
+
+def _string(arguments: dict[str, Any], key: str) -> str | None:
+    value = arguments.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise ToolError(f"{key} must be a nonempty string")
+    return value.strip()
+
+
+def _argv(operation: str, arguments: dict[str, Any]) -> list[str]:
+    tail = ["--host", "claude-desktop"]
+    session = _string(arguments, "session_id")
+    if session is not None:
+        tail += ["--session", session]
+    if operation in {"preview", "use"} and arguments.get("domains") is not None:
+        domains = arguments["domains"]
+        if not isinstance(domains, list) or not domains or not all(isinstance(v, str) and v.strip() for v in domains):
+            raise ToolError("domains must be a nonempty list of selection names")
+        tail += ["--domains", ",".join(v.strip() for v in domains)]
+    if operation == "use" and (ref := _string(arguments, "expected_content_ref")) is not None:
+        tail += ["--expected-content-ref", ref]
+    if operation == "status" and (marker := _string(arguments, "end_marker_seen")) is not None:
+        tail += ["--end-marker-seen", marker]
+    return tail
+
+
+def run_session(operation: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    config = _config()
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, str(HERE))
+    from host_platform import python_argv, runtime_environment
+    from instructions_transaction import confirmed_release, guard_pending, reject_symlink_ancestors
+    state = Path(config["state_root"])
+    reject_symlink_ancestors(state)
+    reject_symlink_ancestors(Path(config["user_root"]))
+    guard_pending(state)
+    release = confirmed_release(state)
+    reject_symlink_ancestors(release)
+    env = dict(os.environ)
+    env.update({"HOME": config["home"], "AGENT_BIOS_STATE_DIR": config["state_root"],
+                "AGENT_BIOS_INSTRUCTIONS_DIR": config["user_root"], "AGENT_BIOS_CORPUS_DIR": config["user_root"],
+                "AGENT_BIOS_PACKAGE_ROOT": str(release), "AGENT_BIOS_PRIVATE_INSTRUCTIONS": "1",
+                "AGENT_BIOS_PRIVATE_CORPUS": "1", "AGENT_BIOS_LEGACY_INSTALL": "0",
+                "PYTHONDONTWRITEBYTECODE": "1"})
+    if "python_binding" in config:
+        if not isinstance(config["python_binding"], dict):
+            raise ToolError("the bundle's Python binding must be an object")
+        env.update(runtime_environment(config["python_binding"]))
+    manager = release / "compose/instructions_app.py"
+    argv = python_argv(manager, "--repo", str(release), "--state-dir", config["state_root"],
+                       "--user-dir", config["user_root"], "--json", "session", operation,
+                       *_argv(operation, arguments), environ=env)
+    try:
+        done = subprocess.run(argv, env=env, stdin=subprocess.DEVNULL, capture_output=True,
+                              text=True, encoding="utf-8", timeout=CALL_TIMEOUT)
+    except subprocess.TimeoutExpired as exc:
+        raise ToolError(f"agent-bios did not answer within {CALL_TIMEOUT} seconds") from exc
+    if done.returncode != 0:
+        raise ToolError(done.stderr.strip() or f"agent-bios session {operation} failed")
+    try:
+        return json.loads(done.stdout)
+    except ValueError as exc:
+        raise ToolError("agent-bios returned an unreadable session result") from exc
+
+
+def _scope(result: dict[str, Any]) -> str:
+    return ("Project scope: none. Desktop names no project, so project-scoped imported "
+            "instructions are not included.") if result.get("project_scope") == "none" else ""
+
+
+def _size_note(result: dict[str, Any]) -> str:
+    if not result.get("host_may_save_to_file"):
+        return ""
+    return (f"{result['instruction_bytes']} bytes is above the smallest limit Desktop has kept inline; "
+            "Desktop may save this result to a file instead of showing it.")
+
+
+def _unavailable(result: dict[str, Any]) -> str:
+    items = result.get("unavailable") or []
+    names = [f"{item.get('ref')} ({item.get('reason')})" if isinstance(item, dict) else str(item) for item in items]
+    return "Not included: " + "; ".join(names) if names else ""
+
+
+def render(operation: str, result: dict[str, Any]) -> str:
+    session = result.get("session_id")
+    if operation == "use" and isinstance(result.get("instruction_text"), str):
+        lines = [f"agent-bios session_id: {session} — pass it to status, off and use in this conversation.",
+                 f"content_ref: {result['content_ref']}", _scope(result), _size_note(result)]
+        if result.get("repeat"):
+            lines.append("Same snapshot as this conversation's latest delivery; returned again with its existing receipt.")
+        lines.append(_unavailable(result))
+        lines.append("The text below ends with a line beginning 'agent-bios end'. After reading to it, "
+                     "call status with that whole line as end_marker_seen.")
+        header = "\n".join(line for line in lines if line)
+        return f"{header}\n\n{result['instruction_text'].rstrip()}\n\n{result['end_marker']}"
+    if operation == "preview":
+        if result.get("selection_mode") == "none":
+            return f"agent-bios session_id: {session}\nNo instructions are selected; use would return nothing."
+        lines = [f"agent-bios session_id: {session} — pass it to use, status and off in this conversation.",
+                 f"content_ref: {result['content_ref']}",
+                 f"Size: {result.get('instruction_characters')} characters, {result.get('instruction_bytes')} bytes.",
+                 _scope(result), _size_note(result),
+                 _unavailable(result),
+                 "Nothing was delivered. Call use to return this text."]
+        return "\n".join(line for line in lines if line)
+    lines = [f"agent-bios session_id: {session}",
+             f"Delivery: {'on' if result.get('enabled') else 'off'}; "
+             f"deliveries recorded: {len(result.get('deliveries', []))}.",
+             f"Latest delivery read to its end: {'yes' if result.get('latest_end_confirmed') else 'no'}."
+             if result.get("ever_delivered") else "",
+             result.get("message", "")]
+    return "\n".join(line for line in lines if line)
+
+
+def call_tool(params: dict[str, Any]) -> dict[str, Any]:
+    name = params.get("name")
+    arguments = params.get("arguments") or {}
+    if name not in {tool["name"] for tool in TOOLS}:
+        return {"content": [{"type": "text", "text": f"unknown tool: {name}"}], "isError": True}
+    if not isinstance(arguments, dict):
+        return {"content": [{"type": "text", "text": "arguments must be an object"}], "isError": True}
+    try:
+        text = render(name, run_session(name, arguments))
+        return {"content": [{"type": "text", "text": text}], "isError": False}
+    except (ToolError, OSError, RuntimeError, ValueError, KeyError) as exc:
+        return {"content": [{"type": "text", "text": f"agent-bios: {exc}"}], "isError": True}
+
+
+def respond(message: Any) -> dict[str, Any] | None:
+    if not isinstance(message, dict):
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "expected one JSON-RPC request object"}}
+    method, ident = message.get("method"), message.get("id")
+    params = message.get("params") if isinstance(message.get("params"), dict) else {}
+    if method == "initialize":
+        asked = params.get("protocolVersion")
+        result: dict[str, Any] = {"protocolVersion": asked if asked in KNOWN_PROTOCOLS else PROTOCOL,
+                                  "capabilities": {"tools": {}},
+                                  "serverInfo": {"name": "agent-bios", "version": _version()}}
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = {"tools": TOOLS}
+    elif method == "tools/call":
+        result = call_tool(params)
+    elif ident is None:
+        return None
+    else:
+        return {"jsonrpc": "2.0", "id": ident, "error": {"code": -32601, "message": f"method not supported: {method}"}}
+    return None if ident is None else {"jsonrpc": "2.0", "id": ident, "result": result}
+
+
+def _version() -> str:
+    try:
+        return str(json.loads((HERE.parent / "manifest.json").read_text(encoding="utf-8"))["version"])
+    except (OSError, ValueError, KeyError):
+        return "unknown"
+
+
+def main() -> int:
+    for stream in (sys.stdin, sys.stdout):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            message = json.loads(line)
+        except ValueError:
+            reply: dict[str, Any] | None = {"jsonrpc": "2.0", "id": None,
+                                            "error": {"code": -32700, "message": "parse error"}}
+        else:
+            reply = respond(message)
+        if reply is not None:
+            sys.stdout.write(json.dumps(reply, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/compose/assemble.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Per-selection assembler: canonical corpus + domains.json -> deployed trees.
+"""Per-selection assembler: canonical instructions + domains.json -> deployed trees.
 
 Claude side (central-managed tree, overwritten on every run):
   <claude-dir>/central/bundle.md     core+infra+selected-domain bullets, the
@@ -174,7 +174,7 @@ def filtered_files(manifest, key, selection):
 
 
 def author_only(path):
-    """Does this file's own frontmatter say it is for the corpus author?
+    """Does this file's own frontmatter say it is for the instructions author?
 
     A guide declaring `audience: author` documents a step only the author can
     perform, and names repository paths that exist in a checkout and nowhere
@@ -666,7 +666,7 @@ def seed_entry(claude_dir, legacy_monolith, prior_deployed=(), dry=False):
     Telling those apart used to be a byte-comparison against THIS commit's monolith, which
     recognizes only a re-install of the same release. Anyone upgrading from an earlier one had
     that release's monolith on disk — our file, not theirs — and it was reported as user-owned,
-    so the import line was never added and the corpus did not load until they edited it by hand.
+    so the import line was never added and the instructions did not load until they edited it by hand.
 
     `prior_deployed` is the previous install's manifest, which is the repo's existing answer to
     "did we write this": deploy_file records every destination it writes, and the pre-unification
@@ -800,7 +800,7 @@ def main():
 
     if args.remove_owned:
         # No domains gate: removal does not depend on the manifest being well-formed, and an
-        # uninstall that refuses to run because the corpus is mid-edit would strand the user.
+        # uninstall that refuses to run because the instructions are mid-edit would strand the user.
         # That was the claim; the parse sat ABOVE this branch and ran first, so a malformed
         # domains.json raised out of uninstall before the branch that does not need it. The
         # two halves of the removal need it differently: the Codex region is bounded by our
@@ -823,7 +823,7 @@ def main():
     gate = subprocess.run([sys.executable, str(REPO / "compose" / "check-domains.py")],
                           capture_output=True, text=True)
     if gate.returncode != 0:
-        die("domains gate FAILED — fix manifest/corpus first:\n" + gate.stdout + gate.stderr)
+        die("domains gate FAILED — fix manifest/instructions first:\n" + gate.stdout + gate.stderr)
     if args.domains is not None:
         selection = frozenset(d for d in args.domains.split(",") if d)
     else: