arkaos 4.14.3 → 4.15.0

package/VERSION

@@ -1 +1 @@
-4.14.3
+4.15.0

package/config/agent-roster.json

@@ -3,33 +3,49 @@
     "generator": "core/agents/roster_manifest.py",
     "purpose": "every specialist-gate owner resolves to a dispatchable agent source; installer/skill-deploy.js deploys these"
   },
+  "aliases": {
+    "andre": "backend-dev",
+    "bruno": "security-eng",
+    "carlos": "devops-eng",
+    "diana": "frontend-dev",
+    "gabriel": "architect",
+    "vasco": "dba"
+  },
+  "ambiguous_first_names": [],
   "gate_owners": {
     "architect": {
       "compiled": false,
+      "human_name": "Gabriel",
       "source": "departments/dev/agents/architect.md"
     },
     "backend-dev": {
       "compiled": true,
+      "human_name": "Andre",
       "source": "config/claude-agents/backend-dev.md"
     },
     "dba": {
       "compiled": true,
+      "human_name": "Vasco",
       "source": "config/claude-agents/dba.md"
     },
     "devops-eng": {
       "compiled": true,
+      "human_name": "Carlos",
       "source": "config/claude-agents/devops-eng.md"
     },
     "frontend-dev": {
       "compiled": false,
+      "human_name": "Diana",
       "source": "departments/dev/agents/frontend-dev.md"
     },
     "security-eng": {
       "compiled": true,
+      "human_name": "Bruno",
       "source": "config/claude-agents/security-eng.md"
     },
     "senior-dev": {
       "compiled": false,
+      "human_name": "",
       "source": "departments/dev/agents/senior-dev.md"
     }
   }

package/core/agents/authority_brief.py

@@ -0,0 +1,205 @@
+"""Authority brief — the write rules a session must know BEFORE it writes.
+
+The 2026-07-12 incident: a session was blocked writing a Laravel
+controller and, never having been told the rule existed, invented a
+"documented bug" to justify a bypass. Grep confirms the gap: ownership
+and ``specialist-bypass`` appear NOWHERE in CLAUDE.md, arka/SKILL.md,
+flow/SKILL.md or constitution.yaml. The deny message was the first and
+only place a session ever learned any of it.
+
+This module renders the ``[ARKA:AUTHORITY]`` block the SessionStart hook
+injects. Everything is GENERATED from ``config/agent-ownership.yaml`` +
+``config/agent-roster.json`` + the agents actually deployed on THIS
+machine — never hand-typed.
+
+Two rules this file learned the hard way (QG, redo 1):
+
+1. **Relevance is decided by the FULL literal spine, never its first
+   segment.** The first cut matched ``**/app/Http/Controllers/**`` in
+   this repo because a directory called ``dashboard/app`` exists — so it
+   taught a session five Laravel rules that govern nothing here.
+2. **Never truncate in silence.** The same cut capped the list at 8 and
+   dropped ``core/workflow/**/*.py`` and ``core/agents/**/*.py`` — the
+   rules that own the very files that PR was editing — under a heading
+   that claims "Owned paths in THIS project". A brief that hides the
+   rules that apply is the incident, re-delivered as its own fix.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+OWNERSHIP_YAML = REPO_ROOT / "config" / "agent-ownership.yaml"
+ROSTER_JSON = REPO_ROOT / "config" / "agent-roster.json"
+
+# Enough to state every rule that really applies to a project this size
+# (arka-os itself renders 14). Anything beyond is COUNTED, never dropped.
+_MAX_RULES = 16
+_MAX_FIELD = 120
+# `{` is a glob char too: the enforcer expands `{core,dashboard}` braces,
+# so treating that segment as a literal spine would make the brief DROP a
+# rule the gate enforces — the "brief hides an applicable rule" incident.
+_GLOB_CHARS = ("*", "?", "[", "{")
+# The brief lands in a system prompt. A pattern is operator-editable YAML
+# (agent-ownership.yaml is `lead_allowed`), so a newline in it could forge
+# an authority line — OWASP LLM01. Control bytes never reach the prompt.
+_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def _load(path: Path) -> dict:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        data = (
+            json.loads(text) if path.suffix == ".json" else yaml.safe_load(text)
+        )
+    except (json.JSONDecodeError, yaml.YAMLError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _clean(value: str) -> str:
+    """Strip control bytes and bound the length — prompt-injection guard."""
+    return _CONTROL_RE.sub("", str(value))[:_MAX_FIELD]
+
+
+def deployed_agents(agents_dirs: list[Path] | None = None) -> set[str]:
+    """Slugs the Task tool can actually dispatch on this machine."""
+    dirs = agents_dirs or [
+        Path.home() / ".claude" / "agents",
+        Path.cwd() / ".claude" / "agents",
+    ]
+    found: set[str] = set()
+    for base in dirs:
+        try:
+            for md in base.glob("*.md"):
+                found.add(md.stem.removeprefix("arka-"))
+        except OSError:
+            continue
+    return found
+
+
+def _spine(pattern: str) -> list[str]:
+    """The literal path segments of a glob: `**/app/Http/Controllers/**`
+    -> ['app', 'Http', 'Controllers']; `**/*.vue` -> []."""
+    return [
+        part for part in pattern.split("/")
+        if part and not any(ch in part for ch in _GLOB_CHARS)
+    ]
+
+
+def rule_applies(pattern: str, root: Path) -> bool:
+    """Does this rule govern anything in `root`?
+
+    The FULL spine must exist — checking only its first segment is what
+    made `**/app/Http/Controllers/**` look relevant here (a `dashboard/app`
+    directory exists) while the rules that actually govern the repo were
+    pushed out of the list. Extension-only rules always apply: they cost
+    one line and are honest ("write a .vue and frontend-dev owns it").
+    """
+    spine = _spine(pattern)
+    if not spine:
+        return True
+    joined = Path(*spine)
+    try:
+        if (root / joined).exists():
+            return True
+        # One level down covers monorepo layouts (dashboard/app/…).
+        return any(
+            (child / joined).exists()
+            for child in root.iterdir()
+            if child.is_dir() and not child.name.startswith(".")
+        )
+    except OSError:
+        return False
+
+
+def applicable_rules(rules: list[dict], root: Path) -> list[dict]:
+    return [
+        rule for rule in rules
+        if isinstance(rule, dict)
+        and rule.get("pattern")
+        and rule.get("owners")
+        and "*" not in rule["owners"]
+        and rule_applies(str(rule["pattern"]), root)
+    ]
+
+
+def _dispatch_status(named: set[str], owners_meta: dict,
+                     dispatchable: set[str]) -> list[str]:
+    status: list[str] = []
+    for slug in sorted(named):
+        # agent-roster.json is operator-editable and this line lands in a
+        # system prompt — human_name walks through _clean like every other
+        # field (QG redo 2: it was the one field that did not).
+        tokens = _clean(owners_meta.get(slug, {}).get("human_name", "")).split()
+        label = f"{slug} ({tokens[0]})" if tokens else slug
+        status.append(
+            f"{label} ok" if slug in dispatchable else f"{label} MISSING"
+        )
+    return status
+
+
+def render(cwd: str | Path | None = None,
+           agents_dirs: list[Path] | None = None) -> str:
+    """The [ARKA:AUTHORITY] block, or "" when there is nothing to say."""
+    ownership = _load(OWNERSHIP_YAML)
+    roster = _load(ROSTER_JSON)
+    rules = ownership.get("ownership") or []
+    owners_meta = roster.get("gate_owners") or {}
+    if not isinstance(rules, list) or not owners_meta:
+        return ""
+
+    root = Path(cwd) if cwd else Path.cwd()
+    relevant = applicable_rules(rules, root)
+    if not relevant:
+        return ""
+    shown, overflow = relevant[:_MAX_RULES], len(relevant) - _MAX_RULES
+
+    lines = [
+        "[ARKA:AUTHORITY] Write permissions (enforced by a PreToolUse gate)",
+        "1. Your last [arka:routing] / [arka:dispatch] marker is an "
+        "AUTHORIZATION TOKEN a gate reads before every Write/Edit. It is "
+        "not narration.",
+        "2. Owned paths in THIS project (first match wins):",
+    ]
+    named: set[str] = set()
+    for rule in shown:
+        owners = [_clean(o) for o in rule["owners"]]
+        named.update(owners)
+        lines.append(
+            f"     {_clean(rule['pattern']):<26s} -> {', '.join(owners)}"
+        )
+    if overflow > 0:
+        lines.append(
+            f"     (+{overflow} more — see config/agent-ownership.yaml)"
+        )
+
+    status = _dispatch_status(named, owners_meta, deployed_agents(agents_dirs))
+    lines.append(
+        f"3. Dispatchable here (Task subagent_type): {', '.join(status)}"
+    )
+    if any(entry.endswith("MISSING") for entry in status):
+        lines.append("   MISSING -> run `npx arkaos update` (never bypass).")
+    lines.append(
+        "4. The dispatched specialist writes with NO block. Retrying a "
+        "blocked Write never works — dispatch instead."
+    )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    brief = render()
+    print(brief or "(no ownership rules apply to this directory)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/agents/roster_manifest.py

@@ -68,6 +68,55 @@ def _resolve_source(slug: str) -> Path | None:
     return None
 
 
+def _agent_yaml(slug: str) -> Path | None:
+    matches = sorted(DEPARTMENTS_DIR.glob(f"*/agents/**/{slug}.yaml"))
+    return matches[0] if matches else None
+
+
+def _human_name(slug: str) -> str:
+    source = _agent_yaml(slug)
+    if source is None:
+        return ""
+    try:
+        data = yaml.safe_load(source.read_text(encoding="utf-8"))
+    except yaml.YAMLError:
+        return ""
+    return str(data.get("name") or "") if isinstance(data, dict) else ""
+
+
+def _first_name(human: str) -> str:
+    """'Andre — Backend Core Lead' -> 'andre'."""
+    return human.split()[0].split("—")[0].strip().lower() if human else ""
+
+
+def build_aliases(entries: dict[str, dict]) -> dict[str, str]:
+    """First-name -> owner slug, resolved WITHIN the gate-owner set.
+
+    Sessions route by human name (``[arka:dispatch] paulo -> diana``) but
+    ownership rules name slugs (``frontend-dev``). Unresolved, that
+    mismatch blocked the RIGHT specialist from her own files: 22 of 189
+    measured blocks. (The 22 `senior-dev` blocks are a separate, still
+    open class: there the slug IS the persona, so no alias helps.)
+
+    Scoping to gate owners is what makes this safe. Globally, ``diana``
+    is ambiguous (frontend-dev AND hr-specialist) and so is ``andre``
+    (backend-dev AND growth-engineer) — a naive first-name alias would
+    trade one bug for a worse one. Among the owners the gate can
+    actually demand, both are unique. Anything still ambiguous here is
+    REFUSED, never guessed.
+    """
+    by_first: dict[str, set[str]] = {}
+    for slug in entries:
+        first = _first_name(_human_name(slug))
+        if first:
+            by_first.setdefault(first, set()).add(slug)
+    return {
+        first: next(iter(slugs))
+        for first, slugs in sorted(by_first.items())
+        if len(slugs) == 1
+    }
+
+
 def build_roster() -> dict:
     owners = gate_owners()
     entries: dict[str, dict] = {}
@@ -80,6 +129,7 @@ def build_roster() -> dict:
         entries[slug] = {
             "source": str(source.relative_to(REPO_ROOT)),
             "compiled": source.parent == COMPILED_DIR,
+            "human_name": _human_name(slug),
         }
     if ghosts:
         raise ValueError(
@@ -88,6 +138,14 @@ def build_roster() -> dict:
             f"config/agent-ownership.yaml; a gate must never demand an "
             f"owner nobody can invoke"
         )
+    aliases = build_aliases(entries)
+    ambiguous = sorted(
+        first
+        for first in {
+            _first_name(e["human_name"]) for e in entries.values()
+        }
+        if first and first not in aliases
+    )
     return {
         "_meta": {
             "generator": "core/agents/roster_manifest.py",
@@ -97,6 +155,8 @@ def build_roster() -> dict:
             ),
         },
         "gate_owners": entries,
+        "aliases": aliases,
+        "ambiguous_first_names": ambiguous,
     }
 
 

package/core/hooks/pre_tool_use.py

@@ -26,6 +26,7 @@ the specialist and flow gates via their ``messages=`` params.
 
 from __future__ import annotations
 
+import contextlib
 import sys
 from pathlib import Path
 
@@ -65,19 +66,26 @@ class _MessagesOnce:
     def __init__(self, transcript_path: str):
         self._path = transcript_path
         self._messages: list[str] | None = None
+        self._sidechain: bool | None = None
 
     def peek(self) -> list[str] | None:
         return self._messages
 
+    def sidechain_active(self) -> bool | None:
+        """Scope of the most recent assistant record; None before load()."""
+        return self._sidechain
+
     def load(self) -> list[str] | None:
         if self._messages is None:
             try:
-                from core.workflow.flow_enforcer import (
-                    _load_last_assistant_messages,
-                )
-                self._messages = _load_last_assistant_messages(
-                    self._path, _ASSISTANT_WINDOW
-                )
+                # Scope-aware since P0.2: the window counts MAIN-scope
+                # messages only, so interleaved subagent records cannot
+                # evict the routing marker; sidechain-ness feeds the
+                # specialist gate's persistence guard.
+                from core.workflow.transcript_scope import split_from_path
+                split = split_from_path(self._path)
+                self._messages = split.main[-_ASSISTANT_WINDOW:]
+                self._sidechain = split.active_sidechain
             except Exception:
                 return None
         return self._messages
@@ -104,10 +112,8 @@ def _kb_gate(root: str, tool_name: str, session_id: str, query: str) -> int | No
     decision = evaluate_research_gate(
         tool_name=tool_name, session_id=session_id, query=query
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
-    except Exception:
-        pass
     if not decision.allow:
         return _deny(decision.to_stderr_message())
     if decision.nudge and decision.to_stderr_message():
@@ -150,8 +156,9 @@ def _specialist_gate(
         cwd=cwd,
         tool_input=tool_input,
         messages=shared,
+        is_sidechain=messages.sidechain_active(),
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(
             session_id=session_id,
             tool=tool_name,
@@ -160,8 +167,6 @@ def _specialist_gate(
             target_file=str(tool_input.get("file_path", "")),
             model_requested=str(tool_input.get("model", "")),
         )
-    except Exception:
-        pass
     if not decision.allow:
         return _deny(decision.to_stderr_message())
     return None
@@ -206,10 +211,8 @@ def _frontend_gate(
         tool_input=tool_input,
         messages=messages.load(),
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
-    except Exception:
-        pass
     if not decision.allow:
         return _deny(decision.to_stderr_message())
     if decision.to_stderr_message():
@@ -259,12 +262,10 @@ def _flow_gate(
         # env bypass, classifier flag, marker cache) before reading.
         messages=messages.peek(),
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(
             session_id=session_id, tool=tool_name, decision=decision, cwd=cwd
         )
-    except Exception:
-        pass
     if decision.allow:
         # Grace path: allow, but surface the non-blocking warning so the
         # operator sees the routing nudge instead of a silent pass.
@@ -326,4 +327,4 @@ if __name__ == "__main__":
     except Exception:
         # Fail open — the bash version piped every heredoc through
         # `2>/dev/null` and exited 0 on internal errors.
-        raise SystemExit(0)
+        raise SystemExit(0) from None

package/core/hooks/session_start.py

@@ -242,6 +242,30 @@ def _ensure_dashboard(repo: str, config: dict) -> None:
     )
 
 
+def _authority_brief(cwd: str) -> str:
+    """[ARKA:AUTHORITY] — who may write what, BEFORE the first Write.
+
+    The 2026-07-12 incident happened because this information existed
+    nowhere in the prompt surface: a session met the ownership rule for
+    the first time in a deny message, and rationalized a bypass instead
+    of dispatching. Generated per project, never hand-typed.
+    """
+    try:
+        from core.agents.authority_brief import render
+        brief = render(cwd)
+    except Exception as exc:
+        # But it must not fail SILENTLY either: a swallowed error here
+        # restores the exact pre-incident state (a session writing with no
+        # idea the rules exist). One honest line beats a silent void.
+        return (
+            f"\n\n[ARKA:AUTHORITY] unavailable ({type(exc).__name__}) — "
+            f"write rules could not be rendered; check "
+            f"config/agent-ownership.yaml. Dispatch the owning specialist "
+            f"rather than assuming you may write."
+        )
+    return f"\n\n{brief}" if brief else ""
+
+
 def build_message(cwd: str) -> str:
     repo = repo_path()
     config = _config()
@@ -254,6 +278,7 @@ def build_message(cwd: str) -> str:
     msg += _drift(version)
     msg += _EVIDENCE_CONTRACT
     msg += _META_TAG_CONTRACT
+    msg += _authority_brief(cwd)
     msg += _model_fabric()
     _trigger_reorganizer(repo, config)
     _ensure_dashboard(repo, config)

package/core/workflow/specialist_authorization.py

@@ -0,0 +1,140 @@
+"""Persistent per-session persona — closes the specialist gate fail-open.
+
+The specialist gate reads the persona from the last ``[arka:routing]`` /
+``[arka:dispatch]`` marker in a 20-message window. When the marker rolls
+out of the window the gate returned ALLOW (``no-routing-tag``) — 4,093
+of 5,683 telemetry records (72%). Routing once and hammering the gate
+with 20 messages of noise was a winning strategy.
+
+Fix mirrors ``design_authorization`` (#297, frontend gate): **persist on
+observe, consult before allow**. Whenever ``evaluate`` sees a marker in
+the window it confirms the resolved persona here; when the window shows
+nothing, a valid persisted persona for the session decides exactly as if
+the marker were still visible — including deciding BLOCK.
+
+Two deliberate properties:
+
+- **The record is keyed by session_id AND the transcript file's name.**
+  A dispatched subagent runs on its own transcript (ADR
+  2026-05-28-specialist-dispatch-subagent-blindspot), so it can never
+  inherit the parent's persisted persona and be blocked from the very
+  files it was dispatched to write — even if it shares the session_id.
+- **A session that never routed stays un-restored** (``never-routed``
+  keeps today's ALLOW): this module only closes the eviction hole; the
+  hard flip for never-routed sessions is a separate, telemetry-gated
+  decision.
+
+State dir: ``/tmp/arkaos-specialist-auth`` (override via
+``ARKA_SPECIALIST_AUTH_DIR``).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import time
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+from core.shared.temp_paths import arkaos_temp_dir
+
+_safe_session_id = _safe_session_id_module.safe_session_id
+
+# A working session; a stale /tmp record expires on its own.
+DEFAULT_TTL_SECONDS = 12 * 60 * 60
+
+
+def _base_dir() -> Path:
+    override = os.environ.get("ARKA_SPECIALIST_AUTH_DIR", "").strip()
+    return Path(override) if override else arkaos_temp_dir(
+        "arkaos-specialist-auth"
+    )
+
+
+def _auth_path(session_id: str) -> Path | None:
+    safe = _safe_session_id(session_id)
+    return (_base_dir() / f"{safe}.json") if safe else None
+
+
+def _read(path: Path | None) -> dict:
+    if path is None or not path.exists():
+        return {}
+    try:
+        # errors="replace", like transcript_scope: a non-UTF8 byte in an
+        # operator-writable /tmp file must degrade to "no record", never
+        # raise through evaluate() into the hook's exit-0 (QG redo 3 —
+        # an uncaught UnicodeDecodeError WAS a silent gate bypass).
+        raw = path.read_text(encoding="utf-8", errors="replace")
+        data = json.loads(raw)
+    except (ValueError, OSError):  # JSONDecodeError/UnicodeDecodeError ⊂ ValueError
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def confirm(
+    session_id: str,
+    transcript_path: str,
+    persona: str,
+    marker: str,
+    persona_raw: str | None = None,
+    alias_resolved: bool = False,
+) -> None:
+    """Persist the persona observed in the window (marker seen)."""
+    if not persona or not transcript_path:
+        return
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps({
+                "persona": persona,
+                "marker": marker,
+                "persona_raw": persona_raw,
+                "alias_resolved": bool(alias_resolved),
+                "transcript": Path(transcript_path).name,
+                "confirmed_ts": time.time(),
+            }),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass  # authorization state must never block the hook
+
+
+def confirmed(
+    session_id: str,
+    transcript_path: str,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+) -> dict | None:
+    """Return the persisted persona record, or None.
+
+    None unless: record exists, TTL holds, the persona is non-empty AND
+    the record was written for THIS transcript file — the property that
+    keeps a parent's persona out of a subagent's evaluation.
+    """
+    if not transcript_path:
+        return None
+    data = _read(_auth_path(session_id))
+    ts = data.get("confirmed_ts")
+    # isinstance, not float(): a string in a corrupt-but-valid JSON would
+    # raise straight through evaluate() — the same silent-bypass class as
+    # the non-UTF8 hole (QG redo 3).
+    if not isinstance(ts, (int, float)) or time.time() - ts > ttl_seconds:
+        return None
+    if data.get("transcript") != Path(transcript_path).name:
+        return None
+    persona = data.get("persona")
+    if not isinstance(persona, str) or not persona:
+        return None
+    return data
+
+
+def clear(session_id: str) -> None:
+    """Remove authorization state for a session (tests / session end)."""
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    with contextlib.suppress(FileNotFoundError, OSError):
+        path.unlink()

package/core/workflow/specialist_enforcer.py

@@ -13,29 +13,42 @@ Used bypasses are logged to telemetry for accountability.
 Feature flag: `hooks.specialistEnforcement` in ~/.arkaos/config.json.
 
 Architectural note (per ADR 2026-05-28-specialist-dispatch-subagent-
-blindspot): the enforcer is a NEGATIVE gate on the parent transcript
-only. Subagent writes pass through as `no-routing-tag` because Claude
+blindspot, amended by P0.2): the enforcer is a NEGATIVE gate on the
+parent transcript only. Subagent writes pass through because Claude
 Code isolates subagent transcripts from the parent. The positive
 `owner-match` path is exercised when the parent emits `[arka:dispatch]`
 inline (e.g., the orchestrator impersonating a specialist) and remains
 for forward compatibility if parent-transcript visibility ever ships.
 
+Fail-open closed (P0.2): a marker that rolls out of the 20-message
+window no longer reopens the gate — the persona observed in the window
+is persisted per session+transcript (specialist_authorization) and
+restored when the window shows nothing, deciding exactly as if the
+marker were visible. The old blanket `no-routing-tag` (72% of all
+telemetry) splits into `never-routed` (session never emitted a marker;
+still ALLOW — hardening THAT is a separate, telemetry-gated decision)
+and `subagent-scope` (sidechain evaluation; ADR behavior, now
+measurable). The window itself counts main-scope messages only
+(transcript_scope), so interleaved subagent records cannot evict the
+marker.
+
 Read by: config/hooks/pre-tool-use.sh between the KB-gate and the
 flow-gate. Same Decision JSON contract as core.workflow.flow_enforcer.
 """
 
+import contextlib
 import json
 import re
 from contextlib import contextmanager
 from dataclasses import asdict, dataclass, field
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from functools import lru_cache
 from pathlib import Path
 
 import yaml
 
 from core.shared import safe_session_id as _safe_session_id_module
-from core.workflow.flow_enforcer import _load_last_assistant_messages
+from core.workflow import specialist_authorization, transcript_scope
 
 try:
     import fcntl  # POSIX only
@@ -55,10 +68,8 @@ def _locked_append(path: Path):
         yield fh
     finally:
         if _HAS_FLOCK:
-            try:
+            with contextlib.suppress(OSError):
                 fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
-            except OSError:
-                pass
         fh.close()
 
 
@@ -73,6 +84,11 @@ OWNERSHIP_YAML_PATH = (
     / "config"
     / "agent-ownership.yaml"
 )
+ROSTER_PATH = (
+    Path(__file__).resolve().parent.parent.parent
+    / "config"
+    / "agent-roster.json"
+)
 
 GATED_TOOLS: frozenset[str] = frozenset(
     {"Write", "Edit", "MultiEdit", "NotebookEdit"}
@@ -85,8 +101,13 @@ ROUTING_RE = re.compile(
 DISPATCH_RE = re.compile(
     r"\[arka:dispatch\]\s*[\w-]+\s*->\s*([\w-]+)", re.IGNORECASE
 )
+# Single-line, length-bounded body: the lazy `([^\]]+?)\s*` form
+# backtracked catastrophically on an unclosed marker (4000 trailing
+# spaces = 22s) — inside a BLOCKING PreToolUse hook, on model-emitted
+# text. 400 chars is far above any substantive reason; beyond it the
+# marker simply does not parse and the gate stays closed.
 BYPASS_RE = re.compile(
-    r"\[arka:specialist-bypass\s+([^\]]+?)\s*\]", re.IGNORECASE
+    r"\[arka:specialist-bypass\s+([^\]\n]{1,400})\]", re.IGNORECASE
 )
 
 ASSISTANT_WINDOW = 20
@@ -107,22 +128,50 @@ class Decision:
     bypass_used: bool = False
     bypass_reason: str | None = None
     target_file: str | None = None
+    # Alias resolution (PR-1): the marker said "diana", the rules say
+    # "frontend-dev" — record both so telemetry can prove the fix.
+    persona_raw: str | None = None
+    alias_resolved: bool = False
+    # Fail-open taxonomy (P0.2): where the persona came from ("window" |
+    # "persisted" | ""), whether the ACTIVE scope is a sidechain, and how
+    # far the marker sits from the window's end (None = not in window).
+    persona_source: str = ""
+    is_sidechain: bool = False
+    msgs_since_marker: int | None = None
 
     def to_stderr_message(self) -> str:
+        """The message a blocked session reads.
+
+        Rewritten after the 2026-07-12 incident, where a session read the
+        old text and went looking for a bug to justify a bypass. Three
+        changes carry the weight: it refuses the false diagnosis up front,
+        it hands over the correct path already filled in (two copyable
+        lines), and it demotes the bypass to what it is — an audited
+        exception the operator sees. The old text also called EVERY
+        persona "(lead)", so a blocked specialist was told she was a lead:
+        that actively fed the "the gate is buggy" story.
+        """
         if self.allow:
             return ""
-        persona = self.current_persona or "lead"
-        owners = ", ".join(self.required_owners) or "specialist"
+        persona = self.current_persona or "unrouted"
+        owner = (self.required_owners or ["the owning specialist"])[0]
+        owners = ", ".join(self.required_owners) or "the owning specialist"
         target = self.target_file or "this file"
         return (
-            f"[ARKA:SPECIALIST] {persona} (lead) is not authorised to write "
-            f"{target}. Required owners: {owners}. Choose one: (1) dispatch "
-            f"the specialist via the Agent tool AND emit "
-            f"`[arka:dispatch] {persona} -> <specialist>` immediately before "
-            f"the dispatch call (NON-NEGOTIABLE constitution rule "
-            f"`dispatch-must-be-announced`), OR (2) add "
-            f"`[arka:specialist-bypass <reason>]` to the same assistant "
-            f"message to override (logged for accountability)."
+            f"[ARKA:SPECIALIST] BLOCKED. {target} is owned by: {owners} "
+            f"— dispatch any ONE of them. You are {persona}.\n"
+            f"This is NOT a bug. The gate is working as designed. Retrying "
+            f"this Write will fail again, every time.\n"
+            f"DO THIS — two lines, and the specialist writes with no block:\n"
+            f"    [arka:dispatch] {persona} -> {owner}\n"
+            f"    Task(subagent_type=\"{owner}\", prompt=\"<what you were "
+            f"about to write>\")\n"
+            f"Audited exception (visible to the operator in the "
+            f"specialist-dispatch telemetry: `arka-py -m "
+            f"core.governance.specialist_telemetry_cli today`) — ONLY if "
+            f"no specialist can do this:\n"
+            f"    [arka:specialist-bypass owner={owner} reason=<24+ chars "
+            f"explaining why a specialist cannot>]"
         )
 
 
@@ -139,8 +188,15 @@ class _Ctx:
     messages: list[str] = field(default_factory=list)
     persona: str | None = None
     marker: str | None = None
+    persona_raw: str | None = None
+    alias_resolved: bool = False
     config: dict = field(default_factory=dict)
     preloaded_messages: list[str] | None = None
+    persona_source: str = ""
+    # None = self-detect from the transcript; the consolidated hook passes
+    # the value it computed while parsing (parse-once contract, PR-6).
+    is_sidechain: bool | None = None
+    msgs_since_marker: int | None = None
 
 
 # ─── Config + Ownership loaders ────────────────────────────────────────
@@ -233,34 +289,110 @@ def _glob_match(pattern: str, path: str) -> bool:
 # ─── Persona, bypass, ownership resolution ─────────────────────────────
 
 
-def _resolve_persona(messages: list[str]) -> tuple[str | None, str | None]:
-    """Find the current persona, scanning newest-to-oldest assistant turns.
+def _load_aliases() -> dict[str, str]:
+    """First-name -> owner slug, from the generated roster.
+
+    Sessions dispatch by human name (``-> diana``); ownership rules name
+    slugs (``frontend-dev``). Without this, the RIGHT specialist was
+    blocked from her own files — 22 of 189 measured blocks. The roster
+    only emits aliases that are unambiguous among gate owners, and never
+    guesses (core/agents/roster_manifest.py::build_aliases).
+    """
+    try:
+        data = json.loads(ROSTER_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    aliases = data.get("aliases")
+    return aliases if isinstance(aliases, dict) else {}
+
+
+def _normalize_persona(raw: str) -> tuple[str, bool]:
+    """Return (slug, alias_resolved). Unknown names pass through."""
+    slug = _load_aliases().get(raw)
+    return (slug, True) if slug else (raw, False)
+
+
+def _resolve_persona(
+    messages: list[str],
+) -> tuple[str | None, str | None, str | None, bool]:
+    """Find the current persona: (slug, marker, raw, alias_resolved).
 
     Dispatch tag wins over routing because dispatching is more specific.
+    The name is normalized through the roster aliases, so a marker that
+    names the human (``-> diana``) matches an ownership rule that names
+    the slug (``frontend-dev``).
     """
     for text in reversed(messages):
         dispatch = DISPATCH_RE.search(text)
         if dispatch:
-            return dispatch.group(1).lower(), "dispatch"
+            raw = dispatch.group(1).lower()
+            slug, resolved = _normalize_persona(raw)
+            return slug, "dispatch", raw, resolved
         routing = ROUTING_RE.search(text)
         if routing:
-            return routing.group(1).lower(), "routing"
-    return None, None
+            raw = routing.group(1).lower()
+            slug, resolved = _normalize_persona(raw)
+            return slug, "routing", raw, resolved
+    return None, None, None, False
+
+
+# A bypass must cost more than doing the right thing. Before the
+# 2026-07-12 incident the only barrier was a non-empty string, and the
+# deny message advertised the bypass beside the dispatch as an equal
+# option — the single place in the whole prompt surface that taught it.
+_MIN_BYPASS_REASON = 24
+_EMPTY_REASONS = (
+    "typo", "quick fix", "quickfix", "trivial", "urgent", "just this once",
+    "small change", "minor", "one char", "fast", "quick typo fix",
+    "just a quick typo fix", "just a quick typo fix honestly",
+    "nothing important", "it is faster this way",
+)
+# Structured form the deny message teaches: `owner=<slug> reason=<text>`.
+_BYPASS_STRUCTURED_RE = re.compile(
+    r"^owner=(?P<owner>[\w-]+)\s+reason=(?P<reason>.*)$",
+    re.IGNORECASE | re.DOTALL,
+)
 
 
-def _find_bypass(messages: list[str]) -> str | None:
-    """Return bypass reason from LAST assistant message, or None.
+def _reason_is_substantive(reason: str) -> bool:
+    """A reason must say something. QG redo 1 caught the hole: the floor
+    was applied to the WHOLE marker body, so
+    ``owner=senior-dev reason=`` (24 chars of boilerplate, empty reason)
+    opened the gate — with the deny message teaching that very template.
+    The floor now applies to the reason ALONE."""
+    reason = reason.strip()
+    if len(reason) < _MIN_BYPASS_REASON:
+        return False
+    normalized = reason.lower().strip(" .!,;")
+    return normalized not in _EMPTY_REASONS
+
+
+def _find_bypass(messages: list[str], owners: list[str] | None = None) -> str | None:
+    """Return the bypass reason from the LAST assistant message, or None.
 
     Scope is strict: only the immediately preceding assistant message can
-    grant a bypass. Empty / whitespace reasons are rejected.
+    grant a bypass. The structured form is required in spirit — a bare
+    legacy reason is still accepted for one release, but it must clear the
+    same substance floor. When ``owners`` is given, a structured
+    ``owner=`` that names someone other than an actual owner is rejected:
+    a bypass may not invent its own justification target.
     """
     if not messages:
         return None
     match = BYPASS_RE.search(messages[-1])
     if not match:
         return None
-    reason = match.group(1).strip()
-    return reason if reason else None
+    body = match.group(1).strip()
+    structured = _BYPASS_STRUCTURED_RE.match(body)
+    if structured:
+        if owners:
+            claimed = structured.group("owner").lower()
+            if claimed not in {o.lower() for o in owners}:
+                return None
+        reason = structured.group("reason")
+    else:
+        reason = body
+    return reason.strip() if _reason_is_substantive(reason) else None
 
 
 def _match_ownership(
@@ -285,6 +417,15 @@ def _is_lead_allowed(file_path: str, patterns: list[str]) -> bool:
 # ─── Pipeline stages (B1 refactor) ─────────────────────────────────────
 
 
+def _scope_fields(ctx: _Ctx) -> dict:
+    """The P0.2 taxonomy fields every post-populate Decision carries."""
+    return {
+        "persona_source": ctx.persona_source,
+        "is_sidechain": bool(ctx.is_sidechain),
+        "msgs_since_marker": ctx.msgs_since_marker,
+    }
+
+
 def _check_tool_gated(ctx: _Ctx) -> Decision | None:
     if ctx.tool_name not in GATED_TOOLS:
         return Decision(allow=True, reason="tool-not-gated")
@@ -297,8 +438,15 @@ def _check_feature_flag(ctx: _Ctx) -> Decision | None:
     return None
 
 
+def _msgs_since_marker(messages: list[str]) -> int | None:
+    for i, text in enumerate(reversed(messages)):
+        if DISPATCH_RE.search(text) or ROUTING_RE.search(text):
+            return i
+    return None
+
+
 def _populate_context(ctx: _Ctx) -> None:
-    """Extract file_path, load ownership config, load + resolve transcript."""
+    """Extract file_path, load ownership, resolve persona (P0.2 fail-open)."""
     if ctx.tool_input and isinstance(ctx.tool_input, dict):
         ctx.file_path = str(
             ctx.tool_input.get("file_path")
@@ -309,16 +457,55 @@ def _populate_context(ctx: _Ctx) -> None:
     if ctx.preloaded_messages is not None:
         ctx.messages = ctx.preloaded_messages[-ASSISTANT_WINDOW:]
     else:
-        ctx.messages = _load_last_assistant_messages(
-            ctx.transcript_path, ASSISTANT_WINDOW
+        split = transcript_scope.split_from_path(ctx.transcript_path)
+        ctx.messages = split.main[-ASSISTANT_WINDOW:]
+        if ctx.is_sidechain is None:
+            ctx.is_sidechain = split.active_sidechain
+    ctx.is_sidechain = bool(ctx.is_sidechain)
+    _resolve_or_restore_persona(ctx)
+
+
+def _resolve_or_restore_persona(ctx: _Ctx) -> None:
+    """Persist-on-observe + consult-before-allow (P0.2, mirrors #297).
+
+    Marker in the window -> persist the resolved persona. Window empty of
+    markers -> a valid persisted persona for THIS session+transcript
+    decides as if the marker were still visible — including deciding
+    BLOCK. Sidechain evaluations never consult the parent's persistence
+    (the dispatched specialist must keep writing with no block, per the
+    ADR).
+    """
+    ctx.persona, ctx.marker, ctx.persona_raw, ctx.alias_resolved = (
+        _resolve_persona(ctx.messages)
+    )
+    if ctx.persona is not None:
+        ctx.persona_source = "window"
+        ctx.msgs_since_marker = _msgs_since_marker(ctx.messages)
+        specialist_authorization.confirm(
+            ctx.session_id, ctx.transcript_path,
+            persona=ctx.persona, marker=ctx.marker or "",
+            persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        )
+    elif not ctx.is_sidechain:
+        restored = specialist_authorization.confirmed(
+            ctx.session_id, ctx.transcript_path
         )
-    ctx.persona, ctx.marker = _resolve_persona(ctx.messages)
+        if restored:
+            ctx.persona = restored["persona"]
+            ctx.marker = restored.get("marker") or None
+            ctx.persona_raw = restored.get("persona_raw")
+            ctx.alias_resolved = bool(restored.get("alias_resolved"))
+            ctx.persona_source = "persisted"
 
 
 def _check_no_persona(ctx: _Ctx) -> Decision | None:
     if ctx.persona is None:
+        # Taxonomy (P0.2): the old blanket "no-routing-tag" (72% of all
+        # telemetry) splits into what actually happened.
+        reason = "subagent-scope" if ctx.is_sidechain else "never-routed"
         return Decision(
-            allow=True, reason="no-routing-tag", target_file=ctx.file_path,
+            allow=True, reason=reason, target_file=ctx.file_path,
+            **_scope_fields(ctx),
         )
     return None
 
@@ -329,7 +516,7 @@ def _check_c_suite(ctx: _Ctx) -> Decision | None:
         return Decision(
             allow=True, reason="c-suite-override",
             current_persona=ctx.persona, marker_found=ctx.marker,
-            target_file=ctx.file_path,
+            target_file=ctx.file_path, **_scope_fields(ctx),
         )
     return None
 
@@ -340,7 +527,7 @@ def _check_lead_allowed_file(ctx: _Ctx) -> Decision | None:
         return Decision(
             allow=True, reason="lead-allowed-file",
             current_persona=ctx.persona, marker_found=ctx.marker,
-            target_file=ctx.file_path,
+            target_file=ctx.file_path, **_scope_fields(ctx),
         )
     return None
 
@@ -352,7 +539,7 @@ def _decide_open_access(
     return Decision(
         allow=True, reason=reason, current_persona=ctx.persona,
         marker_found=ctx.marker, target_file=ctx.file_path,
-        required_owners=owners,
+        required_owners=owners, **_scope_fields(ctx),
     )
 
 
@@ -360,7 +547,9 @@ def _decide_owner_match(ctx: _Ctx, owners: list[str]) -> Decision:
     return Decision(
         allow=True, reason=f"owner-match:{ctx.persona}",
         current_persona=ctx.persona, marker_found=ctx.marker,
-        target_file=ctx.file_path, required_owners=owners,
+        target_file=ctx.file_path,
+        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        required_owners=owners, **_scope_fields(ctx),
     )
 
 
@@ -368,8 +557,10 @@ def _decide_bypass(ctx: _Ctx, owners: list[str], reason: str) -> Decision:
     return Decision(
         allow=True, reason="bypass-with-reason",
         current_persona=ctx.persona, marker_found=ctx.marker,
-        target_file=ctx.file_path, required_owners=owners,
-        bypass_used=True, bypass_reason=reason,
+        target_file=ctx.file_path,
+        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        required_owners=owners, bypass_used=True, bypass_reason=reason,
+        **_scope_fields(ctx),
     )
 
 
@@ -379,7 +570,9 @@ def _decide_block(ctx: _Ctx, owners: list[str]) -> Decision:
         allow=False,
         reason=f"lead-blocked:{ctx.persona}-not-in-[{','.join(owners_lower)}]",
         current_persona=ctx.persona, marker_found=ctx.marker,
-        target_file=ctx.file_path, required_owners=owners,
+        target_file=ctx.file_path,
+        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        required_owners=owners, **_scope_fields(ctx),
     )
 
 
@@ -389,7 +582,7 @@ def _resolve_with_owners(ctx: _Ctx, owners: list[str], rule_reason: str | None)
         return _decide_open_access(ctx, owners, rule_reason)
     if ctx.persona in {o.lower() for o in owners}:
         return _decide_owner_match(ctx, owners)
-    bypass = _find_bypass(ctx.messages)
+    bypass = _find_bypass(ctx.messages, owners)
     if bypass:
         return _decide_bypass(ctx, owners, bypass)
     return _decide_block(ctx, owners)
@@ -404,7 +597,7 @@ def _resolve_ownership_outcome(ctx: _Ctx) -> Decision:
         return Decision(
             allow=True, reason="no-ownership-rule",
             current_persona=ctx.persona, marker_found=ctx.marker,
-            target_file=ctx.file_path,
+            target_file=ctx.file_path, **_scope_fields(ctx),
         )
     return _resolve_with_owners(ctx, owners, rule_reason)
 
@@ -419,16 +612,19 @@ def evaluate(
     cwd: str = "",
     tool_input: dict | None = None,
     messages: list[str] | None = None,
+    is_sidechain: bool | None = None,
 ) -> Decision:
     """Decide whether a Write/Edit/MultiEdit/NotebookEdit may proceed.
 
     ``messages`` (PR-6 hook consolidation): pre-parsed assistant messages;
     when None the transcript is read from ``transcript_path``.
+    ``is_sidechain`` (P0.2): the active scope, when the caller computed it
+    while parsing; None self-detects (only possible without ``messages``).
     """
     ctx = _Ctx(
         tool_name=tool_name, transcript_path=transcript_path,
         session_id=session_id, cwd=cwd, tool_input=tool_input or {},
-        preloaded_messages=messages,
+        preloaded_messages=messages, is_sidechain=is_sidechain,
     )
     for early_check in (_check_tool_gated, _check_feature_flag):
         decision = early_check(ctx)
@@ -464,7 +660,7 @@ def record_telemetry(
     if safe is None:
         return
     entry = {
-        "ts": datetime.now(timezone.utc).isoformat(),
+        "ts": datetime.now(UTC).isoformat(),
         "session_id": safe,
         "tool": tool,
         "cwd": cwd,

package/core/workflow/transcript_scope.py

@@ -0,0 +1,74 @@
+"""Scope-aware transcript reading — the sidechain guard (specialist P0.2).
+
+The specialist gate's 20-message window was counted over EVERY assistant
+record in the JSONL. Two scope leaks follow:
+
+- where a harness interleaves subagent (sidechain) records into the same
+  transcript, a burst of subagent activity evicts the routing marker and
+  reopens the fail-open the persisted-persona fix exists to close;
+- the persisted persona itself must never cross scopes — a dispatched
+  specialist evaluated under the PARENT's persisted persona would be
+  blocked from the very files it was dispatched to write.
+
+This module splits a transcript into main-scope and sidechain-scope
+assistant messages and reports which scope is ACTIVE (the scope of the
+most recent assistant record — at PreToolUse time, the agent whose tool
+call is being judged). Parsing mirrors
+``flow_enforcer._load_last_assistant_messages`` exactly; records without
+an ``isSidechain`` field are main-scope, so a transcript that predates
+the field behaves as before.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from core.workflow.flow_enforcer import _extract_text
+
+
+@dataclass
+class ScopeSplit:
+    """Assistant messages of a transcript, separated by scope."""
+
+    main: list[str] = field(default_factory=list)
+    sidechain: list[str] = field(default_factory=list)
+    active_sidechain: bool = False
+
+
+def split_by_scope(raw_text: str) -> ScopeSplit:
+    """Split raw JSONL transcript text into main/sidechain scopes."""
+    split = ScopeSplit()
+    for line in raw_text.splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        role = record.get("role") or record.get("message", {}).get("role")
+        if role != "assistant":
+            continue
+        content = record.get("content")
+        if content is None:
+            content = record.get("message", {}).get("content")
+        text = _extract_text(content)
+        if not text:
+            continue
+        side = bool(record.get("isSidechain", False))
+        (split.sidechain if side else split.main).append(text)
+        split.active_sidechain = side
+    return split
+
+
+def split_from_path(transcript_path: str) -> ScopeSplit:
+    """Read and split a transcript file; any failure is an empty split."""
+    path = Path(transcript_path) if transcript_path else None
+    if path is None or not path.exists():
+        return ScopeSplit()
+    try:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ScopeSplit()
+    return split_by_scope(raw)

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "4.14.3",
+    "version": "4.15.0",
     "marketplace": "arkaos"
   },
   "structural": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.14.3",
+  "version": "4.15.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.14.3"
+version = "4.15.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}