@arbiterforge/ca-pi 0.6.3 → 0.10.0

package/plugins/ca-pi/hooks/_arbiterstatelib.py

@@ -27,7 +27,9 @@
 #   count_matches_text(text, pattern) -> int          same count, given already-read text (performance-003)
 #   arbiter_state(root, count_in_flight=None, read_board=None, frontmatter_enabled=None,
 #                 ctx_text=None, ot_text=None, oq_text=None) -> dict|None
-#   dev_active(root) -> bool                        True when the /dev marker is present
+#   current_mode(session_id, root=None, payload=None) -> str   one of _modelib.MODES
+#                                                    (#437, mode-plane-deterministic-flip; replaces
+#                                                    the retired dev_active(root) presence check)
 #
 # performance-003 (#194): SessionStart's main() already reads CONTEXT.md,
 # open-tasks.md, and open-questions.md before the display-only governance line
@@ -42,6 +44,15 @@
 import os
 import re
 
+# #437 (mode-plane-deterministic-flip, T-51): the mode plane replaces the old
+# presence-only 'dev-active' marker this module used to read. Imported
+# unguarded (like every other sibling import in this file) — statusline.py,
+# this module's only external caller, already wraps `import _arbiterstatelib`
+# in its own try/except, so a failure here degrades the whole module import,
+# exactly like a failure to import `os` would. No circularity risk: _modelib
+# imports _activationlib and _hooklib, neither of which imports this module.
+from _modelib import current_mode as _modelib_current_mode
+
 # mtime-keyed memo: statusline.py is a short-lived subprocess, but a single render
 # can resolve arbiter_state more than once (safe() probes), and the StopHook fires
 # the whole script on every tool-call completion. Caching on max(input mtime) makes
@@ -155,6 +166,22 @@ def arbiter_state(root, count_in_flight=None, read_board=None, frontmatter_enabl
     return result
 
 
+# AC-40: MODE: <name> enter|exit and legacy DEV: enter|exit rows are ledger
+# bookkeeping (the #437 mode-plane audit trail), not overrides — they must not
+# inflate the statusline's "over:" counter. Mode transitions are about to
+# become routine traffic in overrides.log, so an uncorrected counter would
+# turn from noisy into actively WRONG. Mirrors _metricslib._MODE_TRANSITION_RE's
+# exact matched fragment (kept as an independent literal, not an import: this
+# module has no other reason to depend on _metricslib, and one small regex
+# fragment is cheaper to duplicate than to add a cross-module coupling for).
+_MODE_TRANSITION_FRAGMENT = (
+    r"\|\s*(?:MODE:\s*\S+\s+(?:enter|exit)|DEV:\s*(?:enter|exit))\s*(?:\||$)"
+)
+_OVERRIDE_LINE_RE = (
+    r"^(?!\s*#)(?!\s*$)(?!.*" + _MODE_TRANSITION_FRAGMENT + r").+"
+)
+
+
 def _arbiter_state_uncached(cad, count_in_flight=None, read_board=None, frontmatter_enabled=None,
                              ctx_text=None, ot_text=None, oq_text=None):
     ctx_path = os.path.join(cad, "CONTEXT.md")
@@ -164,7 +191,7 @@ def _arbiter_state_uncached(cad, count_in_flight=None, read_board=None, frontmat
     # open-questions.md text when supplied, instead of a second disk read. `None`
     # (the default) preserves the exact original read-from-disk behavior.
     fm = frontmatter_text(ctx_text) if ctx_text is not None else frontmatter(ctx_path)
-    total_over = count_matches(os.path.join(cad, "overrides.log"), r"^(?!\s*#)(?!\s*$).+")
+    total_over = count_matches(os.path.join(cad, "overrides.log"), _OVERRIDE_LINE_RE)
     # last-checkpoint holds the override COUNT at the last /ca:checkpoint. A value
     # outside [0, total] is not a valid count (e.g. a timestamp from a stale writer)
     # -> fail safe to 0 so overrides are surfaced, never silently hidden.
@@ -196,13 +223,34 @@ def _arbiter_state_uncached(cad, count_in_flight=None, read_board=None, frontmat
     }
 
 
-def dev_active(root):
-    """True when /dev developer-override mode is on — signalled by a transient marker
-    the orchestrator drops on /dev and clears on /arbiter (a local UI flag, not a log).
+def current_mode(session_id, root=None, payload=None):
+    """The session's current orchestration posture — one of `_modelib.MODES`
+    ('arbiter' | 'dangerous' | 'ops') — read off the mode plane (#437,
+    mode-plane-deterministic-flip). Replaces the retired `dev_active(root)`
+    presence check: the 'dev-active' marker is not dual-written (Decided
+    parameters: "Single source of truth" — every reader migrates to the mode
+    file), so a reader that kept checking for that marker would silently and
+    permanently report inactive the moment nothing writes it anymore.
+
+    Deliberately resolves through `_activationlib.marker_root` — via
+    `_modelib.current_mode`'s own `root=None` contract — rather than this
+    module's OTHER readers' pre-resolved `root` (arbiter_state's caller
+    passes a project root suitable for reading CONTEXT.md/overrides.log
+    in-place). `.codearbiter/.markers/` is gitignored, so a linked
+    worktree's own checkout never has a fresh copy of it, and every other
+    `.markers/` writer (security-pass.py, migration-pass.py, the mode flip
+    itself) already resolves through marker_root — the mode marker must
+    agree with them or a linked-worktree session silently reads the wrong
+    file (#604, AC-5).
+
+    Pass `payload` (the raw hook/status-line JSON) for production-correct
+    resolution; `root` is a test-only escape hatch that mirrors
+    `_modelib.current_mode`'s own contract exactly — an explicit root
+    bypasses payload/host resolution entirely and is read verbatim.
 
-    Presence-only by design, unaffected by #271 C-5's session-scoped clearing:
-    the marker still means "dev mode is on for SOMEONE" regardless of which
-    session owns it. Session-scoping only changes WHEN SessionStart is willing
-    to clear a live marker (never a different, possibly still-live session's
-    own marker) — it does not change what "present" means to this reader."""
-    return os.path.exists(os.path.join(root, ".codearbiter", ".markers", "dev-active"))
+    Never raises: an absent/unreadable/malformed marker, or an unrecognized
+    per-session value, degrades to 'arbiter' — the diagnostic half of
+    `_modelib.current_mode`'s return is a maintainer/audit concern, not this
+    render-facing reader's; callers here need only the mode, never why."""
+    mode, _diag = _modelib_current_mode(session_id, root=root, payload=payload)
+    return mode

package/plugins/ca-pi/hooks/_bashguardlib.py

@@ -81,7 +81,8 @@ import subprocess
 import sys
 
 from _hooklib import (
-    AUDIT_LOG_BASENAMES, AUDIT_LOG_NAMES, CRYPTO_RE, DECISION_LOG_BASENAME, DECISIONS_DIR_RE,
+    ADR_LIFECYCLE_LOG_BASENAME, AUDIT_LOG_BASENAMES, AUDIT_LOG_FLAT_BASENAMES,
+    AUDIT_LOG_NAMES, CRYPTO_RE, DECISION_AUDIT_LOG_NAMES, DECISION_LOG_BASENAME, DECISIONS_DIR_RE,
     GATE_MARKER_NAMES, MARKER_FRESHNESS_MINUTES, SECRET_RE, SECURITY_DIFF_GIT_ARGS, block,
     content_digest, is_migration_path, line_digest, marker_fresh, sensitive_scan_added_lines,
 )
@@ -317,7 +318,7 @@ PROTECTED_DEST_RE = re.compile(r"(?:\S+:|:)?(?:refs/heads/)?(?:main|master)")
 # (the /sprint decision record). The bare-name alternation is centralized in
 # _hooklib.AUDIT_LOG_NAMES so the Write/Edit and shell flanks never drift.
 LOG_NAMES = AUDIT_LOG_NAMES
-LOG_TRUNC_RE = re.compile(r"(?<!>)>(?!>)\|?\s*\S*" + LOG_NAMES)
+LOG_TRUNC_RE = re.compile(r"(?<!>)>(?!>)\|?\s*\S*" + LOG_NAMES, re.I)
 LOG_DESTROY_RE = re.compile(
     r"\b(rm|del|mv|cp|copy|dd|tee|sed|truncate|sponge"
     # #528: `New-Item -Force` TRUNCATES an existing file (verified in PowerShell:
@@ -345,20 +346,20 @@ DECISIONS = DECISIONS_DIR_RE + r"\b"
 # #528: the one path under decisions/ that H-11 must NOT claim — see
 # _check_h11_decisions. Matched on the raw command, so both separators.
 #
-# DELIBERATELY CASE-SENSITIVE. H-05, which takes over for this file, is itself
-# case-sensitive on both flanks: _check_h05_audit_log pre-filters with a plain
-# `in` test over AUDIT_LOG_BASENAMES, and LOG_TRUNC_RE carries no re.I. An re.I
-# here therefore stripped `Decision-Log.md` out of H-11's view and handed it to a
-# guard that could not see it — and on Windows/NTFS and default macOS/APFS that
-# spelling resolves to the real file, so `rm …/Decision-Log.md` destroyed the
-# append-only log with nothing firing at all. The two flanks must agree on case.
-#
 # The right edge is anchored so this path cannot SHIELD a sibling token: without
 # it, `touch …/decision-log.md.evil.md` was stripped to a harmless remainder and
 # H-11 stopped seeing a decisions/ write at all.
 DECISION_LOG_SHELL_RE = re.compile(
     DECISIONS_DIR_RE + r"[\\/]+" + re.escape(DECISION_LOG_BASENAME) + r"""(?=$|[\s>|;&"'])""",
 )
+# The lifecycle ledger is new and explicitly enrolled case-insensitively on
+# supported case-folding filesystems. Keep this separate from decision-log.md:
+# historical mixed-case decision-log spellings remain H-11, as #528 requires.
+ADR_LIFECYCLE_LOG_SHELL_RE = re.compile(
+    DECISIONS_DIR_RE + r"[\\/]+" + re.escape(ADR_LIFECYCLE_LOG_BASENAME) +
+    r"""(?=$|[\s>|;&"'])""",
+    re.I,
+)
 # `>>?\|?` covers `>`, `>>`, and the `>|` force-clobber form into decisions/.
 DECISIONS_REDIRECT_RE = re.compile(r">>?\|?\s*\S*" + DECISIONS, re.I)
 DECISIONS_WRITE_RE = re.compile(
@@ -804,6 +805,12 @@ def git_cwd(cmd, root):
     return acc
 
 
+_CODEX_EXPLICIT_WORKDIR_TOOLS = frozenset({
+    "shell_command", "exec_command", "unified_exec",
+    "functions.exec",
+})
+
+
 def _effective_exec_root(payload, root):
     """The git root that a `-C`-less git command in THIS Bash call actually
     runs against — the command's effective cwd — rather than always the
@@ -841,7 +848,13 @@ def _effective_exec_root(payload, root):
     unchanged — the overwhelmingly common (non-worktree) case sees zero
     behavioral difference. It returns the climbed root only when it names a
     genuinely DIFFERENT filesystem location."""
-    exec_root = _gitlib.project_root(payload if isinstance(payload, dict) else {})
+    data = payload if isinstance(payload, dict) else {}
+    tool_input = data.get("tool_input")
+    workdir = tool_input.get("workdir") if isinstance(tool_input, dict) else None
+    if (data.get("tool_name") in _CODEX_EXPLICIT_WORKDIR_TOOLS
+            and isinstance(workdir, str) and os.path.isdir(workdir)):
+        data = {"cwd": workdir}
+    exec_root = _gitlib.project_root(data)
     if os.path.normpath(os.path.abspath(exec_root)) == os.path.normpath(os.path.abspath(root)):
         return root
     return exec_root
@@ -1329,7 +1342,11 @@ def _check_h05_audit_log(cmd):
     # (`python3 -c "open('.codearbiter/overrides.log','w')..."`) — the
     # verb-list and redirect legs above never look for an interpreter token
     # at all, so this shape walked past both.
-    if any(n in cmd for n in AUDIT_LOG_BASENAMES) and (
+    folded = cmd.casefold()
+    legacy_names = AUDIT_LOG_FLAT_BASENAMES + (DECISION_LOG_BASENAME,)
+    enrolled_name = (any(n in cmd for n in legacy_names) or
+                     ADR_LIFECYCLE_LOG_BASENAME.casefold() in folded)
+    if enrolled_name and (
             LOG_TRUNC_RE.search(cmd) or LOG_DESTROY_RE.search(cmd)
             or LOG_GIT_RESTORE_RE.search(cmd) or LOG_INTERP_RE.search(cmd)):
         block("H-05", "The .codearbiter audit logs (overrides.log, triage.log, sprint-log.md, "
@@ -1356,6 +1373,7 @@ def _check_h11_decisions(cmd):
     # append to decisions/decision-log.md stays the #528 carve-out's to
     # police (via H-05's own LOG_INTERP_RE), not a false H-11 block.
     cmd = DECISION_LOG_SHELL_RE.sub(" ", cmd)
+    cmd = ADR_LIFECYCLE_LOG_SHELL_RE.sub(" ", cmd)
     if (DECISIONS_REDIRECT_RE.search(cmd) or DECISIONS_WRITE_RE.search(cmd)
             or DECISIONS_INTERP_RE.search(cmd)):
         block("H-11", "ADR files under .codearbiter/decisions/ are authored only via "

package/plugins/ca-pi/hooks/_gitexec.py

@@ -20,6 +20,29 @@ import os
 GIT_ENV = "CODEARBITER_GIT_EXECUTABLE"
 PYTHON_ENV = "CODEARBITER_PYTHON_EXECUTABLE"
 
+_ROOT_OVERRIDE_ENV = frozenset({
+    # `git rev-parse --local-env-vars` repository/object selectors.
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_OBJECT_DIRECTORY",
+    "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE",
+    "GIT_GRAFT_FILE", "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS",
+    "GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_SHALLOW_FILE",
+    "GIT_COMMON_DIR",
+    # Discovery indirection can also override an exact root-bound probe.
+    "GIT_CEILING_DIRECTORIES", "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+})
+
+
+def root_bound_git_env():
+    """Environment for selected Git to describe an explicit checkout root.
+
+    Protected configuration such as safe.directory remains authoritative; only
+    repository, object, and discovery selectors that override `-C` are removed.
+    """
+    env = os.environ.copy()
+    for name in _ROOT_OVERRIDE_ENV:
+        env.pop(name, None)
+    return env
+
 
 def _trusted_environment_path(name):
     value = os.environ.get(name)

package/plugins/ca-pi/hooks/_githooks.py

@@ -62,8 +62,8 @@
 #   * Idempotent: an up-to-date ours-hook is left untouched (no churn); a stale
 #     ours-hook is refreshed.
 #   * performance-002 (#194): re-resolving hooks_dir() every SessionStart costs
-#     up to two blocking `git` subprocess spawns (config --get core.hooksPath,
-#     rev-parse --git-path hooks) even on the common steady-state call where
+#     one blocking `git` subprocess spawn (`rev-parse --git-path hooks`) even
+#     on the common steady-state call where
 #     nothing changed. install() first checks a cheap on-disk cache (a single
 #     small file read, no git spawn) recording the hooks_dir a prior successful
 #     resolution used; if BOTH phase shims at that cached location already
@@ -114,7 +114,8 @@ import sys
 
 import _hooklib
 from _durabilitylib import is_ephemeral_path
-from _gitexec import git_executable, trusted_git_executable, trusted_python_executable
+from _gitexec import (git_executable, root_bound_git_env,
+                      trusted_git_executable, trusted_python_executable)
 
 SENTINEL = (
     "# codeArbiter-managed git hook (#161) — this SHIM is refreshed by any live "
@@ -140,6 +141,7 @@ def _git(args, cwd):
         return subprocess.run(
             [git_executable()] + args, cwd=cwd, capture_output=True, text=True,
             encoding="utf-8", errors="replace", timeout=5,
+            env=root_bound_git_env(),
         )
     except Exception:  # noqa: BLE001
         return None
@@ -148,20 +150,15 @@ def _git(args, cwd):
 def hooks_dir(root):
     """The directory git actually reads hooks from for `root`, or None.
 
-    Honors core.hooksPath (when set, git IGNORES .git/hooks entirely), and
-    resolves the real git dir via `rev-parse --git-path hooks` so linked
-    worktrees and submodules land in the right place. Falls back to
-    <root>/.git/hooks only if git can't answer."""
-    cfg = _git(["config", "--get", "core.hooksPath"], root)
-    if cfg is not None and cfg.returncode == 0 and cfg.stdout.strip():
-        hp = cfg.stdout.strip()
-        return hp if os.path.isabs(hp) else os.path.join(root, hp)
+    The selected Git binary owns core.hooksPath parsing, including its path
+    grammar (`~`, `%(prefix)`, absolute, and relative forms), and linked
+    worktree/submodule semantics. Python must not reinterpret the raw config
+    value differently from the binary that will execute the hooks."""
     gp = _git(["rev-parse", "--git-path", "hooks"], root)
     if gp is not None and gp.returncode == 0 and gp.stdout.strip():
         hp = gp.stdout.strip()
         return hp if os.path.isabs(hp) else os.path.join(root, hp)
-    default = os.path.join(root, ".git", "hooks")
-    return default if os.path.isdir(os.path.join(root, ".git")) else None
+    return None
 
 
 def _enforcer_path():
@@ -213,13 +210,15 @@ def _git_common_dir(root):
     repo must resolve to the SAME common dir here, or the #265 drop-in dir
     would fork per-worktree and defeat the entire cross-host purpose (a shim
     installed from worktree A would never see an entry written from
-    worktree B). The main-repo case (`.git` is a directory) needs no spawn at
-    all: it IS its own common dir. Returns None if nothing resolves — callers
-    must treat that as "can't place the drop-in dir right now" and never
-    invent a per-worktree fallback."""
+    worktree B). The returned path is canonical so equivalent symlink, macOS
+    `/var`, and Windows short-name spellings produce the same registry path in
+    every managed shim. The main-repo case (`.git` is a directory) needs no
+    spawn at all: it IS its own common dir. Returns None if nothing resolves —
+    callers must treat that as "can't place the drop-in dir right now" and
+    never invent a per-worktree fallback."""
     git_path = os.path.join(root, ".git")
     if os.path.isdir(git_path):
-        return os.path.abspath(git_path)
+        return os.path.realpath(git_path)
     if os.path.isfile(git_path):
         text = _read(git_path)
         if text:
@@ -234,12 +233,13 @@ def _git_common_dir(root):
                         cd = cd_text.strip()
                         common = (cd if os.path.isabs(cd)
                                   else os.path.normpath(os.path.join(wt_gitdir, cd)))
-                        return os.path.abspath(common)
+                        return os.path.realpath(common)
                     break
     r = _git(["rev-parse", "--git-common-dir"], root)
     if r is not None and r.returncode == 0 and r.stdout.strip():
         out = r.stdout.strip()
-        return os.path.abspath(out if os.path.isabs(out) else os.path.join(root, out))
+        return os.path.realpath(
+            out if os.path.isabs(out) else os.path.join(root, out))
     return None
 
 
@@ -370,8 +370,9 @@ def _touch_seen_marker(dropin_dir, plugin, enforcer):
 # SENTINEL) session bakes in. `/ca:doctor` runs the SAME text as a real
 # subprocess instead of a parallel port, so the two can never drift.
 #
-# Algorithm: a plugin's registered entry is "stale" — printed to stdout, one
-# per line — iff (a) at least one OTHER registered entry in the same
+# Algorithm: first discard entries whose registered enforcer is not a live
+# regular file. A remaining plugin's registered entry is "stale" — printed to
+# stdout, one per line — iff (a) at least one OTHER live registered entry in the same
 # drop-in dir has recorded a `.seen` heartbeat, AND (b) this plugin's own
 # heartbeat is either absent or strictly older than the freshest one seen.
 # When NOBODY has ever recorded a heartbeat (a repo that predates #556, or
@@ -401,7 +402,7 @@ _FRESHNESS_PY = (
     "    if legacy.fullmatch(plugin):\n"
     "        continue\n"
     "    path_val = _rd(os.path.join(d, n))\n"
-    "    if path_val is None:\n"
+    "    if not path_val or not os.path.isfile(path_val):\n"
     "        continue\n"
     "    seen_file = os.path.join(d, plugin + '.seen')\n"
     # `.seen` only counts as a confirmation of what's registered RIGHT NOW when
@@ -455,6 +456,32 @@ def stale_registered_plugins(dropin_dir):
     return [ln for ln in r.stdout.splitlines() if ln.strip()]
 
 
+def live_registered_plugins(dropin_dir):
+    """Stable plugin names whose current `.path` target is a regular file.
+
+    This deliberately uses the same liveness boundary as the generated shim
+    (`[ -f "$E" ]`) and the freshness probe above. It is diagnostic support
+    for doctor, not a second freshness implementation."""
+    if not dropin_dir or not os.path.isdir(dropin_dir):
+        return []
+    legacy = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$")
+    live = []
+    try:
+        names = sorted(os.listdir(dropin_dir))
+    except OSError:
+        return []
+    for name in names:
+        if not name.endswith(".path"):
+            continue
+        plugin = name[:-len(".path")]
+        if legacy.fullmatch(plugin):
+            continue
+        path_val = _read(os.path.join(dropin_dir, name))
+        if path_val and os.path.isfile(path_val.strip()):
+            live.append(plugin)
+    return live
+
+
 _TRUSTED_IDENTITY_FILE = "trusted-executables.identity"
 
 

package/plugins/ca-pi/hooks/_hooklib.py

@@ -186,7 +186,10 @@ from _protectedlib import (  # noqa: F401
     DECISIONS_DIR_RE,
     DECISIONS_PATH_RE,
     DECISION_LOG_BASENAME,
+    ADR_LIFECYCLE_LOG_BASENAME,
+    DECISION_AUDIT_LOG_NAMES,
     DECISION_LOG_RE,
+    ADR_LIFECYCLE_LOG_RE,
     GATE_MARKER_NAMES,
     MARKERS_RE,
     classify_protected,
@@ -532,30 +535,149 @@ def warn(msg):
 # active long-running flow's marker has sat around past `window_minutes` with
 # no matching activity in its expected audit log.
 #
-# Only /dev and /sprint have a persistent "in-progress" marker today
-# (.codearbiter/.markers/dev-active and .codearbiter/sprint-active — the same
-# state _arbiterstatelib.dev_active()/arbiter_state() already read). /override
-# is a single synchronous action (announce-then-log in one turn, per
-# override.md) with no analogous "still in progress" marker anywhere in the
-# framework, so per CONFIRM-09's own "do not invent new state" constraint it
-# is not tracked here — there is no existing signal to detect it from.
+# Only the mode plane and /sprint have a persistent "in-progress" marker
+# today (.codearbiter/.markers/mode.d/ and .codearbiter/sprint-active — the same
+# state _arbiterstatelib.current_mode()/arbiter_state() already read; the
+# mode marker is #437's direct successor to the retired dev-active marker
+# this comment originally described). /override is a single synchronous
+# action (announce-then-log in one turn, per override.md) with no analogous
+# "still in progress" marker anywhere in the framework, so per CONFIRM-09's
+# own "do not invent new state" constraint it is not tracked here — there is
+# no existing signal to detect it from.
 #
-# #271 C-5: this staleness WARN is presence + age based (marker mtime vs. an
-# audit-log write), which is unaffected by session-start.py's newer
-# session-scoped CLEARING decision for the SAME dev-active marker — the two
-# consumers ask different questions ("has this sat around too long with no
-# matching log activity?" vs. "am I sure enough this belongs to nobody live
-# right now that I should force-close it?") and neither needs to agree with
-# the other's answer. A dev marker owned by a still-live different session
-# can legitimately trip THIS warning (it really has been open a while) even
-# though session-start.py correctly declines to clobber it.
+# #271 C-5 (pre-#437): this staleness WARN is presence + age based (marker
+# mtime vs. an audit-log write), which was unaffected by session-start.py's
+# then-newer session-scoped CLEARING decision for the SAME dev-active
+# marker — the two consumers ask different questions ("has this sat around
+# too long with no matching log activity?" vs. "am I sure enough this
+# belongs to nobody live right now that I should force-close it?") and
+# neither needs to agree with the other's answer. The same reasoning now
+# applies to the mode marker: a non-arbiter entry owned by a still-live
+# different session can legitimately trip THIS warning even though
+# SessionStart correctly declines to clobber a live session's own entry.
 _STALE_FLOWS = (
     # (flow name, marker path parts, expected-log path parts)
-    ("dev", (".markers", "dev-active"), ("overrides.log",)),
+    #
+    # #437 (mode-plane-deterministic-flip): the 'dev'/'dev-active' entry this
+    # tuple used to carry is RENAMED, not removed — the mode marker is the
+    # direct successor of dev-active (Decided parameters: dev-active is not
+    # dual-written; every reader migrates to the mode file). Missing this
+    # rename is the one hazard this whole registry exists to avoid: it is a
+    # WARN, not a gate, so a stale matcher fails PERMANENTLY SILENT with an
+    # otherwise green suite — nothing else in the repo would ever notice.
+    #
+    # #681 moved the target again, from that one file to the per-session entry
+    # DIRECTORY, for the same reason: pointed at `mode`, this row would have
+    # kept matching a file nothing writes any more and gone silent exactly as
+    # the note above warns. This row's marker is therefore a directory, and
+    # `_mode_plane_active_since` — not `os.path.isfile` + `getmtime` — answers
+    # both "is anything active" and "since when" for it.
+    ("mode", (".markers", "mode.d"), ("overrides.log",)),
     ("sprint", ("sprint-active",), ("sprint-log.md",)),
 )
 
 
+def _mode_marker_has_non_arbiter_entry(marker):
+    """AC-36: True iff the mode marker JSON names at least one session in a
+    non-'arbiter' posture. Presence alone is NOT "active" for this flow the
+    way it was for the old boolean dev-active marker — the mode file is a
+    persistent `{session_id: mode}` map (#437's State: decided parameter)
+    that legitimately keeps existing, with plenty of purely-'arbiter'
+    entries, long after every non-arbiter session has flipped back or
+    ended. Warning on mere file presence would trip AC-36's negative arm
+    (never warn for arbiter) permanently, for every repo that has ever used
+    the mode plane at all — exactly the "warns on everything" matcher the
+    negative-arm assertion exists to catch.
+
+    Deliberately duplicates the literal 'arbiter' value here rather than
+    importing `_modelib.MODES[0]`: `_modelib` imports `write_text_atomic`
+    FROM this module, so importing back the other way would be circular.
+    Never raises: an absent/corrupt/malformed marker answers False — the
+    same fail-toward-silent convention `staleness_warning`'s own try/except
+    already applies to every other stat/read in this loop."""
+    try:
+        with open(marker, encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception:  # noqa: BLE001 — unreadable/corrupt -> nothing provably active
+        return False
+    if not isinstance(data, dict):
+        return False
+    return any(v != "arbiter" for v in data.values())
+
+
+# Worst-case bound on the entry scan below: the all-arbiter case, where the
+# newest-first early exit never fires and every entry would otherwise be read
+# on every prompt. 64 is far above any plausible count of sessions live at once
+# and far below the unbounded total a long-lived repo accumulates. Capping
+# costs only a WARN — a flow older than the 64 most recently touched sessions
+# goes unreported, which this registry's own contract already tolerates
+# ("a missed warn is acceptable; a crash is not", prune-transcript.py).
+_MODE_ENTRY_SCAN_MAX = 64
+
+
+def _mode_plane_active_since(cad):
+    """(#681) Newest mtime among per-session mode entries in a NON-arbiter
+    posture, or None when the mode plane is not active.
+
+    Replaces the single marker file's stat for this flow. The plane is now a
+    directory of one-file-per-session entries (`_modelib.mode_entry_dir`),
+    which changes both halves of the question this registry asks:
+
+    - *Active* is still "some session is non-arbiter", but it is now answered
+      per entry rather than over one map's values.
+    - *Since when* gets strictly more accurate. The shared map's mtime was
+      bumped by ANY session's write, so one arbiter session flipping reset the
+      staleness clock for a different session sitting in `dangerous`. An
+      entry's own mtime is that session's own last flip.
+
+    Bounded: entries are examined newest-first and the scan stops at the first
+    non-arbiter one (which is by definition the newest), with a hard
+    `_MODE_ENTRY_SCAN_MAX` ceiling for the all-arbiter case.
+
+    Falls back to the pre-split map so a repo upgraded mid-flow keeps warning.
+    Never raises: this whole registry is a WARN, and a matcher that stopped
+    matching would fail permanently SILENT with a green suite — the exact
+    hazard `_STALE_FLOWS`' own comment names.
+
+    Duplicates the literal 'arbiter' for the same reason
+    `_mode_marker_has_non_arbiter_entry` does: `_modelib` imports
+    `write_text_atomic` from this module, so importing back would be circular.
+    """
+    entries = []
+    entry_dir = os.path.join(cad, ".markers", "mode.d")
+    try:
+        with os.scandir(entry_dir) as it:
+            for item in it:
+                try:
+                    entries.append((item.stat().st_mtime, item.path))
+                except OSError:
+                    continue
+    except OSError:  # no directory yet -> no per-session entries to weigh
+        entries = []
+    # NEWEST FIRST, and stop at the first non-arbiter entry: that entry IS the
+    # newest non-arbiter mtime, so the ordering turns "read every entry" into
+    # "usually read one". This runs on the prompt seam — `prune-transcript.py`
+    # calls `staleness_warning` on every UserPromptSubmit — and entries are
+    # never reaped, so an unordered full scan would make every prompt pay for
+    # every session the repo has ever had.
+    entries.sort(reverse=True)
+    for mtime, path in entries[:_MODE_ENTRY_SCAN_MAX]:
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+        except Exception:  # noqa: BLE001 — unreadable entry proves nothing active
+            continue
+        if isinstance(data, dict) and data.get("mode") not in (None, "arbiter"):
+            return mtime
+    legacy = os.path.join(cad, ".markers", "mode")
+    if os.path.isfile(legacy) and _mode_marker_has_non_arbiter_entry(legacy):
+        try:
+            return os.path.getmtime(legacy)
+        except OSError:
+            return None
+    return None
+
+
 def staleness_warning(root, now=None, window_minutes=30):
     """(CONFIRM-09) One WARN message per active flow (see _STALE_FLOWS) whose
     marker has existed for at least `window_minutes` with no audit-log
@@ -573,9 +695,15 @@ def staleness_warning(root, now=None, window_minutes=30):
     for name, marker_parts, log_parts in _STALE_FLOWS:
         try:
             marker = os.path.join(cad, *marker_parts)
-            if not os.path.isfile(marker):
-                continue
-            marker_mtime = os.path.getmtime(marker)
+            if name == "mode":
+                # AC-36: never warn for arbiter — presence alone isn't "active".
+                marker_mtime = _mode_plane_active_since(cad)
+                if marker_mtime is None:
+                    continue
+            else:
+                if not os.path.isfile(marker):
+                    continue
+                marker_mtime = os.path.getmtime(marker)
             if now - marker_mtime < window_minutes * 60:
                 continue  # flow started too recently to call it stale yet
             log_path = os.path.join(cad, *log_parts)

package/plugins/ca-pi/hooks/_host.py

@@ -10,6 +10,11 @@ import hostapi  # noqa: E402
 
 class PiHost(hostapi.Host):
     name = "pi"
+    adapter_name = "@arbiterforge/ca-pi"
+    adapter_version = "0.10.0"
+    update_target = "ca-pi"
+    update_tag_prefix = "ca-pi-v"
+    update_command = "pi update npm:@arbiterforge/ca-pi"
     command_noun = "command"
     has_statusline = False
     has_read_tool = True
@@ -40,7 +45,10 @@ class PiHost(hostapi.Host):
         return hostapi.git_toplevel() or os.getcwd()
 
     def plugin_root(self):
-        return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        return hostapi.resolve_plugin_root(
+            __file__, adapter_name=self.adapter_name, adapter_version=self.adapter_version,
+            manifest_relpath=self.manifest_relpath(), anchor_relpath="hooks/_host.py",
+        )
 
     def manifest_relpath(self):
         return "package.json"

package/plugins/ca-pi/hooks/_metricslib.py

@@ -247,6 +247,17 @@ def commit_timeline(root):
 import re as _re
 _OVERRIDE_TS_RE = _re.compile(r"^\[([^\]]+)\]")
 
+# Mode-transition rows are ledger bookkeeping, not overrides, and must be
+# excluded from override_rate (AC-40). Two forms appear in overrides.log:
+#   - new:    "MODE: <name> enter" / "MODE: <name> exit"
+#   - legacy: "DEV: enter" / "DEV: exit"
+# Both are matched as a pipe-delimited field (bounded by "|" or end-of-line),
+# the same shape as _SMALL_LANE_RE's field match below, so a REASON/NOTE
+# sentence that merely mentions "mode" or "dev" cannot false-positive.
+_MODE_TRANSITION_RE = _re.compile(
+    r"\|\s*(?:MODE:\s*\S+\s+(?:enter|exit)|DEV:\s*(?:enter|exit))\s*(?:\||$)"
+)
+
 
 def override_rate(lines_or_text, windows):
     """Compute the override rate for the current and prior windows.
@@ -274,6 +285,10 @@ def override_rate(lines_or_text, windows):
         - Lines that start with "#" (after stripping leading whitespace) are
           comment lines and are excluded.
         - Blank and whitespace-only lines are excluded.
+        - Mode-transition rows are excluded: the new form
+          "MODE: <name> enter|exit" and the legacy form "DEV: enter|exit"
+          (AC-40). These are ledger bookkeeping, not overrides — genuine
+          "GATE:" / "SECURITY-OVERRIDE" / other override rows still count.
         - Entries whose parsed timestamp maps to BEFORE_HISTORY are excluded
           from all window counts.
     """
@@ -300,6 +315,11 @@ def override_rate(lines_or_text, windows):
         if not line or line.startswith("#"):
             continue
 
+        # Skip mode-transition rows (new MODE: and legacy DEV: forms) — see
+        # AC-40 and _MODE_TRANSITION_RE above.
+        if _MODE_TRANSITION_RE.search(line):
+            continue
+
         # Extract the leading timestamp token "[<ts>]".
         m = _OVERRIDE_TS_RE.match(line)
         if not m: