agent-bios 0.15.0 → 0.16.0

package/compose/assemble.py

@@ -206,6 +206,96 @@ def author_only(path):
                for ln in front.splitlines() if ln.startswith("audience:"))
 
 
+class GuideMemberError(ValueError):
+    """A guide source tree does not have the primary-plus-companions shape."""
+
+
+def _guide_primaries(root):
+    """Return the top-level primary Markdown files after validating `root`.
+
+    A guide is one manifest item even when it has resources.  Its primary remains the
+    top-level ``<name>.md`` and its optional resource tree is exactly ``<name>/``.  This
+    small structural contract lets delivery and every author-side consumer agree on the
+    member set without adding a second manifest entry for each resource.
+
+    The source is shipped verbatim for non-Markdown resources, so accepting a symlink
+    (or a FIFO/device) would make the shipped package's bytes depend on the checkout at
+    copy time.  Refuse those shapes before a caller starts copying anything.
+    """
+    if root.is_symlink() or not root.is_dir():
+        raise GuideMemberError(f"guide root must be a real directory: {root}")
+    primaries = []
+    entries = sorted(root.iterdir(), key=lambda p: p.name)
+    for path in entries:
+        if path.is_symlink():
+            raise GuideMemberError(f"guide source must not contain symlinks: {path}")
+        if path.is_file():
+            if path.suffix != ".md":
+                raise GuideMemberError(
+                    f"unsupported top-level guide resource {path}; companion resources belong "
+                    f"under a same-stem directory")
+            primaries.append(path.name)
+            continue
+        if path.is_dir():
+            primary = root / f"{path.name}.md"
+            if not primary.is_file() or primary.is_symlink():
+                raise GuideMemberError(
+                    f"orphan guide companion tree {path}; expected primary {primary.name}")
+            continue
+        raise GuideMemberError(f"unsupported guide source path: {path}")
+    if not primaries:
+        raise GuideMemberError(f"guide root has no primary Markdown files: {root}")
+    return primaries
+
+
+def _tree_members(root):
+    """Return regular-file members under `root`, refusing every other entry type."""
+    out = []
+    for path in sorted(root.iterdir(), key=lambda p: p.name):
+        if path.is_symlink():
+            raise GuideMemberError(f"guide companion tree must not contain symlinks: {path}")
+        if path.is_file():
+            out.append(path)
+        elif path.is_dir():
+            children = _tree_members(path)
+            if not children:
+                raise GuideMemberError(f"empty guide companion directory: {path}")
+            out.extend(children)
+        else:
+            raise GuideMemberError(f"unsupported guide companion path: {path}")
+    return out
+
+
+def guide_members(root: pathlib.Path, name: str) -> list[str]:
+    """Return one guide item's source-relative files in deterministic order.
+
+    ``name`` is the manifest's existing top-level ``*.md`` key.  The primary is first;
+    optional companions live below ``Path(name).stem/`` and retain their relative path.
+    Validating all top-level entries on every call intentionally catches an orphan companion
+    tree even when the caller happens to ask about a different guide.
+    """
+    root = pathlib.Path(root)
+    primaries = _guide_primaries(root)
+    if name not in primaries or pathlib.PurePath(name).name != name or not name.endswith(".md"):
+        raise GuideMemberError(f"guide primary {name!r} is not a top-level Markdown file in {root}")
+    members = [name]
+    companion = root / pathlib.Path(name).stem
+    if companion.exists():
+        if companion.is_symlink() or not companion.is_dir():
+            raise GuideMemberError(f"guide companion {companion} must be a real directory")
+        companion_members = _tree_members(companion)
+        if not companion_members:
+            raise GuideMemberError(f"empty guide companion tree: {companion}")
+        members.extend(str(path.relative_to(root).as_posix()) for path in companion_members)
+    return members
+
+
+def guide_member_map(root: pathlib.Path) -> dict[str, list[str]]:
+    """Every guide's exact source-relative member paths, keyed by its manifest key."""
+    root = pathlib.Path(root)
+    return {name: guide_members(root, name) for name in _guide_primaries(root)}
+
+
 def copy_filtered(src_dir, names, dest, rewrite=None, dry=False, backup=None):
     """Write the selected files, and remove the ones we deployed and no longer select.
 
@@ -260,6 +350,160 @@ def copy_filtered(src_dir, names, dest, rewrite=None, dry=False, backup=None):
         target.write_text(body, encoding="utf-8")
 
 
+def _backup_member(path, backup, reason):
+    """Keep a recoverable copy of one exact deployed member before changing it."""
+    if backup is None:
+        return
+    kept = backup / reason / str(path).lstrip("/")
+    kept.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(path, kept)
+
+
+def validate_guide_destination_members(dest, members):
+    """Refuse member paths that would traverse a symlink below the chosen guide root.
+
+    ``dest`` itself is deliberately outside this check: a user may configure the whole
+    guides root as a symlink, and that pre-existing top-level behavior is not claimed by a
+    bundle.  A same-stem companion directory below it is different — following it would let
+    an install replace or deselect a file outside the configured root.  Validate every
+    source-owned member up front, including currently deselected ones, so no earlier member
+    can be changed before a later nested path reveals the unsafe shape.
+    """
+    dest = pathlib.Path(dest)
+    for rel in sorted(set(members)):
+        target = dest / rel
+        if target.is_symlink():
+            die(f"refusing guide member destination symlink: {target}")
+        ancestor = target.parent
+        while ancestor != dest:
+            if ancestor.is_symlink():
+                die(f"refusing guide member ancestor symlink: {ancestor}")
+            if ancestor.exists() and not ancestor.is_dir():
+                die(f"guide member ancestor is not a directory: {ancestor}")
+            ancestor = ancestor.parent
+
+
+def prior_guide_candidates(prior_deployed, dest, current_members):
+    """Former guide paths a prior manifest names but the current source does not.
+
+    Historic manifests over-claimed guide directories, so a prior row is not deletion
+    authority.  This parser only bounds the warning to the configured guide root; current
+    source members retain the existing source-derived cleanup rule in ``copy_guide_members``.
+    """
+    dest = pathlib.Path(dest)
+    current = set(current_members)
+    candidates = set()
+    for raw in prior_deployed:
+        if not raw or "\0" in raw:
+            continue
+        try:
+            path = pathlib.Path(raw)
+        except (TypeError, ValueError):
+            continue
+        if not path.is_absolute():
+            continue
+        try:
+            rel = path.relative_to(dest)
+        except ValueError:
+            continue
+        # `relative_to` is lexical and preserves `..`; never allow a handcrafted manifest
+        # row to escape the configured root when the target path is joined below.
+        if not rel.parts or any(part in ("", ".", "..") for part in rel.parts):
+            continue
+        rel_text = rel.as_posix()
+        if rel_text not in current:
+            candidates.add(rel_text)
+    return sorted(candidates)
+
+
+def disclose_prior_guide_remnants(dest, candidates, dry=False):
+    """Report, but never alter, prior-only guide paths that remain on disk.
+
+    The existing installer keeps the previous manifest as its recovery record.  A user can
+    inspect that record and remove a remnant manually if it is known to be old product data;
+    this assembler cannot safely distinguish that case from a user-created same-named file.
+    """
+    dest = pathlib.Path(dest)
+    for rel in sorted(set(candidates)):
+        target = dest / rel
+        # Inspect existence only. A link is also a remnant for manual review; never open
+        # or modify its target as part of this disclosure.
+        if not target.exists() and not target.is_symlink():
+            continue
+        print(f"  {'[dry] ' if dry else ''}prior guide remnant left in place: {target}")
+        print("    inspect it and remove it manually if it is an obsolete agent-bios resource")
+
+
+def copy_guide_members(src_dir, names, dest, rewrite=None, dry=False, backup=None):
+    """Copy selected guide bundles and reconcile only their exact source members.
+
+    A companion directory is not an ownership boundary: it may contain a file a user added
+    after installation.  Membership is therefore resolved from the source tree and every
+    replace/deselect action is addressed to one known file path.  Empty directories are left
+    behind deliberately; an installer can remove them with ``rmdir`` only after all manifest
+    owned members are gone.
+
+    Markdown is rewritten only where the old file-only guide path already was.  Other regular
+    files are copied byte-for-byte (and with their mode) so scripts and render assets remain
+    one source of truth rather than becoming text projections.
+    """
+    src_dir = pathlib.Path(src_dir)
+    dest = pathlib.Path(dest)
+    all_members = guide_member_map(src_dir)
+    unknown = set(names) - set(all_members)
+    if unknown:
+        die(f"selected guide(s) not found in source tree: {sorted(unknown)}")
+    owned = {member for members in all_members.values() for member in members}
+    selected = {member for name in names for member in all_members[name]}
+    validate_guide_destination_members(dest, owned)
+    if not dry:
+        dest.mkdir(parents=True, exist_ok=True)
+
+    # Deselecting a guide means deleting files, never a same-named directory wholesale.
+    # The latter would claim a user's nested note merely because it shares our guide stem.
+    for rel in sorted(owned - selected):
+        target = dest / rel
+        if not target.is_file():
+            continue
+        print(f"  {'[dry] ' if dry else ''}deselected, removed {target}")
+        if dry:
+            continue
+        _backup_member(target, backup, "deselected")
+        target.unlink()
+
+    for rel in sorted(selected):
+        source = src_dir / rel
+        target = dest / rel
+        if dry:
+            print(f"  [dry] copy {rel} -> {dest}")
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if source.suffix == ".md":
+            body = source.read_text(encoding="utf-8")
+            if rewrite:
+                body = body.replace(*rewrite)
+            changed = True
+            if target.is_file():
+                try:
+                    changed = target.read_text(encoding="utf-8") != body
+                except (OSError, UnicodeDecodeError):
+                    changed = True
+            if changed and target.is_file():
+                _backup_member(target, backup, "replaced")
+            if changed:
+                target.write_text(body, encoding="utf-8")
+            continue
+
+        # Read the bytes directly.  `filecmp` caches stat signatures, which can report a
+        # same-size rewrite clean on filesystems whose mtime granularity is coarse; source
+        # code is small and byte identity is the contract here.
+        changed = not target.is_file() or source.read_bytes() != target.read_bytes()
+        if changed and target.is_file():
+            _backup_member(target, backup, "replaced")
+        if changed:
+            shutil.copy2(source, target)
+
+
 def replace_atomically(path, text):
     """Write via a temp file + os.replace, so a write that fails partway cannot truncate.
 
@@ -610,15 +854,46 @@ def main():
         if codex_only:
             codex_bundle = place_codex_only(codex_bundle, codex_only)
 
+    guide_source = REPO / "claude" / "guides"
+    guide_sources = guide_member_map(guide_source)
+    codex_guide_sources = guide_member_map(REPO / "codex" / "guides")
+    if set(guide_sources) != set(codex_guide_sources):
+        die("Claude and Codex guide primary sets differ; regenerate mirrors before assembling")
+    for name, members in guide_sources.items():
+        if members != codex_guide_sources[name]:
+            die(f"Claude and Codex guide members differ for {name}; regenerate mirrors before assembling")
+    prior_deployed = set()
+    if args.prior_manifest:
+        prior = pathlib.Path(args.prior_manifest)
+        if prior.is_file():
+            prior_deployed = {str(pathlib.Path(ln.strip())) for ln in
+                              prior.read_text(encoding="utf-8").splitlines() if ln.strip()}
+    current_guide_members = [member for members in guide_sources.values() for member in members]
+    current_codex_guide_members = [member for members in codex_guide_sources.values() for member in members]
+    prior_claude_candidates = prior_guide_candidates(
+        prior_deployed, claude_dir / "central" / "guides", current_guide_members)
+    prior_codex_candidates = prior_guide_candidates(
+        prior_deployed, codex_dir / "guides", current_codex_guide_members)
+    # Do this before withheld cleanup, bundle.md, or any guide copy.  A companion ancestor
+    # can be a symlink even when its leaf is an ordinary file; checking leaf targets only
+    # would then write outside the selected guides root before the unsafe path was noticed.
+    validate_guide_destination_members(
+        claude_dir / "central" / "guides",
+        current_guide_members,
+    )
+    validate_guide_destination_members(
+        codex_dir / "guides",
+        current_codex_guide_members,
+    )
     guides = filtered_files(manifest, "guides", selection)
-    withheld = [n for n in guides if author_only(REPO / "claude" / "guides" / n)]
+    withheld = [n for n in guides if author_only(guide_source / n)]
     guides = [n for n in guides if n not in withheld]
     # Not writing it is not enough for anyone who installed before this rule: the
     # manifest is rebuilt from the current deploy, so a file that stops being
     # deployed stops being tracked and would sit there for good.
-    stale = [d / n for n in withheld
+    stale = [d / member for n in withheld for member in guide_sources[n]
              for d in (claude_dir / "central" / "guides", codex_dir / "guides")
-             if (d / n).is_file()]
+             if (d / member).is_file()]
     # Copy before removing, the way install.sh backs up a file it replaces. The
     # name matching ours does not prove we wrote it — a shared or symlinked guides
     # directory can hold somebody's own file under the same name, and a deleted
@@ -627,6 +902,13 @@ def main():
     # `withheld` is an audience decision, `deselected` is a selection change.
     run_backup = state_dir / "backups" / time.strftime("%Y%m%d-%H%M%S")
     backup = run_backup / "withheld"
+    # A source release can remove one resource while retaining its primary guide.  Prior
+    # manifests have historically included user files below these roots, so they disclose
+    # candidates only; the source-derived member list remains the sole deletion authority.
+    disclose_prior_guide_remnants(claude_dir / "central" / "guides", prior_claude_candidates,
+                                  dry=args.dry_run)
+    disclose_prior_guide_remnants(codex_dir / "guides", prior_codex_candidates,
+                                  dry=args.dry_run)
     for path in stale:
         print(f"  {'[dry] ' if args.dry_run else ''}remove withheld {path}")
         if not args.dry_run:
@@ -646,25 +928,19 @@ def main():
     else:
         central.mkdir(parents=True, exist_ok=True)
         (central / "bundle.md").write_text(bundle, encoding="utf-8")
-    copy_filtered(REPO / "claude" / "guides", guides, central / "guides",
-                  rewrite=(f"{CLAUDE_VAR}/guides/", f"{CLAUDE_VAR}/central/guides/"), dry=dry,
-                  backup=run_backup)
+    copy_guide_members(guide_source, guides, central / "guides",
+                       rewrite=(f"{CLAUDE_VAR}/guides/", f"{CLAUDE_VAR}/central/guides/"),
+                       dry=dry, backup=run_backup)
     copy_filtered(REPO / "claude" / "hooks", hooks, central / "hooks", dry=dry, backup=run_backup)
     copy_filtered(REPO / "claude" / "agents", agents, central / "agents", dry=dry,
                   backup=run_backup)
     merge_settings(claude_dir, hooks, REPO / "claude" / "settings.template.json", dry=dry,
                    owned_names=manifest.get("hooks", {}))   # deselected hooks must drop too
-    prior_deployed = set()
-    if args.prior_manifest:
-        prior = pathlib.Path(args.prior_manifest)
-        if prior.is_file():
-            prior_deployed = {str(pathlib.Path(ln.strip())) for ln in
-                              prior.read_text(encoding="utf-8").splitlines() if ln.strip()}
     entry_state = seed_entry(claude_dir, monolith, prior_deployed, dry=dry)
 
     merge_codex(codex_dir, codex_bundle, prior_deployed, dry=dry)
-    copy_filtered(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry,
-                  backup=run_backup)
+    copy_guide_members(REPO / "codex" / "guides", guides, codex_dir / "guides", dry=dry,
+                       backup=run_backup)
 
     if not dry:
         state_dir.mkdir(parents=True, exist_ok=True)

package/compose/bootstrap/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: corpus
+description: Inspect or change the private agent-bios corpus used by activated sessions, including item creation, edits, consumption placement, removal, restore, recovery, selection, reset, rollback, history, and current-vs-pinned explanation. Use for requests about the user's agent-bios instructions or personal learnings; it does not alter the running session or native global files.
+---
+
+# Corpus management
+
+Use the deterministic `agent-bios corpus` client. In an activated launch, invoke
+it as `bash "$AGENT_BIOS_PACKAGE_ROOT/install.sh" corpus` (the examples below use
+the shorter command name). The launcher supplies that package path, so a checkout
+installation does not accidentally call an older global npm CLI. If the variable
+is absent, resolve the installed `agent-bios` command before using the examples.
+It reads and writes private
+agent-bios state; it never edits native global `AGENTS.md` / `CLAUDE.md`, host
+discovery directories, or the current conversation.
+
+## Establish the view
+
+Start with:
+
+```bash
+agent-bios corpus status --json
+agent-bios corpus list --json
+agent-bios corpus show '<CorpusRef>' --view effective --json
+```
+
+The running session is pinned to the `ContentRef` stated by its launch contract.
+`status`, `list`, and `show` describe current authoring unless a command explicitly
+says otherwise. A mutation changes future activated launches only; it does not
+rewrite this session's pin. `snapshot --host codex|claude` composes current
+authoring and returns stored snapshot evidence—it does not prove a host loaded it.
+Use `snapshot --content-ref '<ContentRef>' --json` to inspect the exact immutable
+items and instruction text of the running or resumed session, independently of
+current authoring.
+
+Use `show --view installed|change|diff|history` to compare the selected installed
+baseline, the personal layer, and effective authoring. Use `history [CorpusRef]
+--json` for recoverable revisions.
+
+## Plan, preview, then apply
+
+Send exactly one semantic operation as JSON. The runtime owns ids, paths, digests,
+timestamps, serialization, revision calculation, and publication. Never invent or
+edit those values. For writes, preserve the `digest` returned by `list` as
+`item_digest`; preserve the plan's `expected_revision` when applying it.
+
+```bash
+agent-bios corpus plan --input request.json --json
+agent-bios corpus apply '<plan_id>' --expected-revision '<expected_revision>' --json
+```
+
+Supported payloads:
+
+```json
+{"operation":"create","item":{"title":"Review releases","body":"...","surface":"requested","tier":"env-personal","domains":["personal"],"kind":"rule"}}
+{"operation":"update","ref":"@scope/name:item-id","item_digest":"<digest>","patch":{"body":"...","surface":"relevant"}}
+{"operation":"remove","ref":"@scope/name:item-id","item_digest":"<digest>"}
+{"operation":"restore","ref":"@scope/name:item-id"}
+{"operation":"recover","ref":"@local/personal:item-id"}
+{"operation":"select","selection":["@scope/name/domain"]}
+{"operation":"reset"}
+{"operation":"rollback","baseline_ref":"<baseline_ref>"}
+{"operation":"rollback","history_id":"<history_id>"}
+```
+
+For a body edit, submit `body`; the manager updates the item's `primary_member`
+and derives every content view from that file. For a multi-file edit, submit
+`members` retaining unchanged files. A conflicting simultaneous body/member edit
+is refused. If `content_conflict` is shown, compare the preserved body and members
+with the user; submit an explicit primary-member/content choice rather than
+silently choosing a version. Personal IDs are issued once by the plan and remain
+stable on retry; create payloads do not supply `item_id` or `ref`.
+Do not turn a prose edit into an executable asset, hook,
+permission, tool, or capability change. `always`, `relevant`, and `requested`
+mean always in an activated selection, trigger-routed, and explicitly requested.
+For existing Claude hook items, `hook: {"event":"PreToolUse","matcher":"Bash"}`
+edits the binding through the same plan/apply path. Preserve the installed source
+carrier and native agent frontmatter, including tool restrictions. Changing an
+ordinary prose item's kind/surface does not turn it into executable hook code.
+
+Native hook execution and corpus-agent registration are off by default. The user
+opts in per launch with `agent-launch --corpus-native`; `snapshot --host claude
+--native --json` previews/composes that selection without activating a host.
+The snapshot supplies session-only local plugins; it does not install them into
+global discovery. Check `unavailable` for unsupported carriers or hosts. Native
+corpus agent names are qualified by their item plugin, distinct from the launcher's
+bare tier names. Removing/restoring one item changes only future snapshots.
+
+Show the plan and its consequences before Apply when the user has not already
+approved that exact mutation. A stale revision or digest requires a fresh read and
+new plan; never retry by dropping the revision check. Report after Apply that the
+current session is unchanged and a new activated launch is needed.
+
+## Restore, recover, and reset
+
+- `restore` removes an installed item's personal override/tombstone and reveals
+  the version in the selected baseline for future snapshots.
+- `recover` reactivates a personal item or host learning from private history. It is not installed
+  restore.
+- `reset` returns future authoring and selection to the last successful installed
+  tuple while preserving sources, history, and existing session pins.
+- For all product settings as well, `agent-bios reset` previews the effect;
+  `agent-bios reset --apply --yes --expected-revision '<preview revision>'` also
+  resets launcher overrides and disables configured ingestion. It does not reset
+  the native host's settings. Retry the accepted revision to finish an interrupted
+  reset; if state has changed, show a fresh preview and obtain approval for its
+  revision. Token bytes are never archived or restored.
+- `rollback` selects a validated baseline or replays one history record for future
+  snapshots; it never rewrites a running or resumable session.
+
+## Personal learnings
+
+Claude and Codex learning sources are separate, host-qualified local authorities.
+Captured events and their `learning_id` identify immutable captured bytes. Editing
+their corpus presentation creates a local overlay for future snapshots; it does
+not change an already uploaded record. Uploading revised wording is a new explicit
+capture with a new id and provenance link. Never claim that local remove, reset,
+promotion, or purge deleted an uploaded learning unless a real remote delete
+protocol reports that outcome.

