create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/pi/egregore_runtime/harness_cli.py

@@ -0,0 +1,1221 @@
+"""Harness-neutral command adapter for organizational context.
+
+Claude, Codex, Pi, Prime, and shell skills enter the Egregore Runtime here.
+This module deliberately knows no QMD, graph, Supabase, or filesystem-index
+implementation details.  Infrastructure is composed behind ``local_runtime``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import unicodedata
+import uuid
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from .contracts import (
+    EvidenceItem,
+    Permission,
+    RetrievalMode,
+    RetrievalRequest,
+    TemporalScope,
+)
+from .errors import AuthorizationDenied, EgregoreRuntimeError
+from .identity import organization_member_presentations
+from .runtime import EgregoreRuntime, local_runtime
+
+
+# Optional latency optimization only. The model remains responsible for
+# interpreting organizational-recall intent when this conservative prefetch
+# misses; see the actor-only context contract below.
+_ORG_CONTEXT_PREFETCH_PATTERN = re.compile(
+    "|".join(
+        (
+            r"\b(find|locate|dig up|look up|pull up)\b.*\b"
+            r"(handoff|decision|notes?|docs?|meeting|harvest|quest|reflection)s?\b",
+            r"\bdid we (decide|discuss|agree|say|talk about|cover)\b",
+            r"\bdo we have (any )?(notes?|docs?|anything|something)( on| about)?\b",
+            r"\bwhat did we (decide|say|agree|discuss)\b",
+            r"\bhave we (discussed|decided|covered|talked about|looked at)\b",
+            r"\bnotes on\b",
+            r"\bhandoff (from|about)\b",
+            r"\bwho worked on\b",
+            r"\bdidn.?t (someone|we) already\b",
+            r"\bwas there (a|any) (handoff|decision|discussion|meeting)\b",
+            r"\bopen (the )?canonical (source|handoff|decision|thread|artifact|document)\b",
+            r"\b(?:restore|resume|continue|pick up)\b.*\b"
+            r"(?:handoff|organizational context|org context|prior work|runtime|project|thread)\b",
+            r"\b(?:handoff|organizational context|org context|prior work|runtime|project|thread)\b.*\b"
+            r"(?:restore|resume|continue|pick up)\b",
+            r"\bfrom (?:the )?handoff titled\b",
+            r"\bwhat\b.*\b(newest|latest|recorded|canonical)\b.*\b"
+            r"(handoffs?|decisions?|threads?|quests?|meetings?|artifacts?)\b",
+            r"\bwhat\b.*\b(handoffs?|decisions?|quests?|meetings?|artifacts?)\b.*\b"
+            r"(says?|records?|contains?|remains?|status)\b",
+            r"\b(our|company|org|organization|team)\b.*\b"
+            r"(pricing|price|tiers?|plans?|paid|free|strategy|policy|positioning|ownership|decision|"
+            r"purpose|mission|principles?|conventions?|values?|goals?|roadmap|architecture|priorities|"
+            r"roles?|people|team)\b",
+            r"\b(pricing|price|tiers?|plans?|paid|free|purpose|mission|principles?|conventions?|values?)\b.*\b"
+            r"(our|company|org|organization|team)\b",
+            r"\b(?:what(?:'s| is)?|where)\b.*\b"
+            r"(?:remaining|remains|left|next|status|state|scope|open work|working on)\b.*\b"
+            r"(?:egregore|runtime|architecture|mvp|implementation|release|project|thread|handoff)\b",
+            r"\b(?:egregore|runtime|architecture|mvp|implementation|release|project|thread|handoff)\b.*\b"
+            r"(?:remaining|remains|left|next|status|state|scope|open work|still needs?)\b",
+        )
+    ),
+    re.IGNORECASE,
+)
+_EXPLICIT_SEARCH = re.compile(
+    r"(/search\b|\$search\b|search\.sh|\bsearch (the )?memory\b)", re.I
+)
+_ORG_RITUAL_CONTEXT_PREFETCH_PATTERN = re.compile(
+    r"(?:/scroll\b|\$scroll\b|\b(?:create|make|compose|tend)\b.{0,48}\bscroll\b)",
+    re.I,
+)
+_HISTORICAL_SCOPE = re.compile(
+    r"\b(history|historical|previous|older|old decision|superseded|what changed|how .* evolv(?:e|ed))\b",
+    re.I,
+)
+_RECALL_LEX_PREFIXES = tuple(
+    re.compile(pattern, re.I)
+    for pattern in (
+        r"^\s*(?:what\s+)?did\s+we\s+(?:decide|discuss|agree|say|cover|talk\s+about)\s*(?:about|on)?\s*",
+        r"^\s*have\s+we\s+(?:discussed|decided|covered|talked\s+about|looked\s+at)\s*(?:about|on)?\s*",
+        r"^\s*do\s+we\s+have\s+(?:any\s+)?(?:notes?|docs?|anything|something)\s*(?:about|on)?\s*",
+        r"^\s*what\s+(?:exact\s+)?(?:invariants?|decisions?|details?|content|status)\s+"
+        r"(?:are|is)\s+(?:recorded|listed|defined|contained)\s+in\s+(?:the\s+)?",
+    )
+)
+_WORKTREE_PATH_PATTERN = re.compile(
+    r"(?P<path>/[^\s`\"']*?/\.claude/worktrees/[^\s`\"']+)",
+)
+
+
+def _root() -> Path:
+    configured = os.environ.get("EGREGORE_ROOT")
+    return Path(configured).resolve() if configured else Path.cwd().resolve()
+
+
+def _prompt_root(payload: dict[str, object], default_root: Path) -> Path:
+    """Select an explicitly named worktree inside this Egregore instance.
+
+    Harness instructions and hooks are loaded when a session starts, so a
+    continuation prompt may name a newer task worktree while the process still
+    stands in the instance root. Runtime retrieval must follow that explicit
+    workspace instead of silently querying the stale launch checkout.
+    """
+
+    prompt = str(payload.get("prompt") or payload.get("user_prompt") or "")
+    root_text = str(default_root.resolve())
+    marker = f"{os.sep}.claude{os.sep}worktrees{os.sep}"
+    instance_root = Path(root_text.split(marker, 1)[0]) if marker in root_text else default_root
+    worktree_root = (instance_root / ".claude" / "worktrees").resolve()
+    for match in _WORKTREE_PATH_PATTERN.finditer(prompt):
+        raw = match.group("path").rstrip(".,;:)]}")
+        candidate = Path(raw).resolve()
+        try:
+            candidate.relative_to(worktree_root)
+        except ValueError:
+            continue
+        if candidate.is_dir() and (candidate / ".git").exists() and (candidate / "egregore.json").is_file():
+            return candidate
+    return default_root
+
+
+def _session_id(root: Path) -> str:
+    configured = os.environ.get("EGREGORE_SESSION_ID", "").strip()
+    if configured:
+        return configured
+    try:
+        persisted = (root / ".egregore-session-id").read_text(encoding="utf-8").strip()
+    except OSError:
+        persisted = ""
+    return persisted or f"session_{uuid.uuid4().hex}"
+
+
+def _actor(runtime: EgregoreRuntime, root: Path, harness: str):
+    return runtime.resolve_actor(session_id=_session_id(root), harness=harness)
+
+
+def _observe_receipt_path(root: Path, harness: str) -> Path:
+    """Return the gitignored, current-session Observe receipt path."""
+
+    identity = f"{harness}:{_session_id(root)}".encode("utf-8")
+    name = hashlib.sha256(identity).hexdigest()[:24] + ".json"
+    return root / ".egregore" / "runtime" / "observe" / name
+
+
+def _clear_observe_receipt(root: Path, harness: str) -> None:
+    try:
+        _observe_receipt_path(root, harness).unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _write_observe_receipt(root: Path, harness: str, prompt: str, context) -> None:
+    """Record that this prompt already received useful authorized evidence.
+
+    This is ephemeral turn-deduplication state, not organizational memory or a
+    learned retrieval cache. The next UserPromptSubmit hook clears it before
+    deciding whether that new prompt needs Observe.
+    """
+
+    evidence = tuple(getattr(context, "evidence", ()) or ())
+    if not evidence:
+        return
+    path = _observe_receipt_path(root, harness)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        os.chmod(path.parent, 0o700)
+        payload = {
+            "schema_version": "egregore.observe-receipt/v1",
+            "created_at_unix": time.time(),
+            "harness": harness,
+            "session_id": _session_id(root),
+            "prompt_sha256": hashlib.sha256(prompt.encode("utf-8")).hexdigest(),
+            "context_id": str(getattr(context, "context_id", "")),
+            "source_paths": [str(item.canonical_path) for item in evidence],
+        }
+        temporary = path.with_suffix(".tmp")
+        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, separators=(",", ":"))
+            handle.write("\n")
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, path)
+    except OSError:
+        # The hook remains advisory if local ephemeral state is unavailable.
+        pass
+
+
+def _active_observe_receipt(root: Path, harness: str) -> dict[str, object] | None:
+    """Load a useful receipt for the current harness prompt, if present."""
+
+    receipt_dir = root / ".egregore" / "runtime" / "observe"
+    paths = [_observe_receipt_path(root, harness)]
+    if harness == "shell":
+        try:
+            paths = sorted(
+                receipt_dir.glob("*.json"),
+                key=lambda candidate: candidate.stat().st_mtime,
+                reverse=True,
+            )
+        except OSError:
+            paths = []
+    for path in paths:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("session_id") != _session_id(root):
+            continue
+        if harness != "shell" and payload.get("harness") != harness:
+            continue
+        if payload.get("source_paths"):
+            return payload
+    return None
+
+
+def _request(
+    *,
+    task: str,
+    org_id: str,
+    actor_id: str,
+    mode: RetrievalMode,
+    limit: int,
+    lex: tuple[str, ...] = (),
+    vec: tuple[str, ...] = (),
+    open_sources: bool = False,
+    temporal_scope: TemporalScope | None = None,
+    recent_days: int | None = None,
+) -> RetrievalRequest:
+    if mode is RetrievalMode.LEX and not lex:
+        lex = vec
+    if mode is RetrievalMode.VEC and not vec:
+        vec = lex
+    return RetrievalRequest(
+        request_id=f"observe-{uuid.uuid4().hex}",
+        org_id=org_id,
+        actor_id=actor_id,
+        task=task,
+        lex=lex,
+        vec=vec,
+        top_k=limit,
+        mode=mode,
+        open_sources=open_sources,
+        temporal_scope=temporal_scope or temporal_scope_for_task(task),
+        not_before=(
+            datetime.now(UTC) - timedelta(days=recent_days)
+            if recent_days is not None
+            else None
+        ),
+    )
+
+
+def temporal_scope_for_task(task: str) -> TemporalScope:
+    """Select historical evidence only when the task explicitly asks for it."""
+
+    return (
+        TemporalScope.CURRENT_AND_HISTORICAL
+        if _HISTORICAL_SCOPE.search(task)
+        else TemporalScope.CURRENT
+    )
+
+
+def _render_evidence(evidence: EvidenceItem) -> str:
+    parts = [
+        "---",
+        f"**file:** `{evidence.canonical_path}`",
+        f"**artifact:** `{evidence.artifact_id}`",
+        f"**reason:** {evidence.reason}",
+    ]
+    if evidence.content:
+        parts.extend(("", evidence.content))
+    return "\n".join(parts)
+
+
+def _render_compact_evidence(evidence: EvidenceItem, rank: int) -> str:
+    excerpt = " ".join(evidence.content.split())
+    excerpt = re.sub(r"^@@.*?@@\s*(?:\([^)]*\)\s*)?", "", excerpt)
+    if len(excerpt) > 220:
+        excerpt = excerpt[:217].rstrip() + "..."
+    return "\n".join(
+        (
+            f"[{rank}] **file:** `{evidence.canonical_path}` · "
+            f"**artifact:** `{evidence.artifact_id}` · {evidence.reason}",
+            f"    excerpt: {excerpt}",
+        )
+    )
+
+
+def _query(args: argparse.Namespace) -> int:
+    root = _root()
+    receipt = (
+        None
+        if getattr(args, "new_search", False)
+        else _active_observe_receipt(root, args.harness)
+    )
+    if receipt is not None:
+        print("EGREGORE_OBSERVE_CONTEXT_REUSED")
+        print(
+            "Authorized organizational context was already compiled for this prompt; "
+            "no second retrieval was run. Use the attached EGREGORE_ORG_CONTEXT_V1 evidence."
+        )
+        return 0
+    runtime = local_runtime(root, push_remote=False)
+    actor = _actor(runtime, root, args.harness)
+    lexical = identity_aware_lexical_formulations(
+        root,
+        actor,
+        args.task,
+        tuple(args.lex),
+    )
+    context = runtime.observe(
+        actor,
+        _request(
+            task=args.task,
+            org_id=actor.profile.org_id,
+            actor_id=actor.actor.actor_id,
+            lex=lexical,
+            vec=tuple(args.vec),
+            mode=args.mode,
+            limit=args.limit,
+            temporal_scope=getattr(args, "temporal_scope", None),
+            recent_days=getattr(args, "recent_days", None),
+        ),
+        token_budget=actor.profile.default_context_budget,
+    )
+    if args.json:
+        print(json.dumps(context.to_dict(), indent=2))
+    elif len(context.evidence) < getattr(args, "min_evidence", 1):
+        minimum = getattr(args, "min_evidence", 1)
+        recent_days = getattr(args, "recent_days", None)
+        window = f" within the last {recent_days} days" if recent_days is not None else ""
+        print(
+            "EGREGORE_EVIDENCE_GAP "
+            f"actual={len(context.evidence)} required={minimum} "
+            f"recent_days={recent_days or 0}"
+        )
+        print(
+            f"Freshness evidence gap: found {len(context.evidence)} authorized source(s){window}; "
+            f"at least {minimum} are required for this synthesis. Do not substitute older sources."
+        )
+    elif context.evidence and getattr(args, "compact", False):
+        print(
+            "\n".join(
+                _render_compact_evidence(item, rank)
+                for rank, item in enumerate(context.evidence, start=1)
+            )
+        )
+    elif context.evidence:
+        print("\n\n".join(_render_evidence(item) for item in context.evidence))
+    else:
+        recent_days = getattr(args, "recent_days", None)
+        if recent_days is not None:
+            print(
+                f"No authorized evidence was found within the last {recent_days} days. "
+                "State the freshness gap; do not substitute older sources."
+            )
+        else:
+            print("No results found.")
+    return 0
+
+
+def prompt_prefetches_org_context(prompt: str) -> bool:
+    """Return whether Observe should prefetch likely organizational context.
+
+    This is deliberately a best-effort latency optimization, not the semantic
+    authority for recall. A false result still injects actor context that tells
+    the model to interpret intent and enter Runtime/QMD once when recall is
+    actually needed.
+    """
+
+    return bool(
+        prompt
+        and not _EXPLICIT_SEARCH.search(prompt)
+        and (
+            _ORG_CONTEXT_PREFETCH_PATTERN.search(prompt)
+            or _ORG_RITUAL_CONTEXT_PREFETCH_PATTERN.search(prompt)
+        )
+    )
+
+
+def prompt_requests_org_context(prompt: str) -> bool:
+    """Compatibility alias for the optional Observe prefetch predicate."""
+
+    return prompt_prefetches_org_context(prompt)
+
+
+def prompt_requests_actor_context(prompt: str) -> bool:
+    """Return whether a normal prompt needs stable actor attribution.
+
+    Identity is cheap, local organizational context. Supplying it on every
+    prompt keeps every skill and harness consistent about ``me``/``myself``
+    without triggering retrieval or asking models to infer from OS/Git names.
+    """
+
+    return bool(prompt and prompt.strip())
+
+
+def _actor_context_block(runtime: EgregoreRuntime, root: Path, harness: str) -> str:
+    """Render the minimum stable identity needed by harness rituals."""
+
+    actor_context = _actor(runtime, root, harness)
+    actor = actor_context.actor
+    aliases = ", ".join(
+        dict.fromkeys(
+            value.strip()
+            for value in getattr(actor, "aliases", {}).values()
+            if value and value.strip() and value.strip().casefold() != actor.display_name.casefold()
+        )
+    ) or "none"
+    member_names = "; ".join(
+        f"{', '.join(member.aliases)} → {member.display_name}"
+        if member.aliases
+        else member.display_name
+        for member in organization_member_presentations(root, actor_context)
+    ) or "unavailable"
+    search_command = 'bash bin/search.sh query "<concept>" -n 6 --compact'
+    if harness == "claude":
+        search_command += " --context-packet"
+    return "\n".join(
+        (
+            "EGREGORE_ACTOR_CONTEXT_V1",
+            "Resolved automatically by EgregoreRuntime before the ritual.",
+            f"Actor ID: {actor.actor_id}",
+            f"Actor display name: {actor.display_name}",
+            f"Actor aliases: {aliases}",
+            f"Organization ID: {actor_context.profile.org_id}",
+            f"Organization member names: {member_names}",
+            "Member names are presentation-only identity context. Use the display name when "
+            "retrieved evidence names one of its aliases. The directory is not activity "
+            "evidence: never mention a member merely because they are listed, never append it "
+            "to a retrieval query, and never use it for authorization.",
+            f"Runtime root: {root}",
+            "Run Egregore retrieval and workflow commands from this Runtime root. "
+            "Do not fall back to a launch checkout named elsewhere in the session.",
+            "Organizational retrieval status: NOT_PERFORMED. This actor-only block "
+            "does not mean organizational recall is unnecessary.",
+            "Interpret the user's intent semantically, without requiring trigger words. "
+            "If the request needs organizational history, synthesis of current team or person "
+            "work, a prior handoff, or continuation of earlier work and no "
+            "EGREGORE_ORG_CONTEXT_V1 block is attached, begin with "
+            f"exactly one `{search_command}` call. Compact "
+            "evidence is the normal model-led recall surface; do not open a full source unless "
+            "a necessary claim depends on context omitted from its excerpt. For a semantic "
+            "request about current team or person work, keep the user's actual concept and add "
+            "only useful time framing such as the current month and year. Never append the "
+            "organization roster, unmentioned member names, account handles, or aliases to a "
+            "retrieval query. Add a model-selected `--recent-days N` window; prefer 30 days for "
+            "a team-wide synthesis unless the user asks for another period. For one named "
+            "member, omit `--min-evidence`: one recent authorized source can support a narrow, "
+            "properly bounded answer, and Runtime expands only that member's stable identity "
+            "aliases during lexical fallback. Add `--min-evidence 3` only for a team-wide "
+            "synthesis so one stale-looking source cannot support a broad claim. These are "
+            "freshness and confidence constraints; lifecycle `current` alone "
+            "does not prove recency. `Freshness evidence gap` is a terminal result for that "
+            "prompt: report only the gap. Do not make current-work claims, run a second search, "
+            "or substitute Git, startup status, Activity, Dashboard, or older sources.",
+            "On Claude, `--context-packet` keeps the internal evidence trace out of the user "
+            "transcript and attaches it through PostToolUse. Keep that flag on model-led "
+            "searches; never repeat the attached ranking trace in the answer.",
+            "Exact lifecycle questions route differently: recognize them from meaning, not "
+            "fixed phrases. When the user asks for the latest/newest/oldest handoff addressed "
+            "to or sent by a specific person (including `me`), or open/unresolved handoffs, "
+            "run the typed deterministic lookup `bash bin/search.sh handoffs "
+            "[--mine|--sent|--addressed-to X|--sent-by X] [--status open] "
+            "[--order newest|oldest] [--limit N] [--open]` instead of a semantic query — one "
+            "memory-form retrieval beat, then answer from its result. Topical or synthesis "
+            "questions about handoffs (`the handoff about privacy`) remain semantic "
+            "`search.sh query` recall.",
+            "Do not substitute Activity, Dashboard, Project, Git inspection, graph, or raw "
+            "memory scans for that recall. A named request to display a status card is an "
+            "explicit status workflow; a question asking for an explained synthesis of "
+            "organizational work is Runtime/QMD recall. Do not query graph unless the user "
+            "explicitly requests relationship "
+            "or projected graph status.",
+            "For every identity-bearing workflow, `me`, `myself`, `from me`, "
+            "and `to myself` mean this Actor ID and display name. Use the "
+            "display name for presentation and the Actor ID for ownership, "
+            "authorization, attribution, creator, steward, recipient, and "
+            "respondent fields. Never infer identity from the OS user, Git, "
+            "GitHub, a branch name, or prose aliases.",
+            "END_EGREGORE_ACTOR_CONTEXT_V1",
+        )
+    )
+
+
+def lexical_formulation(prompt: str) -> str:
+    """Remove conversational recall framing from the BM25 formulation.
+
+    This is deterministic typed-query planning, not query expansion: the
+    vector lane still receives the untouched task and no new terms are added.
+    """
+
+    concept = prompt.strip()
+    for prefix in _RECALL_LEX_PREFIXES:
+        match = prefix.match(concept)
+        if not match:
+            continue
+        reduced = concept[match.end() :].strip(" \t\r\n?!.:")
+        if reduced:
+            return reduced
+    return concept
+
+
+def identity_aware_lexical_formulations(
+    root: Path,
+    actor: object,
+    task: str,
+    formulations: tuple[str, ...],
+) -> tuple[str, ...]:
+    """Add aliases only for organization members explicitly named by the task.
+
+    This keeps cold BM25 retrieval equivalent to stable identity resolution:
+    a chosen display name, provider handle, and legacy local alias all refer to
+    one member. The directory is never added wholesale and semantic queries
+    remain untouched.
+    """
+
+    def normalized(value: str) -> str:
+        decomposed = unicodedata.normalize("NFKD", value.casefold())
+        ascii_like = "".join(
+            character for character in decomposed if not unicodedata.combining(character)
+        )
+        return " ".join(re.findall(r"[^\W_]+", ascii_like, re.UNICODE))
+
+    task_tokens = f" {normalized(task)} "
+    expanded = list(formulations)
+    seen = {value.strip().casefold() for value in expanded if value.strip()}
+    for member in organization_member_presentations(root, actor):
+        references = (member.display_name, *member.aliases)
+        if not any(
+            reference_normalized
+            and f" {reference_normalized} " in task_tokens
+            for reference_normalized in (normalized(value) for value in references)
+        ):
+            continue
+        for reference in references:
+            key = reference.strip().casefold()
+            if not key or key in seen:
+                continue
+            expanded.append(reference)
+            seen.add(key)
+    return tuple(expanded)
+
+
+def _hook_context(
+    runtime: EgregoreRuntime,
+    root: Path,
+    prompt: str,
+    harness: str,
+    limit: int,
+) -> str:
+    actor = _actor(runtime, root, harness)
+    aliases = ", ".join(
+        dict.fromkeys(
+            value.strip()
+            for value in getattr(actor.actor, "aliases", {}).values()
+            if value
+            and value.strip()
+            and value.strip().casefold() != actor.actor.display_name.casefold()
+        )
+    ) or "none"
+    lexical = lexical_formulation(prompt)
+    context = runtime.observe(
+        actor,
+        _request(
+            task=prompt,
+            org_id=actor.profile.org_id,
+            actor_id=actor.actor.actor_id,
+            lex=identity_aware_lexical_formulations(
+                root,
+                actor,
+                prompt,
+                (lexical,),
+            ),
+            vec=(prompt,),
+            mode=RetrievalMode.HYBRID,
+            limit=limit,
+            open_sources=True,
+        ),
+        token_budget=min(actor.profile.default_context_budget, 1_500),
+    )
+    _write_observe_receipt(root, harness, prompt, context)
+    lines = [
+        "EGREGORE_ORG_CONTEXT_V1",
+        "Compiled automatically by EgregoreRuntime.observe after actor resolution and authorization.",
+        f"Actor ID: {actor.actor.actor_id}",
+        f"Actor display name: {actor.actor.display_name}",
+        f"Actor aliases: {aliases}",
+        f"Organization ID: {actor.profile.org_id}",
+        f"Runtime root: {root}",
+        "Run Egregore retrieval and workflow commands from this Runtime root. "
+        "Do not fall back to a launch checkout named elsewhere in the session.",
+        "Identity rule: `me` and `myself` mean this Actor ID and display name. "
+        "Use the display name for presentation and the Actor ID for ownership "
+        "and authorization; never infer identity from OS/Git/GitHub names.",
+        "Retrieval status: COMPLETE for this prompt. RETRIEVAL_ALREADY_PERFORMED=true. "
+        "SECOND_QUERY_ALLOWED=false. Do not invoke the search skill or run "
+        "`bin/search.sh query` again in this prompt turn.",
+        "Exact lifecycle questions are different: `bash bin/search.sh handoffs "
+        "[--mine|--sent|--addressed-to X|--sent-by X] [--status open] [--order newest|oldest] "
+        "[--limit N] [--open]` is a typed deterministic Runtime lookup, not a second query. "
+        "When the user asks an exact organizational-state question (latest/newest/oldest "
+        "handoff addressed to or sent by someone, open or unresolved handoffs) and this "
+        "packet's evidence cannot answer it, run that lookup in this same turn, emit the "
+        "memory-form retrieval beat once, and answer from its result. If it returns nothing, "
+        "say no matching handoff exists — never substitute semantic evidence.",
+        "Source access: OPENED_BY_OBSERVE through the Runtime read-policy boundary for the "
+        "packaged evidence below; do not open it again solely for verification.",
+        f"Context: {context.context_id}",
+        f"Profile revision: {context.profile_revision}",
+        f"Source revision: {context.source_revision}",
+        f"Lifecycle revision: {context.freshness.get('lifecycle_revision', 'unavailable')}",
+        f"Temporal scope: {context.freshness.get('temporal_scope', 'current')}",
+        "Evidence (authorized canonical content; canonical Markdown remains authoritative):",
+    ]
+    if not context.evidence:
+        lines.append("- No authorized evidence found.")
+    for position, evidence in enumerate(context.evidence, start=1):
+        excerpt = " ".join(evidence.content.split())
+        lines.extend(
+            (
+                f"[{position}] {evidence.canonical_path}",
+                f"artifact={evidence.artifact_id} revision={evidence.revision} reason={evidence.reason}",
+                excerpt,
+            )
+        )
+    lines.extend(
+        (
+            "If additional evidence beyond the opened content below is required, the next retrieval "
+            'action is only `bash bin/search.sh open "<another returned memory/... path>"`; do not '
+            "search again first and do not bypass the Runtime read-policy boundary. On Claude add "
+            "--context-packet so the full document attaches privately instead of printing raw "
+            "markdown into the transcript.",
+            "If the evidence cannot answer the question, state the evidence gap. Do not run a second "
+            "query in this prompt turn. A later user prompt that explicitly requests a new search "
+            "starts a new retrieval turn.",
+            "END_EGREGORE_ORG_CONTEXT_V1",
+        )
+    )
+    return "\n".join(lines)
+
+
+def _prompt_hook(args: argparse.Namespace) -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, OSError):
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    prompt = str(payload.get("prompt") or payload.get("user_prompt") or "").strip()
+    root = _prompt_root(payload, _root())
+    # A receipt is valid for one user-prompt turn only. Clearing it on every
+    # prompt preserves explicit/new searches while blocking a redundant skill
+    # query after this hook has already compiled useful evidence.
+    _clear_observe_receipt(root, args.harness)
+    prefetches_org_context = prompt_prefetches_org_context(prompt)
+    requests_actor_context = prompt_requests_actor_context(prompt)
+    if not prefetches_org_context and not requests_actor_context:
+        return 0
+    try:
+        runtime = local_runtime(root, push_remote=False)
+        if prefetches_org_context:
+            additional_context = _hook_context(
+                runtime,
+                root,
+                prompt,
+                args.harness,
+                args.limit,
+            )
+        else:
+            additional_context = _actor_context_block(
+                runtime,
+                root,
+                args.harness,
+            )
+    except Exception as exc:  # Hooks are advisory and must never block a prompt.
+        additional_context = (
+            "Egregore Runtime context was requested but the Local Runtime is unavailable "
+            f"({type(exc).__name__}). Do not guess actor identity. Use the search skill once only "
+            "when organizational evidence is required."
+        )
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": additional_context,
+                }
+            },
+            separators=(",", ":"),
+        )
+    )
+    return 0
+
+
+def _admin_status(args: argparse.Namespace) -> int:
+    """Stable-identity admin capability for shell surfaces — fails closed.
+
+    Egregore-surface admin protection only: repository members retain raw Git
+    access regardless of this answer, and callers must treat any failure as
+    non-admin.
+    """
+
+    root = _root()
+    result = {"admin": False, "display_name": None, "actor_id": None}
+    try:
+        runtime = local_runtime(root, push_remote=False)
+        actor = _actor(runtime, root, args.harness)
+        result["display_name"] = actor.actor.display_name
+        result["actor_id"] = actor.actor.actor_id
+        gate = runtime.admin_gate
+        result["admin"] = bool(gate is not None and gate.actor_is_admin(actor))
+    except Exception:
+        result = {"admin": False, "display_name": None, "actor_id": None}
+    print(json.dumps(result, sort_keys=True))
+    return 0
+
+
+def _access_status(args: argparse.Namespace) -> int:
+    """One authorized snapshot of identity, membership, and capabilities.
+
+    The Runtime authorization backend is the source of truth: every value is
+    a real authorize() decision, never derived independently by a UI. Any
+    failure reports status "attention" and nothing else — no partial claims.
+    """
+
+    root = _root()
+    try:
+        runtime = local_runtime(root, push_remote=False)
+        actor = _actor(runtime, root, args.harness)
+        gate = runtime.admin_gate
+
+        def allowed(*permissions: Permission) -> bool:
+            return all(
+                runtime.authorize(actor, permission).allowed
+                for permission in permissions
+            )
+
+        read_decision = runtime.authorize(actor, Permission.READ)
+        membership = actor.membership
+        out = {
+            "status": "ok",
+            "display_name": actor.actor.display_name,
+            "actor_id": actor.actor.actor_id,
+            "org_name": actor.profile.name,
+            "org_id": actor.profile.org_id,
+            "membership_status": membership.status if membership else "unknown",
+            "roles": sorted(membership.roles) if membership else [],
+            "admin": bool(gate is not None and gate.actor_is_admin(actor)),
+            "capabilities": {
+                "read": allowed(Permission.READ),
+                "create": allowed(Permission.WRITE),
+                "update": allowed(Permission.WRITE),
+                "publish": allowed(Permission.SHARE),
+                "notify": allowed(Permission.SHARE, Permission.EXECUTE),
+                "org_settings": allowed(Permission.ADMINISTER),
+            },
+            "shared_memory_scope": sorted(read_decision.scopes),
+        }
+    except Exception:
+        out = {"status": "attention"}
+    print(json.dumps(out, sort_keys=True))
+    return 0
+
+
+def _handoffs(args: argparse.Namespace) -> int:
+    """Typed lifecycle lookup — exact handoff questions, zero semantic search.
+
+    This is not a second model-led query: it is a bounded deterministic
+    operation over canonical artifact metadata, available even when an
+    attached Observe packet missed.
+    """
+
+    from .handoff_lookup import HandoffLookupService
+
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    actor = _actor(runtime, root, args.harness)
+    service = HandoffLookupService(runtime, root)
+    started = time.monotonic()
+    records = service.query(
+        actor,
+        addressed_to="me" if args.mine else args.addressed_to,
+        sent_by="me" if args.sent else args.sent_by,
+        status_filter=args.status,
+        order=args.order,
+        limit=args.limit,
+    )
+    lookup_ms = round((time.monotonic() - started) * 1000)
+    if args.timing:
+        print(f"lookup: {lookup_ms}ms", file=sys.stderr)
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "records": [record.__dict__ for record in records],
+                    "lookup_ms": lookup_ms,
+                },
+                sort_keys=True,
+            )
+        )
+        return 0
+    if not records:
+        print("no matching handoff exists for that filter")
+        return 0
+    for index, record in enumerate(records, start=1):
+        day = record.occurred_at.split("T")[0]
+        print(f"{index}. {day} · from {record.sender} · to {record.recipient} · {record.status} · {record.topic}")
+        if record.claim:
+            print(f"   claim: {record.claim}")
+        if record.ask:
+            print(f"   ask: {record.ask}")
+        print(f"   source: {record.canonical_path}")
+    if args.open and records:
+        content = runtime.open_source(actor, records[0].canonical_path)
+        print()
+        print(content)
+    return 0
+
+
+def _status(args: argparse.Namespace) -> int:
+    health = local_runtime(_root(), push_remote=False).retrieval_health()
+    if args.json:
+        print(json.dumps(health.to_dict(), indent=2))
+    else:
+        print(f"adapter: {health.adapter} {health.adapter_version}")
+        print(f"index spec: {health.index_spec_version}")
+        print(f"index revision: {health.index_revision}")
+        print(f"source revision: {health.source_revision}")
+        print(f"embedding: {health.embedding_state}")
+        print(f"readiness: {health.runtime_state}")
+        print(f"bm25 ready: {'yes' if health.bm25_ready else 'no'}")
+        print(f"semantic ready: {'yes' if health.semantic_ready else 'no'}")
+        print(f"semantic build: {health.semantic_source_revision or 'none'}")
+        print(f"worker pid: {health.runtime_pid or 'none'}")
+        print(f"endpoint: {health.runtime_endpoint or 'none'}")
+        print(f"index: {health.index_path or 'unknown'}")
+        print(f"collection: {health.collection or 'unknown'}")
+        print(f"available: {'yes' if health.available else 'no'}")
+        for warning in health.warnings:
+            print(f"warning: {warning}")
+    return 0 if health.available else 1
+
+
+_RUNTIME_MVP_VERSION = re.compile(
+    r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-runtime-mvp\.(0|[1-9]\d*)$"
+)
+
+
+def _upgrade_context(root: Path):
+    from .upgrade import build_cli_context
+
+    return build_cli_context(root)
+
+
+def _active_runtime_version(root: Path, store) -> str:
+    activation = store.load_activation()
+    if activation and activation.get("active_version"):
+        return str(activation["active_version"])
+    try:
+        package = json.loads(
+            (root / "packages" / "create-egregore" / "package.json").read_text(encoding="utf-8")
+        )
+        return str(package.get("version") or "unknown")
+    except (OSError, ValueError):
+        return "unknown"
+
+
+def _upgrade(args: argparse.Namespace) -> int:
+    from . import upgrade as upgrade_module
+    from .teamsync import team_sync
+
+    root = _root()
+    try:
+        store, engine, retriever = _upgrade_context(root)
+    except upgrade_module.UpgradeError as exc:
+        # Fail closed: no stable organization identity means no upgrade
+        # state — never fall back to a path-inferred identity.
+        print(str(exc), file=sys.stderr)
+        return 1
+    action = args.action
+
+    if action == "status":
+        state = upgrade_module.describe(store.load())
+        state["active_version"] = _active_runtime_version(root, store)
+        state["instance_hash"] = upgrade_module.instance_key(root)
+        memory_root = (root / "memory").resolve()
+        if memory_root.is_dir():
+            state["team_sync"] = team_sync(memory_root, fetch=bool(args.fetch)).to_dict()
+        print(json.dumps(state, indent=2, sort_keys=True))
+        return 0
+
+    if action == "init":
+        version = (args.candidate or "").strip()
+        if not _RUNTIME_MVP_VERSION.match(version):
+            # The protected publish path enforces the same scheme through
+            # bin/validate-create-egregore-prerelease.mjs; mirror it here so a
+            # retired-scheme candidate can never even start preparing.
+            print(
+                f"candidate {version!r} is not on the runtime-mvp prerelease "
+                "scheme (expected X.Y.Z-runtime-mvp.N)",
+                file=sys.stderr,
+            )
+            return 1
+        config = json.loads((root / "egregore.json").read_text(encoding="utf-8"))
+        org_id = str(config.get("org_id") or "")
+        if not org_id:
+            print("this instance has no stable org_id; refusing to stage an upgrade", file=sys.stderr)
+            return 1
+        existing = store.load()
+        if existing and existing.get("status") in (
+            upgrade_module.STATUS_PREPARING,
+            upgrade_module.STATUS_READY,
+        ):
+            print("an upgrade is already staged for this instance", file=sys.stderr)
+            return 1
+        tarball = Path(args.tarball).expanduser().resolve() if args.tarball else None
+        if tarball is None or not tarball.is_file():
+            print(
+                "upgrade init requires --tarball <candidate .tgz>: the upgrade "
+                "installs actual packaged bytes, never a version string",
+                file=sys.stderr,
+            )
+            return 1
+        state = upgrade_module.new_state(
+            instance_path=root,
+            org_id=org_id,
+            instance_hash=upgrade_module.instance_key(root),
+            candidate_version=version,
+            active_version=_active_runtime_version(root, store),
+            candidate_source=str(tarball),
+        )
+        store.write(state)
+        print(json.dumps(upgrade_module.describe(state), indent=2, sort_keys=True))
+        return 0
+
+    if action == "prepare":
+        state = store.load()
+        if state is None:
+            print("run `upgrade init --candidate <version>` first", file=sys.stderr)
+            return 1
+        worker = state.get("worker") or {}
+        if state.get("status") == upgrade_module.STATUS_PREPARING and worker.get("pid"):
+            if upgrade_module._pid_alive(worker["pid"]):
+                print(json.dumps(upgrade_module.describe(state), indent=2, sort_keys=True))
+                return 0
+        environment = dict(os.environ)
+        package_root = str(Path(__file__).resolve().parents[1])
+        environment["PYTHONPATH"] = (
+            f"{package_root}{os.pathsep}{environment['PYTHONPATH']}"
+            if environment.get("PYTHONPATH")
+            else package_root
+        )
+        process = subprocess.Popen(
+            (
+                sys.executable,
+                "-m",
+                "egregore_runtime.upgrade_worker",
+                "--repository-root",
+                str(root),
+            ),
+            cwd=root,
+            env=environment,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        state["worker"] = {"pid": process.pid, "started_at": int(time.time())}
+        state["status"] = upgrade_module.STATUS_PREPARING
+        store.write(state)
+        print(json.dumps(upgrade_module.describe(state, worker_alive=True), indent=2, sort_keys=True))
+        return 0
+
+    if action == "activate":
+        state = engine.activate()
+        print(json.dumps(upgrade_module.describe(state), indent=2, sort_keys=True))
+        return 0
+
+    if action == "cancel":
+        state = engine.cancel()
+        print(json.dumps(upgrade_module.describe(state), indent=2, sort_keys=True))
+        return 0
+
+    if action == "rollback":
+        state = engine.rollback()
+        print(json.dumps(upgrade_module.describe(state), indent=2, sort_keys=True))
+        return 0
+
+    print(f"unknown upgrade action: {action}", file=sys.stderr)
+    return 2
+
+
+def _team_sync_cmd(args: argparse.Namespace) -> int:
+    from .teamsync import team_sync
+
+    root = _root()
+    memory_root = (root / "memory").resolve()
+    if not memory_root.is_dir():
+        print(json.dumps({"state": "attention", "label": "Sync needs attention"}))
+        return 1
+    result = team_sync(memory_root, fetch=bool(args.fetch))
+    print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
+    return 0
+
+
+def _readiness(args: argparse.Namespace) -> int:
+    from .readiness import collect_report, render
+
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    report = collect_report(
+        root, runtime, harness=args.harness, session_id=_session_id(root)
+    )
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        tty = sys.stdout.isatty() and not args.plain
+        print(render(report, tty=tty))
+    ready = {item.key: item.stage for item in report.items}
+    return 0 if ready.get("search") == "ready" else 1
+
+
+def _sync(args: argparse.Namespace) -> int:
+    receipt = local_runtime(_root(), push_remote=False).synchronize()
+    if args.json:
+        print(json.dumps(receipt.to_dict(), indent=2))
+    else:
+        canonical = receipt.canonical_sync
+        retrieval = receipt.retrieval
+        print(f"synchronization: {receipt.status}")
+        print(
+            "canonical revision: "
+            f"{canonical.local_revision if canonical is not None else 'unavailable'}"
+        )
+        print(f"canonical current: {'yes' if receipt.canonical_current else 'no'}")
+        print(
+            "canonical changed: "
+            f"{'yes' if canonical is not None and canonical.changed else 'no'}"
+        )
+        print(
+            "lexical ready: "
+            f"{'yes' if retrieval is not None and retrieval.bm25_ready else 'no'}"
+        )
+        print(
+            "semantic: "
+            + (
+                "ready"
+                if retrieval is not None and retrieval.semantic_ready
+                else "building"
+                if receipt.semantic_building
+                else "unavailable"
+            )
+        )
+        print(
+            "index/source aligned: "
+            f"{'yes' if receipt.index_source_aligned else 'no'}"
+        )
+        if retrieval is not None:
+            print(f"index revision: {retrieval.index_revision}")
+            print(f"index source revision: {retrieval.index_source_revision or 'unavailable'}")
+            print(f"source revision: {retrieval.source_revision}")
+        for failure in receipt.failures:
+            print(f"failure: {failure}")
+    return 0 if receipt.status == "ready" else 1
+
+
+def _start(args: argparse.Namespace) -> int:
+    health = local_runtime(_root(), push_remote=False).start_retrieval()
+    print(json.dumps(health.to_dict(), indent=2) if args.json else health.runtime_state)
+    return 0 if health.available and health.bm25_ready else 1
+
+
+def _stop(args: argparse.Namespace) -> int:
+    health = local_runtime(_root(), push_remote=False).shutdown_retrieval()
+    print(json.dumps(health.to_dict(), indent=2) if args.json else "stopped")
+    return 0
+
+
+def _open(args: argparse.Namespace) -> int:
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    actor = _actor(runtime, root, args.harness)
+    sys.stdout.write(runtime.open_source(actor, args.path))
+    return 0
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("value must be a positive integer")
+    return parsed
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-runtime")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    query = commands.add_parser("query")
+    query.add_argument("--task", required=True)
+    query.add_argument("--lex", action="append", default=[])
+    query.add_argument("--vec", action="append", default=[])
+    query.add_argument("--mode", type=RetrievalMode, default=RetrievalMode.HYBRID)
+    query.add_argument("--limit", type=int, default=6)
+    query.add_argument("--harness", default=os.environ.get("EGREGORE_RUNTIME", "shell"))
+    query.add_argument(
+        "--new-search",
+        action="store_true",
+        help="run a new retrieval even when this prompt already has compiled Observe context",
+    )
+    query.add_argument("--temporal-scope", type=TemporalScope)
+    query.add_argument("--recent-days", type=_positive_int)
+    query.add_argument("--min-evidence", type=_positive_int, default=1)
+    query.add_argument("--compact", action="store_true")
+    query.add_argument("--json", action="store_true")
+    query.set_defaults(handler=_query)
+
+    prompt_hook = commands.add_parser("prompt-hook")
+    prompt_hook.add_argument("--harness", required=True)
+    prompt_hook.add_argument("--limit", type=int, default=6)
+    prompt_hook.set_defaults(handler=_prompt_hook)
+
+    status = commands.add_parser("status")
+    status.add_argument("--json", action="store_true")
+    status.set_defaults(handler=_status)
+
+    admin_status = commands.add_parser("admin-status")
+    admin_status.add_argument(
+        "--harness", default=os.environ.get("EGREGORE_RUNTIME", "shell")
+    )
+    admin_status.set_defaults(handler=_admin_status)
+
+    handoffs = commands.add_parser("handoffs")
+    handoffs.add_argument("--mine", action="store_true", help="addressed to the resolved actor")
+    handoffs.add_argument("--addressed-to", default=None)
+    handoffs.add_argument("--sent", action="store_true", help="sent by the resolved actor")
+    handoffs.add_argument("--sent-by", default=None)
+    handoffs.add_argument("--status", choices=("any", "open", "unresolved"), default="any")
+    handoffs.add_argument("--order", choices=("newest", "oldest"), default="newest")
+    handoffs.add_argument("--limit", type=_positive_int, default=1)
+    handoffs.add_argument("--open", action="store_true", help="open the top result through Runtime read policy")
+    handoffs.add_argument("--json", action="store_true")
+    handoffs.add_argument("--timing", action="store_true")
+    handoffs.add_argument(
+        "--harness", default=os.environ.get("EGREGORE_RUNTIME", "shell")
+    )
+    handoffs.set_defaults(handler=_handoffs)
+
+    access_status = commands.add_parser("access-status")
+    access_status.add_argument(
+        "--harness", default=os.environ.get("EGREGORE_RUNTIME", "shell")
+    )
+    access_status.set_defaults(handler=_access_status)
+
+    readiness = commands.add_parser("readiness")
+    readiness.add_argument("--json", action="store_true")
+    readiness.add_argument("--plain", action="store_true")
+    readiness.add_argument(
+        "--harness", default=os.environ.get("EGREGORE_RUNTIME", "shell")
+    )
+    readiness.set_defaults(handler=_readiness)
+
+    upgrade = commands.add_parser("upgrade")
+    upgrade.add_argument(
+        "action",
+        choices=("status", "init", "prepare", "activate", "cancel", "rollback"),
+    )
+    upgrade.add_argument("--candidate", default="")
+    upgrade.add_argument("--tarball", default="")
+    upgrade.add_argument("--fetch", action="store_true")
+    upgrade.set_defaults(handler=_upgrade)
+
+    team_sync_parser = commands.add_parser("team-sync")
+    team_sync_parser.add_argument("--fetch", action="store_true")
+    team_sync_parser.set_defaults(handler=_team_sync_cmd)
+
+    sync = commands.add_parser("sync")
+    sync.add_argument("--json", action="store_true")
+    sync.set_defaults(handler=_sync)
+
+    start = commands.add_parser("start")
+    start.add_argument("--json", action="store_true")
+    start.set_defaults(handler=_start)
+
+    stop = commands.add_parser("stop")
+    stop.add_argument("--json", action="store_true")
+    stop.set_defaults(handler=_stop)
+
+    source = commands.add_parser("open")
+    source.add_argument("path")
+    source.add_argument("--harness", default=os.environ.get("EGREGORE_RUNTIME", "shell"))
+    source.set_defaults(handler=_open)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    if getattr(args, "limit", 1) < 1:
+        raise ValueError("retrieval limit must be positive")
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (AuthorizationDenied, EgregoreRuntimeError, RuntimeError, ValueError) as exc:
+        print(f"egregore: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc