coding-os 0.3.2__py3-none-any.whl

core/hooks/_helpers/work_log_append.py

@@ -0,0 +1,89 @@
+"""Append a Work Log entry to a task — called from capture-work-log +
+link-commit-to-task hooks.
+
+USAGE
+    python3 work_log_append.py <task_id> <summary>
+Reads COS_PROJECT_ROOT, COS_DB_PATH, COS_AGENT_SESSION_ID from env.
+Exit 0 = appended; exit 1 = could not append (callers may log/fall back).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+# board_os lives at src/core/ — two levels up from _helpers/. Without this
+# bootstrap (every sibling helper has it) the import below fails for any
+# hook-spawned python3 and the append was a silent no-op (TASK-340).
+_CORE = Path(__file__).resolve().parents[2]
+if _CORE.is_dir() and str(_CORE) not in sys.path:
+    sys.path.insert(0, str(_CORE))
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        return 1
+    task_id, summary = argv[1], argv[2]
+
+    try:
+        from board_os.mcp_tools import cos_work_log_append
+    except ImportError:
+        return 1
+
+    from _paths import resolve_project_root
+
+    project_root = resolve_project_root()
+    try:
+        from thinking_os.database import resolve_db_path  # type: ignore
+
+        db_path = str(resolve_db_path(project_root))
+    except ImportError:
+        db_path = os.environ.get(
+            "COS_DB_PATH",
+            str(project_root / ".coding-os" / "coding-os.db"),
+        )
+    if not Path(db_path).exists():
+        return 1
+
+    # Cross-platform per-task lock (flock(1) does not exist on macOS — the
+    # old bash-side `flock -w 2` died silently there; fcntl works on both).
+    lock_dir = project_root / ".coding-os" / "locks"
+    try:
+        lock_dir.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return 1
+    with open(lock_dir / f"{task_id}.lock", "w", encoding="utf-8") as lock_handle:
+        fcntl.flock(lock_handle, fcntl.LOCK_EX)
+
+        # Route through get_connection for WAL + busy_timeout so a concurrent
+        # board write waits instead of failing on a locked DB.
+        try:
+            from thinking_os.database import get_connection  # type: ignore
+
+            conn = get_connection(db_path)
+        except Exception:
+            conn = sqlite3.connect(db_path, timeout=5.0)
+            conn.execute("PRAGMA busy_timeout = 5000")
+        try:
+            envelope = cos_work_log_append(
+                conn,
+                task_id=task_id,
+                summary=summary,
+                agent_session=os.environ.get("COS_AGENT_SESSION_ID"),
+                source="auto",
+            )
+        finally:
+            conn.close()
+    try:
+        appended = bool(json.loads(envelope).get("ok"))
+    except (TypeError, ValueError):
+        appended = False
+    return 0 if appended else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

core/hooks/_helpers/wrap_dispatch_output.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Wrap captured dispatch output in the JSON envelope Codex expects.
+
+Replaces inline `python3 - <<'PY'` heredocs in adapter dispatch shell
+scripts (Rule 8: heredoc inside `$(...)` deadlocks bash 5.x).
+
+Two output shapes:
+
+    --shape additional-context <event_name> <captured_file>
+        {"hookSpecificOutput": {"hookEventName": "<event>",
+                                "additionalContext": "<captured>"}}
+
+    --shape user-message <max_chars> <captured_file>
+        {"user_message": "<captured truncated to max_chars>"}
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+USAGE = (
+    "usage:\n"
+    "  wrap_dispatch_output.py additional-context <event_name> <captured_file>\n"
+    "  wrap_dispatch_output.py user-message <max_chars> <captured_file>\n"
+)
+
+
+def _read_text(path_str: str) -> str:
+    p = Path(path_str)
+    return p.read_text(encoding="utf-8", errors="replace") if p.exists() else ""
+
+
+def _emit_additional_context(event_name: str, captured_file: str) -> int:
+    text = _read_text(captured_file).strip()
+    json.dump(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": event_name,
+                "additionalContext": text,
+            }
+        },
+        sys.stdout,
+        ensure_ascii=False,
+    )
+    sys.stdout.write("\n")
+    return 0
+
+
+def _emit_user_message(max_chars_s: str, captured_file: str) -> int:
+    try:
+        max_chars = int(max_chars_s)
+    except ValueError:
+        print(f"max_chars must be an integer: {max_chars_s!r}", file=sys.stderr)
+        return 2
+    text = _read_text(captured_file).strip()
+    if len(text) > max_chars:
+        text = text[: max(0, max_chars - 3)] + "..."
+    out: dict[str, str] = {}
+    if text:
+        out["user_message"] = text
+    json.dump(out, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        sys.stderr.write(USAGE)
+        return 2
+    shape = argv[1]
+    if shape == "additional-context" and len(argv) == 4:
+        return _emit_additional_context(argv[2], argv[3])
+    if shape == "user-message" and len(argv) == 4:
+        return _emit_user_message(argv[2], argv[3])
+    sys.stderr.write(USAGE)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

core/hooks/advance-role.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# advance-role.sh (PostToolUse) — advance the active role along the chain.
+#
+# After a tool runs, move .role to the chain member that matches the current
+# work phase (Write/Edit → implementer, test/verify Bash → reviewer) so the
+# session banner's roles= field tracks what the agent is DOING, not a frozen
+# chain lead.
+# Only ever picks a role already IN the composed chain. Fail-open.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+INPUT="$(cos_read_stdin_bounded 2 2>/dev/null || true)"
+
+# Fast-path: this hook only advances the active role when a composed chain
+# exists (the .roles marker). No chain → nothing to advance; bail before any
+# jq spawn (fires on EVERY Write/Edit/Bash tool call). Check first because it
+# is a single stat() vs three jq process spawns.
+TARGET_DIR="${COS_PANEL_DIR:-${COS_AGENT_DIR:-${COS_STATE_DIR:-.coding-os}/${COS_AGENT:-claude}}}"
+[[ -f "${TARGET_DIR}/.roles" ]] || exit 0
+
+TOOL="$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+[[ -n "$TOOL" ]] || exit 0
+case "$TOOL" in
+  Write|Edit|MultiEdit|Bash) ;;
+  *) exit 0 ;;
+esac
+CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+FILE_PATH="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+
+# Resolve the helper through the hook symlink.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HSRC="$(cd -P "$(dirname "$_src")" && pwd)"
+HELPER="${HSRC}/_helpers/advance_role.py"
+[[ -f "$HELPER" ]] || exit 0
+
+CHOSEN=$(python3 "$HELPER" "$TOOL" "$TARGET_DIR" "$CMD" "$FILE_PATH" 2>/dev/null || true)
+if [[ -n "$CHOSEN" ]]; then
+  cos_log_hook advance-role ok "tool=${TOOL} role=${CHOSEN}" || true
+fi
+
+exit 0

core/hooks/agent-presence.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# Coding OS — agent-presence.sh
+#
+# PURPOSE
+#   Maintain a per-session presence file so the board UI can tell in
+#   real time whether an agent is:
+#     • ACTIVE   — tool call within the last 30s or user turn in flight
+#     • PRESENT  — session alive, PID still running, no recent tool
+#     • OFFLINE  — no session marker / PID dead / Stop emitted long ago
+#
+#   The hook layer is the only cross-agent signal we have for presence:
+#   Claude Code and Codex both fire shell hooks via their
+#   settings.{json,toml} contract.  Every lifecycle event routes to
+#   this one script so the state file has a single writer, which keeps
+#   the concurrency model trivial (tmp file + atomic rename).
+#
+# INVOKED BY
+#   A single registry.yaml entry maps this script to every lifecycle
+#   event Claude/Codex expose.  The script reads `hook_event_name`
+#   from the JSON payload Claude Code sends on stdin and routes to the
+#   correct action:
+#     SessionStart    → "start"
+#     UserPromptSubmit→ "prompt"
+#     PreToolUse      → "tool"
+#     PostToolUse     → "tool"
+#     Stop            → "stop"
+#     SessionEnd      → "end"   (Claude Code 2.x; optional)
+#
+# OUTPUT
+#   $COS_AGENT_DIR/sessions/<session_id>.json (one file per live session).
+#     {
+#       "agent":            "claude|codex",
+#       "session_id":       "ses-<agent>-YYYYMMDD-...",
+#       "pid":              <integer>,     // agent runtime pid
+#       "started_at":       <epoch>,
+#       "last_prompt_at":   <epoch|null>,
+#       "last_tool_at":     <epoch|null>,
+#       "last_stop_at":     <epoch|null>,
+#       "ended_at":         <epoch|null>
+#     }
+#   Files whose ended_at is >1h old get garbage-collected lazily.
+#
+# DESIGN NOTES
+#   - Fail-open: every error path exits 0 so presence tracking never
+#     blocks an agent's tool call.
+#   - PID is the hook's parent ($PPID) — that's the agent runtime
+#     itself.  board.py's `_pid_alive` uses `os.kill(pid, 0)` to detect
+#     a crashed session that never got to emit SessionEnd.
+#   - JSON writes go through a tmp file + `mv -f` so concurrent readers
+#     never see a half-written file.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+
+# bash 5.3.9 sporadically deadlocks `INPUT=$(cat)` (any $() with stdin).
+# `cos_read_stdin_bounded` uses perl alarm — bounded read, never hangs.
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Parse all four payload fields in ONE jq spawn (was four separate jq calls,
+# each a ~30ms process startup; this hook fires on EVERY tool call + lifecycle
+# event). Empty fields carry a sentinel: bash `read` treats TAB as whitespace
+# IFS, so consecutive tabs COLLAPSE and a missing .model silently shifted
+# every later column left (sdk_uuid ended up holding the transcript path,
+# killing the sid→chat bridge). The sentinel keeps columns positional.
+_PRES_EMPTY="__COS_EMPTY__"
+_PRES_FIELDS=""
+if [[ -n "$INPUT" ]]; then
+  _PRES_FIELDS=$(printf '%s' "$INPUT" | jq -r --arg e "$_PRES_EMPTY" \
+    '[.hook_event_name, .model, .session_id, .transcript_path] | map(if . == null or . == "" then $e else . end) | @tsv' \
+    2>/dev/null || true)
+fi
+IFS=$'\t' read -r EVENT_RAW HOOK_MODEL HOOK_SDK_UUID HOOK_TRANSCRIPT <<< "$_PRES_FIELDS"
+[[ "$EVENT_RAW" == "$_PRES_EMPTY" ]] && EVENT_RAW=""
+[[ "$HOOK_MODEL" == "$_PRES_EMPTY" ]] && HOOK_MODEL=""
+[[ "$HOOK_SDK_UUID" == "$_PRES_EMPTY" ]] && HOOK_SDK_UUID=""
+[[ "$HOOK_TRANSCRIPT" == "$_PRES_EMPTY" ]] && HOOK_TRANSCRIPT=""
+
+# Derive the logical event.  Prefer the explicit hook_event_name field
+# Claude Code sends; fall back to `$1` so the script stays testable
+# from the CLI (e.g. `bash agent-presence.sh start`).
+if [[ -z "$EVENT_RAW" ]]; then
+  EVENT_RAW="${1:-}"
+fi
+
+case "$EVENT_RAW" in
+  SessionStart|start)      EVENT="start" ;;
+  UserPromptSubmit|prompt) EVENT="prompt" ;;
+  PreToolUse|PostToolUse|tool) EVENT="tool" ;;
+  PostToolUseFailure)      EVENT="tool" ;;   # tool errored — still recent activity
+  SubagentStart)           EVENT="tool" ;;   # sub-session spawn: parent is active
+  SubagentStop)            EVENT="tool" ;;   # sub-session done: parent activity
+  Stop|stop)               EVENT="stop" ;;
+  SessionEnd|end)          EVENT="end" ;;
+  *)                       EVENT="tool" ;;   # safest default: count as activity
+esac
+
+PRESENCE_DIR="${COS_AGENT_DIR}/sessions"
+mkdir -p "$PRESENCE_DIR" 2>/dev/null || exit 0
+
+# Presence is an AGENT-LEVEL (shared) signal — the reader
+# (board_os/presence.py, web/routes/presence.py) scans
+# $COS_AGENT_DIR/sessions/ and keys on $COS_AGENT_DIR/session-id.
+# repointed $COS_SESSION_FILE at the per-panel dir, which only
+# session-context.sh seeds (it alone upgrades the panel id from stdin).
+# PreToolUse hooks resolve the ppid-fallback panel and find no session-id
+# there, so the old unconditional exit killed presence for every live
+# session. Fall back to the agent-level session-id so presence keeps
+# writing — this matches where the reader already looks.
+SESSION_ID_FILE="$COS_SESSION_FILE"
+[[ -f "$SESSION_ID_FILE" ]] || SESSION_ID_FILE="${COS_AGENT_DIR}/session-id"
+if [[ ! -f "$SESSION_ID_FILE" ]]; then
+  exit 0
+fi
+SESSION_ID="$(cat "$SESSION_ID_FILE" 2>/dev/null | tr -d '[:space:]' || true)"
+[[ -z "$SESSION_ID" ]] && exit 0
+# Defense-in-depth — the session-id file is one we write, but it lives
+# in a per-agent directory any runtime can touch.  Reject anything that
+# couldn't be a filename so PRESENCE_FILE can never escape sessions/.
+if ! [[ "$SESSION_ID" =~ ^[A-Za-z0-9_-]+$ ]]; then
+  cos_log_hook agent-presence warn "rejected session id with invalid chars" 2>/dev/null || true
+  exit 0
+fi
+
+# PPID is the agent runtime; a later `kill -0 $pid` from board.py proves
+# the session is alive even when no hook has fired for minutes.
+AGENT_PID="${PPID:-$$}"
+NOW="$(date +%s)"
+PRESENCE_FILE="${PRESENCE_DIR}/${SESSION_ID}.json"
+
+# Delegate JSON merge to a separate helper. Inline `python3 - <<'PY'`
+# sporadically deadlocks in heredoc_write on bash 5.3.9 — and this hook
+# fires on every tool call, so even rare hangs accumulate dozens of
+# zombies that starve agent runtime spawns. Form B (separate .py)
+# is the only deadlock-immune pattern. Resolve via readlink so symlinked
+# install paths still find _helpers/.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+COS_HOOK_SRC_DIR="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+
+PRESENCE_HELPER="${COS_HOOK_SRC_DIR}/_helpers/presence_write.py"
+# HOOK_MODEL / HOOK_SDK_UUID / HOOK_TRANSCRIPT were already parsed (with
+# hook_event_name) in the single jq spawn near the top. model = Claude Code 2.x
+# `.model`; sdk_uuid = host runtime `.session_id` (bridge to the chat
+# transcript); transcript = the Stop payload's live transcript path (TASK-255).
+# Empty values fall through — the helper preserves previously-stored fields.
+if [[ -f "$PRESENCE_HELPER" ]]; then
+  python3 "$PRESENCE_HELPER" \
+    "$PRESENCE_FILE" "$COS_AGENT" "$SESSION_ID" "$AGENT_PID" "$EVENT" "$NOW" \
+    "$HOOK_MODEL" "$HOOK_SDK_UUID" "$HOOK_TRANSCRIPT" \
+    2>/dev/null || true
+fi
+
+# Lazy GC — drop presence files whose session ended >1h ago.
+# The hook fires on every tool call; running the GC scan every time adds
+# noticeable overhead on busy sessions (python3 startup + readdir + stat).
+# Throttle to once per ~60s: cheap-enough to forget, rare-enough to skip.
+GC_TICK=$((NOW / 60))
+GC_MARKER="${PRESENCE_DIR}/.gc-tick"
+RUN_GC=0
+if [[ ! -f "$GC_MARKER" ]] || [[ "$(cat "$GC_MARKER" 2>/dev/null)" != "$GC_TICK" ]]; then
+  echo "$GC_TICK" > "$GC_MARKER" 2>/dev/null || true
+  RUN_GC=1
+fi
+if [[ "$RUN_GC" == "1" ]]; then
+  GC_HELPER="${COS_HOOK_SRC_DIR}/_helpers/presence_gc.py"
+  if [[ -f "$GC_HELPER" ]]; then
+    python3 "$GC_HELPER" "$PRESENCE_DIR" "$NOW" 2>/dev/null || true
+  fi
+fi
+
+cos_log_hook agent-presence fire "event=${EVENT}" 2>/dev/null || true
+exit 0

core/hooks/auto-brain-decay.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# SessionStart hook: run confidence decay on learned_patterns once per 24 h.
+#
+# Rationale: without a scheduler, pattern confidence never fades — stale
+# rules keep surfacing in cos_learn_suggest long after they stopped
+# matching reality. Ebbinghaus decay is applied by
+# src/core/thinking_os/decay.py; this hook just debounces it so we don't
+# re-run on every session start.
+#
+# Debounce file: <db-dir>/.last-decay (unix ts), shared with decay.py. 24 h window.
+# Fire-and-forget — never blocks session start.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+COS_STATE_DIR="${COS_STATE_DIR:-.coding-os}"
+COS_DB_PATH="${COS_DB_PATH:-$COS_STATE_DIR/coding-os.db}"
+
+cos_log_hook auto-brain-decay fire
+
+NOW_TS=$(date +%s)
+# Align with decay.py::run_decay_locked, which marks/throttles + flocks on
+# `<db-dir>/.last-decay`. When COS_DB_PATH sits outside
+# COS_STATE_DIR the two diverged — this hook would re-run decay the nightly
+# job just throttled. Derive from the DB dir so both share one marker + lock.
+LAST_RUN_FILE="$(dirname "$COS_DB_PATH")/.last-decay"
+DEBOUNCE_SECONDS=$((24 * 60 * 60))
+
+# ---------------------------------------------------------------------------
+# Stale state-file GC.
+#
+# WHY
+#   Session-scoped markers under $COS_AGENT_DIR (.thinking_os-gate,
+#   .doc-anchor, .memory-check, .roles, .role, .situation, .active-skill,
+#   .zoom-checkpoint, .rename-plan, .graph-context, .task-current) are
+#   bound to a single session. Old sessions' markers stay on disk forever
+#   unless something reaps them. Over months of dogfooding the agent dir
+#   accumulates hundreds-thousands of stale dotfiles and traces/*.jsonl
+#   blobs, polluting `ls`, slowing `find`, and confusing debug runs.
+#
+# POLICY
+#   - Marker dotfiles older than 7 days → deleted.
+#   - traces/*.jsonl older than 30 days → deleted.
+#   - Bounded to ${COS_AGENT_DIR} only (never touches the shared
+#     COS_STATE_DIR root). Symlinks ignored.
+#
+# Runs UNCONDITIONALLY before the DB-debounced decay below — even fresh
+# installs without a DB benefit from the cleanup, and the GC is cheap
+# enough (≤20 stat calls) to run inline. Errors silently ignored.
+# ---------------------------------------------------------------------------
+if [[ -d "${COS_AGENT_DIR:-}" ]]; then
+  for marker in .thinking_os-gate .doc-anchor .memory-check .roles .role \
+                .situation .active-skill .zoom-checkpoint .rename-plan \
+                .graph-context .task-current; do
+    f="$COS_AGENT_DIR/$marker"
+    if [[ -f "$f" ]]; then
+      mtime=$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null || echo 0)
+      if [[ "$mtime" -gt 0 ]] && [[ $((NOW_TS - mtime)) -gt $((7 * 24 * 60 * 60)) ]]; then
+        rm -f "$f" 2>/dev/null || true
+        cos_log_hook auto-brain-decay gc "removed=${marker} age_s=$((NOW_TS - mtime))"
+      fi
+    fi
+  done
+  if [[ -d "$COS_AGENT_DIR/traces" ]]; then
+    find "$COS_AGENT_DIR/traces" -maxdepth 1 -type f -name '*.jsonl' \
+      -mtime +30 -delete 2>/dev/null || true
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Per-panel orphan GC.
+#
+# WHY
+#   Each panel of the same agent gets its own $COS_AGENT_DIR/panels/<panel-id>/
+#   subdir (see docs/engineering/state-files.md § per-panel isolation). When
+#   a panel terminates without firing Stop (laptop sleeps, agent crashes,
+#   tab killed), its subdir lingers. Without GC, repeated dogfooding leaves
+#   hundreds of dead panel dirs.
+#
+# POLICY
+#   - panels/<id>/ dirs whose heartbeat is older than COS_PANEL_GC_TTL
+#     (default 24 h) → entire subdir removed.
+#   - Live panels (heartbeat fresh) are never touched, even if old; the
+#     heartbeat file is rewritten by cos-env.sh on every hook fire so any
+#     active panel will pass the freshness check.
+#   - The current panel is explicitly excluded ($COS_PANEL_DIR) so the
+#     running session never garbage-collects itself mid-flight.
+#   - Fail-open: any error during GC is swallowed (this is a hygiene
+#     sweep, never a correctness gate).
+# ---------------------------------------------------------------------------
+COS_PANEL_GC_TTL="${COS_PANEL_GC_TTL:-86400}"        # 24 h for real panels
+COS_PANEL_GC_ORPHAN_TTL="${COS_PANEL_GC_ORPHAN_TTL:-3600}"  # 1 h for no-session orphans
+if [[ -d "${COS_AGENT_DIR:-}/panels" ]]; then
+  for panel_dir in "${COS_AGENT_DIR}/panels"/*/; do
+    [[ -d "$panel_dir" ]] || continue
+    panel_dir="${panel_dir%/}"
+    if [[ "$panel_dir" == "$COS_PANEL_DIR" ]]; then
+      continue
+    fi
+    heartbeat_file="${panel_dir}/heartbeat"
+    session_id_file="${panel_dir}/session-id"
+    # Tier 1 — orphan: no session-id was ever written. The only thing
+    # that writes session-id into a panel dir is
+    # cos_panel_upgrade_from_payload (called by session-context.sh on a
+    # real Claude/Codex hook fire). A panel dir without session-id was
+    # created by a stray bash invocation (test, sourced cos-env.sh, etc.)
+    # whose PPID happened to hash to a unique panel-id — never a real
+    # agent session. Reap aggressively (default 1 h) to keep the panels/
+    # subtree from growing without bound during test runs and shell work.
+    if [[ ! -s "$session_id_file" ]]; then
+      orphan_age=0
+      if [[ -f "$heartbeat_file" ]]; then
+        hb=$(stat -c %Y "$heartbeat_file" 2>/dev/null || stat -f %m "$heartbeat_file" 2>/dev/null || echo 0)
+        [[ "$hb" -gt 0 ]] && orphan_age=$((NOW_TS - hb))
+      else
+        # No heartbeat either — use dir mtime.
+        mt=$(stat -c %Y "$panel_dir" 2>/dev/null || stat -f %m "$panel_dir" 2>/dev/null || echo 0)
+        [[ "$mt" -gt 0 ]] && orphan_age=$((NOW_TS - mt))
+      fi
+      if [[ "$orphan_age" -gt "$COS_PANEL_GC_ORPHAN_TTL" ]]; then
+        rm -rf "$panel_dir" 2>/dev/null || true
+        cos_log_hook auto-brain-decay gc "removed_orphan_panel=$(basename "$panel_dir") age_s=${orphan_age}"
+      fi
+      continue
+    fi
+    # Tier 2 — stale real panel: heartbeat older than 24 h.
+    if [[ -f "$heartbeat_file" ]]; then
+      hb=$(stat -f %m "$heartbeat_file" 2>/dev/null || stat -c %Y "$heartbeat_file" 2>/dev/null || echo 0)
+      if [[ "$hb" -gt 0 ]] && [[ $((NOW_TS - hb)) -lt "$COS_PANEL_GC_TTL" ]]; then
+        continue  # panel is live
+      fi
+    fi
+    rm -rf "$panel_dir" 2>/dev/null || true
+    cos_log_hook auto-brain-decay gc "removed_panel=$(basename "$panel_dir")"
+  done
+fi
+
+# DB absent (fresh install, no patterns yet) → skip pattern decay (GC above
+# already ran).
+if [ ! -f "$COS_DB_PATH" ]; then
+  cos_log_hook auto-brain-decay skip "reason=no_db"
+  exit 0
+fi
+
+if [ -f "$LAST_RUN_FILE" ]; then
+  LAST_TS=$(cat "$LAST_RUN_FILE" 2>/dev/null | tr -d '[:space:]')
+  if [ -n "$LAST_TS" ] && [ "$LAST_TS" -gt 0 ] 2>/dev/null; then
+    DELTA=$((NOW_TS - LAST_TS))
+    if [ "$DELTA" -lt "$DEBOUNCE_SECONDS" ]; then
+      cos_log_hook auto-brain-decay skip "reason=debounced age_s=${DELTA}"
+      exit 0
+    fi
+  fi
+fi
+
+# Resolve the decay script path across meta and consumer layouts.
+DECAY_SCRIPT=""
+for CAND in \
+  "$(dirname "$0")/../thinking_os/decay.py" \
+  ".coding-os/thinking_os/decay.py" \
+  "src/core/thinking_os/decay.py"; do
+  if [ -f "$CAND" ]; then
+    DECAY_SCRIPT="$CAND"
+    break
+  fi
+done
+if [ -z "$DECAY_SCRIPT" ]; then
+  cos_log_hook auto-brain-decay skip "reason=script_not_found"
+  exit 0
+fi
+
+# Fire-and-forget — decay.py is bounded (ms per pattern, no I/O beyond
+# the DB) but we still run in the background so SessionStart latency is
+# untouched.
+(
+  COS_DB_PATH="$COS_DB_PATH" \
+  python3 "$DECAY_SCRIPT" > /dev/null 2>&1 \
+    && echo "$NOW_TS" > "$LAST_RUN_FILE"
+) &
+
+exit 0
+
+exit 0

core/hooks/auto-compose-roles.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# auto-compose-roles.sh (UserPromptSubmit) — auto-fire role composition.
+#
+# Closes the dead-trigger gap: cos_compose_chain had no automatic
+# caller, so .roles was never written and the Hub Roles panel was always
+# empty. This hook reads the recorded complexity gate and, for COMPLICATED/
+# COMPLEX classifications, composes a role chain via _helpers/auto_compose.py
+# (which stamps .roles/.role + emits a compose_done trace). It surfaces the
+# composed lead role as additionalContext so the agent knows its chain.
+#
+# Debounce: once per session per gate value (re-composes if the gate class
+# changes). Fail-open: any error exits 0 — never blocks the prompt.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+cos_log_hook auto-compose-roles enter || true
+
+# Read the user prompt from stdin so the composer gets real action/domain
+# signals. Without it the chain collapses to ['analyst'] for every
+# COMPLICATED/COMPLEX prompt. Bounded; fail-open to empty.
+INPUT="$(cos_read_stdin_bounded 2 2>/dev/null || true)"
+PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)"
+
+GATE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate"
+[[ -f "$GATE_FILE" ]] || exit 0
+
+# Validate gate freshness/ownership (same contract as nudge-thinking-os).
+source "$(dirname "$0")/check-state.sh" 2>/dev/null || true
+if type check_state >/dev/null 2>&1; then
+  check_state "$GATE_FILE" 7200
+  [[ "${STATE_VALID:-}" == "true" ]] || exit 0
+  GATE_VALUE="${STATE_VALUE:-}"
+else
+  GATE_VALUE=$(head -1 "$GATE_FILE" 2>/dev/null | cut -d' ' -f2- || true)
+fi
+
+GATE_CLASS=$(printf '%s' "$GATE_VALUE" | awk '{print $1}')
+GATE_DIMS=$(printf '%s' "$GATE_VALUE" | awk '{print $2}')
+# CLEAR passes too: the helper composes a role chain only for COMPLICATED/
+# COMPLEX but surfaces learn_suggest recall for ANY formal gate, so simple
+# tasks also feed .learn-suggestions (the validation loop's only input).
+case "$GATE_CLASS" in
+  CLEAR|COMPLICATED|COMPLEX) ;;
+  *) exit 0 ;;
+esac
+
+# Debounce: one compose per (session, gate-class). Marker records the class
+# we last composed for; re-compose only when the class changes.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.roles-composed"
+if [[ -f "$MARKER" ]]; then
+  LAST=$(head -1 "$MARKER" 2>/dev/null | tr -d '\n\r' || true)
+  [[ "$LAST" == "$GATE_CLASS" ]] && exit 0
+fi
+
+# Resolve the helper through the hook symlink.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HSRC="$(cd -P "$(dirname "$_src")" && pwd)"
+HELPER="${HSRC}/_helpers/auto_compose.py"
+[[ -f "$HELPER" ]] || exit 0
+
+# Panel-first target so .roles/.role land where the banner + Hub read them
+# (same per-panel scope as every other cognitive marker).
+TARGET_DIR="${COS_PANEL_DIR:-${COS_AGENT_DIR:-${COS_STATE_DIR:-.coding-os}/${COS_AGENT:-claude}}}"
+OUT=$(printf '%s' "$PROMPT" | python3 "$HELPER" "$GATE_CLASS" "${GATE_DIMS:-1}" "$TARGET_DIR" 2>/dev/null || true)
+
+mkdir -p "$(dirname "$MARKER")" 2>/dev/null || true
+printf '%s' "$GATE_CLASS" > "$MARKER" 2>/dev/null || true
+
+if [[ -n "$OUT" ]]; then
+  cos_log_hook auto-compose-roles ok "class=${GATE_CLASS}" || true
+  printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$OUT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+else
+  cos_log_hook auto-compose-roles ok "class=${GATE_CLASS} composed=none" || true
+fi
+
+exit 0