package/compose/check-domains.py

@@ -40,7 +40,12 @@ import sys
 
 sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
 import pkgid  # noqa: E402  (sibling module in compose/)
-from assemble import author_only, hook_command_matches  # noqa: E402  THE readers: audience frontmatter, and the settings-merge token rule the gate must agree with
+from assemble import (  # noqa: E402  the shipped structural/audience/ownership readers
+    GuideMemberError,
+    author_only,
+    guide_member_map,
+    hook_command_matches,
+)
 
 REPO = pathlib.Path(__file__).resolve().parent.parent
 MANIFEST = REPO / "compose" / "domains.json"
@@ -62,6 +67,11 @@ def units_on_disk(root, glob, key):
     directories that carry SKILL.md. Returns (names, malformed) — a skills subdirectory
     without the marker is neither claimable nor ignorable."""
     names, malformed = set(), []
+    if key == "guides":
+        try:
+            return set(guide_member_map(root)), malformed
+        except GuideMemberError as exc:
+            return names, [str(exc)]
     for p in root.glob(glob):
         if key == "skills":
             if p.is_dir():
@@ -291,8 +301,11 @@ def run_gate(manifest, bullets, repo=REPO):
         if not on_disk:
             errors.append(f"non-vacuity: no files on disk under {rel}")
         for name in malformed:
-            errors.append(f"{key}: directory {name} in {rel} carries no {SKILL_MARKER} — "
-                          f"not a skill the hosts can load, and not a name the manifest can claim")
+            if key == "skills":
+                errors.append(f"{key}: directory {name} in {rel} carries no {SKILL_MARKER} — "
+                              f"not a skill the hosts can load, and not a name the manifest can claim")
+            else:
+                errors.append(f"{key}: invalid bundle source shape — {name}")
         for name, entry in section.items():
             check_registry(entry, f"{key}/{name}")
             if name not in on_disk:
@@ -308,6 +321,22 @@ def run_gate(manifest, bullets, repo=REPO):
     # handle is only as good as its declaration: this catches phrasings someone wrote down, not
     # every paraphrase.
     guide_aud = {n: audience(e, errors, f"guides/{n}") for n, e in entries["guides"].items()}
+    guide_dir = repo / "claude" / "guides"
+    try:
+        guide_sources = guide_member_map(guide_dir)
+    except GuideMemberError:
+        # Rule 3 already reports the concrete shape error.  Keep the router checks from
+        # raising so one malformed companion cannot hide the rest of the manifest errors.
+        guide_sources = {}
+    for name, members in guide_sources.items():
+        primary_is_author_only = author_only(guide_dir / name)
+        for member in members[1:]:
+            path = guide_dir / member
+            if path.suffix == ".md" and author_only(path) and not primary_is_author_only:
+                errors.append(
+                    f"guides/{name}: companion {member} declares audience: author but its "
+                    f"primary is delivered — author-only content cannot ride a public guide bundle"
+                )
     # A declared handle is a NAME, and a name resolving to two guides routes the reader
     # nowhere: refs_from() would credit both targets from one prose router, falsely
     # rooting and co-packaging a guide the sentence never meant. Duplicates fail here
@@ -380,7 +409,6 @@ def run_gate(manifest, bullets, repo=REPO):
     # exemption: a corpus bullet (by path or declared handle), a parent guide citing a child
     # as a depth chain, and a launch preset's mission. An exemption list would be the fourth,
     # and it is the one that lets a genuinely orphaned guide through.
-    guide_dir = repo / "claude" / "guides"
     launch = repo / "launch" / "agent-launch.toml"
     launch_text, launch_missions = "", []
     if launch.is_file():
@@ -540,8 +568,13 @@ def run_gate(manifest, bullets, repo=REPO):
         prose = re.sub(r"<!--.*?-->", "", prose, flags=re.S)
         return re.sub(r"<!--.*", "", prose, flags=re.S)
 
-    bodies = {p.name: _defenced(p.read_text(encoding="utf-8"))
-              for p in sorted(guide_dir.glob("*.md"))}
+    bodies = {
+        name: "\n".join(
+            _defenced((guide_dir / member).read_text(encoding="utf-8"))
+            for member in members if member.endswith(".md")
+        )
+        for name, members in guide_sources.items()
+    }
     if not bodies:
         errors.append("non-vacuity: no guide bodies read, so consumers were not checked")
     # Reachability is TRANSITIVE FROM ROOTS (bullets and launch missions), not "any
@@ -617,9 +650,10 @@ def run_gate(manifest, bullets, repo=REPO):
         sizes[key] = sizes.get(key, 0) + len(hit) // 4
     for name, entry in entries["guides"].items():
         key = entry.get("tier") if entry.get("tier") != "domain" else ",".join(entry.get("domains", ["?"])[:1])
-        p = repo / FILE_SECTIONS["guides"][0] / name
-        if p.is_file():
-            sizes[key] = sizes.get(key, 0) + len(p.read_text(encoding="utf-8")) // 4
+        for member in guide_sources.get(name, []):
+            p = repo / FILE_SECTIONS["guides"][0] / member
+            if p.is_file():
+                sizes[key] = sizes.get(key, 0) + p.stat().st_size // 4
     return errors, sizes
 
 
@@ -773,6 +807,57 @@ def self_test(manifest, bullets):
     print(f"self-test [{'CAUGHT' if never_ok else 'MISSED'}] an env-personal (never-"
           f"delivered) router bullet leaves {o_name} an orphan")
 
+    # Bundle shape is structural, not a second manifest class.  These controls run against
+    # copies because the source is the input being judged: an orphan resource tree and a
+    # symlink must be named before router/coverage checks can pretend the guide is ordinary.
+    bundle_sources = guide_member_map(REPO / "claude" / "guides")
+    bundle_name = next((name for name, members in bundle_sources.items()
+                        if len(members) > 1), None)
+    if bundle_name is None:
+        raise SystemExit("self-test: no guide bundle has a companion member, so bundle-shape "
+                         "controls would pass vacuously")
+    companion_markdown = next((member for member in bundle_sources[bundle_name][1:]
+                               if member.endswith(".md")), None)
+    if companion_markdown is None:
+        raise SystemExit("self-test: the companion bundle has no Markdown resource, so the "
+                         "companion-router control would pass vacuously")
+    import shutil as _bundle_shutil, tempfile as _bundle_tempfile
+    with _bundle_tempfile.TemporaryDirectory() as _td:
+        _root = pathlib.Path(_td)
+        for _sub in ("claude", "ko", "launch"):
+            if (REPO / _sub).is_dir():
+                _bundle_shutil.copytree(REPO / _sub, _root / _sub)
+        _guide_root = _root / "claude" / "guides"
+        (_guide_root / "orphan-companion-control").mkdir()
+        _orphan_shape, _ = run_gate(manifest, bullets, repo=_root)
+        orphan_companion_ok = any("orphan guide companion tree" in e for e in _orphan_shape)
+        _bundle_shutil.rmtree(_guide_root / "orphan-companion-control")
+
+        _symlink = _guide_root / pathlib.Path(bundle_name).stem / "symlink-control"
+        _symlink.symlink_to(_guide_root / bundle_name)
+        _symlink_shape, _ = run_gate(manifest, bullets, repo=_root)
+        symlink_ok = any("must not contain symlinks" in e for e in _symlink_shape)
+        _symlink.unlink()
+
+        _companion = _guide_root / companion_markdown
+        _body = _companion.read_text(encoding="utf-8")
+        _companion.write_text(_body + f"\n\nSee `guides/{o_name}` for the control.\n",
+                              encoding="utf-8")
+        _companion_router, _ = run_gate(m_orphan, [b for b in bullets if b != o_line], repo=_root)
+        companion_router_ok = not any(o_name in e and "orphan" in e for e in _companion_router)
+        _companion.write_text("---\naudience: author\n---\n" + _body, encoding="utf-8")
+        _companion_author, _ = run_gate(manifest, bullets, repo=_root)
+        companion_author_ok = any(bundle_name in e and companion_markdown in e
+                                  and "audience: author" in e for e in _companion_author)
+    print(f"self-test [{'CAUGHT' if orphan_companion_ok else 'MISSED'}] an orphan companion "
+          "tree is rejected without requiring a manifest item")
+    print(f"self-test [{'CAUGHT' if symlink_ok else 'MISSED'}] a symlink in a companion tree "
+          "is rejected")
+    print(f"self-test [{'CAUGHT' if companion_router_ok else 'MISSED'}] a Markdown companion "
+          "is scanned as its primary guide's router")
+    print(f"self-test [{'CAUGHT' if companion_author_ok else 'MISSED'}] an author-only companion "
+          "cannot ride a delivered primary")
+
     # A registry of the wrong TYPE must be listed like any other violation. `set(None)` is
     # not a diagnostic — it is a TypeError out of the gate before it can name anything, and
     # `"domains": null` is exactly what a bad hand-edit of this file leaves behind. The
@@ -1222,6 +1307,14 @@ def self_test(manifest, bullets):
         failed.append("real router in list-blockquoted prose still counts")
     if not never_ok:
         failed.append("never-delivered bullet does not root a guide")
+    if not orphan_companion_ok:
+        failed.append("orphan companion tree is rejected")
+    if not symlink_ok:
+        failed.append("companion-tree symlink is rejected")
+    if not companion_router_ok:
+        failed.append("Markdown companion prose is scanned as a router")
+    if not companion_author_ok:
+        failed.append("author-only companion cannot ride a delivered primary")
     if not island_ok:
         failed.append("reciprocal island stays orphaned")
     if not inert_hits:

package/compose/corpus-state.py

@@ -356,6 +356,9 @@ def _assemble_at(repo: pathlib.Path, commit: str, domains: list[str]) -> tuple[b
 
 
 def cmd_rollback(args: argparse.Namespace) -> int:
+    if os.environ.get("AGENT_BIOS_LEGACY_INSTALL") != "1":
+        print("corpus-state rollback: global rollback is retired; use agent-bios corpus plan with op=rollback and a private baseline_ref", file=sys.stderr)
+        return 2
     repo = repo_root(args.repo)
     versions = require_versions(repo, "rollback")
     if versions is None:
@@ -1144,6 +1147,7 @@ def main() -> int:
     # Before argparse, because --self-test takes none of the subcommands' arguments and
     # every subcommand here is required.
     if "--self-test" in sys.argv[1:]:
+        os.environ["AGENT_BIOS_LEGACY_INSTALL"] = "1"
         return self_test()
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest="cmd", required=True)