coding-os 0.3.2__py3-none-any.whl

core/hooks/capture-tool-failure.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# PostToolUseFailure hook: pipe event payload to tool_failure_capture.py.
+# Reads session_id from COS_SESSION_FILE and db_path from COS_DB_PATH,
+# both exported by cos-env.sh which Claude Code sources via sourced_hooks.
+# Fire-and-forget — never blocks or errors visibly.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+SESSION_ID=""
+if [[ -f "${COS_SESSION_FILE:-}" ]]; then
+  SESSION_ID=$(cat "$COS_SESSION_FILE")
+fi
+
+if [[ -z "$SESSION_ID" || -z "${COS_DB_PATH:-}" || ! -f "$COS_DB_PATH" ]]; then
+  exit 0
+fi
+
+CAPTURE_PY="$(_cos_helpers_dir 2>/dev/null)/tool_failure_capture.py"
+if [[ ! -f "$CAPTURE_PY" ]]; then
+  exit 0
+fi
+
+python3 "$CAPTURE_PY" "$SESSION_ID" "$COS_DB_PATH" || true

core/hooks/capture-work-log.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# PostToolUse: after Write/Edit on code files when .task-current is set
+# Appends ONE line to the active task's Work Log with `flock` serialization
+# for multi-agent safety (R-L-26, R-L-3).
+#
+# Claude-only: Codex sessions lack PostToolUse delivery — they must call
+# cos_work_log_append() explicitly (see AGENTS.md fragment).
+#
+# Fire-and-forget: never blocks, fail-soft on any error.
+
+set -eu  # NOT -o pipefail — we want to tolerate soft failures.
+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 "capture-work-log" "entry" 2>/dev/null || true
+
+# Only care about Edit/Write on code files.
+payload="$(cos_read_stdin_bounded 5)"
+tool_name="$(echo "$payload" | python3 -c '
+import json, sys
+try:
+    print(json.load(sys.stdin).get("tool_name", ""))
+except Exception:
+    print("")
+' 2>/dev/null || echo "")"
+
+case "$tool_name" in
+    Edit|Write|MultiEdit) ;;
+    *) exit 0 ;;
+esac
+
+# Resolve active task.
+task_current_file="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os/claude}}/.task-current"  # panel-first: .task-current is per-panel
+[[ -f "$task_current_file" ]] || exit 0
+task_current="$(tr -d ' \n' < "$task_current_file" 2>/dev/null)"
+[[ -n "$task_current" ]] || exit 0
+
+# Extract TASK-NNN if the marker contains one, else skip (marker may be
+# a slug like "phase-l-implementation" which doesn't map to a task file).
+task_id="$(echo "$task_current" | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || true)"
+[[ -n "$task_id" ]] || exit 0
+
+# Derive summary from the tool call.
+summary="$(echo "$payload" | python3 -c '
+import json, os, sys
+try:
+    d = json.load(sys.stdin)
+    ti = d.get("tool_input", {})
+    fp = ti.get("file_path", "")
+    desc = ti.get("description") or ""
+    # Prefer description if set; else synthesize.
+    if desc:
+        out = f"{desc[:80]} ({os.path.basename(fp)})"
+    else:
+        out = f"Edit {os.path.basename(fp)}"
+    print(out[:120])
+except Exception:
+    print("")
+' 2>/dev/null || echo "")"
+[[ -n "$summary" ]] || exit 0
+
+# Background fire-and-forget. bash 5.3.9 deadlocks `python3 - <<HEREDOC`;
+# extracted to _helpers/work_log_append.py. task_id and summary pass via
+# argv (avoids triple-quote escaping fragility too). Serialization lives
+# INSIDE the helper (fcntl) — the old bash-side `flock -w 2` died silently
+# on macOS, where flock(1) does not exist, dropping every append (TASK-340).
+_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)"
+unset _src _dir
+HELPER="${HSRC}/_helpers/work_log_append.py"
+if [[ -f "$HELPER" ]]; then
+  COS_PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}" \
+    python3 "$HELPER" "$task_id" "$summary" >/dev/null 2>&1 &
+fi
+
+cos_log_hook "capture-work-log" "spawned" 2>/dev/null || true
+
+# Visible signal — record per-turn activity (rendered by next pulse) +
+# emit systemMessage for future agent renderers / SDK consumers.
+cos_record_activity worklog "+1 ${task_id}" 2>/dev/null || true
+printf '%s' "{\"systemMessage\":\"[worklog] +1 ${task_id}\"}"
+
+exit 0

core/hooks/check-agents-md-refs.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# PostToolUse hook: flag dead references in AGENTS.md to src/core/rules or src/core/skills.
+#
+# AGENTS.md references paths like `src/core/rules/thinking_os.md` and
+# `src/core/skills/clean-code/SKILL.md` so Codex (and any agent without a
+# skill-system) can on-demand read the full content. If a file is
+# renamed or deleted, the reference becomes dangling — the agent hits
+# a dead read.
+#
+# This hook fires on edits to AGENTS.md OR to src/core/rules/** and
+# src/core/skills/** (since renaming a referenced file also breaks things).
+# Non-blocking: warns only. The fix is a one-liner edit either to the
+# renamed file or to AGENTS.md.
+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)"
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+[[ -z "$FILE_PATH" ]] && exit 0
+
+case "$FILE_PATH" in
+  */AGENTS.md|AGENTS.md) ;;
+  */core/rules/*.md) ;;
+  */core/skills/*/SKILL.md) ;;
+  *) exit 0 ;;
+esac
+
+cos_log_hook check-agents-md-refs fire "trigger=${FILE_PATH}"
+
+# Locate AGENTS.md from the file path (may be editing from a subdir).
+AGENTS_MD=""
+DIR=$(dirname "$FILE_PATH")
+while [[ "$DIR" != "/" && "$DIR" != "." ]]; do
+  if [[ -f "${DIR}/AGENTS.md" ]]; then
+    AGENTS_MD="${DIR}/AGENTS.md"
+    break
+  fi
+  DIR=$(dirname "$DIR")
+done
+if [[ -z "$AGENTS_MD" && -f "AGENTS.md" ]]; then
+  AGENTS_MD="AGENTS.md"
+fi
+[[ -z "$AGENTS_MD" ]] && exit 0
+
+PROJECT_ROOT=$(dirname "$AGENTS_MD")
+
+# Extract core/... references (with or without leading ./).
+MISSING=()
+while read -r REF; do
+  [[ -z "$REF" ]] && continue
+  # Normalize: strip backticks / quotes / markdown link syntax.
+  CLEAN=$(echo "$REF" | sed -E 's/[][`()"]//g; s/^\.\///')
+  # Handle markdown [text](path) — keep path portion only.
+  CLEAN=$(echo "$CLEAN" | sed -E 's/^[A-Za-z][^]]*\]\(//; s/#L[0-9-]+$//')
+  TARGET="${PROJECT_ROOT}/${CLEAN}"
+  if [[ ! -e "$TARGET" ]]; then
+    MISSING+=("$CLEAN")
+  fi
+done < <(grep -oE '(^|[^a-zA-Z0-9_/-])core/(rules|skills)/[A-Za-z0-9_./-]+' "$AGENTS_MD" \
+         | sed -E 's/^[^c]*//' | sort -u)
+
+if [[ ${#MISSING[@]} -gt 0 ]]; then
+  cos_log_hook check-agents-md-refs warn "dead=${#MISSING[@]}"
+  echo "⚠️  AGENTS.md references ${#MISSING[@]} path(s) that no longer exist:" >&2
+  for M in "${MISSING[@]}"; do
+    echo "    - $M" >&2
+  done
+  echo "   Fix: update AGENTS.md or restore/rename the referenced file." >&2
+  exit 0
+fi
+
+cos_log_hook check-agents-md-refs ok ""
+exit 0

core/hooks/check-agents-md-size.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# PostToolUse hook: warn if AGENTS.md approaches Codex's 32 KiB read cap.
+#
+# Codex CLI reads AGENTS.md up to project_doc_max_bytes (default 32768).
+# When this file overflows, Codex silently truncates the tail — agents
+# get a partial brain with no error. This hook surfaces the drift early.
+#
+# Non-blocking: warns only. AGENTS.md is often the biggest SSOT file and
+# legitimately grows; the hook's job is to make the user aware, not to
+# prevent legitimate growth.
+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)"
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+[[ -z "$FILE_PATH" ]] && exit 0
+case "$FILE_PATH" in
+  */AGENTS.md|AGENTS.md) ;;
+  *) exit 0 ;;
+esac
+
+cos_log_hook check-agents-md-size fire "path=${FILE_PATH}"
+
+CODEX_CAP=32768
+WARN_AT=28672   # ~28 KiB — gives ~4 KiB buffer before Codex truncates
+
+if [[ ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+SIZE=$(wc -c < "$FILE_PATH" | tr -d ' ')
+
+if [[ "$SIZE" -ge "$CODEX_CAP" ]]; then
+  cos_log_hook check-agents-md-size error "size=${SIZE} >= ${CODEX_CAP}"
+  echo "⚠️  AGENTS.md is ${SIZE} bytes — OVER Codex's ${CODEX_CAP} cap." >&2
+  echo "   Codex will silently truncate. Move detail into src/core/rules/ or docs/," >&2
+  echo "   keep only high-signal navigation + invariants here." >&2
+  exit 0  # warn, never block — user may be mid-edit
+fi
+
+if [[ "$SIZE" -ge "$WARN_AT" ]]; then
+  cos_log_hook check-agents-md-size warn "size=${SIZE} nearing cap ${CODEX_CAP}"
+  echo "ℹ️  AGENTS.md is ${SIZE} bytes (~$((SIZE * 100 / CODEX_CAP))% of Codex's ${CODEX_CAP} cap)." >&2
+fi
+
+cos_log_hook check-agents-md-size ok "size=${SIZE}"
+exit 0

core/hooks/check-capture-worked.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Stop hook: warn if this session made code changes but captured zero
+# observations. A silent capture failure (DB path broken, schema stale,
+# missing RAG extras) leaves the session with "work happened, nothing
+# was learned" — invisible unless we actively check.
+#
+# Runs at session end (Stop event). Never blocks — at this point the
+# session is already wrapping up — just surfaces the drift so the next
+# session starts from a clean, known state.
+#
+# Two signals:
+#   1. $COS_STATE_DIR/.capture-errors.log exists → at least one
+#      capture.py invocation failed this session. Print the error tail.
+#   2. observations table in the DB has zero rows tagged with this
+#      session_id, but the agent did edit code files this session. Warn
+#      about the silent failure.
+#
+# If MCP is down (warn-mcp-down already banner'd at SessionStart), we
+# still produce a concise "session-end recap" confirming the
+# observations count so the human knows exactly what was / wasn't saved.
+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}"
+
+# Resolve session-id via panel-first → agent-level → shared-root chain.
+# Without this, a resumed panel that never ran SessionStart:startup has
+# only the legacy agent-level session-id file and check-capture-worked
+# silently exits, missing the very drift it exists to detect.
+SESSION_ID=""
+if command -v cos_current_session >/dev/null 2>&1; then
+  SESSION_ID=$(cos_current_session 2>/dev/null || true)
+  [[ "$SESSION_ID" == "none" ]] && SESSION_ID=""
+fi
+if [[ -z "$SESSION_ID" ]]; then
+  for f in "${COS_SESSION_FILE:-}" "${COS_AGENT_DIR:-}/session-id" "$COS_STATE_DIR/session-id"; do
+    [[ -z "$f" || "$f" == "/session-id" ]] && continue
+    if [[ -f "$f" ]]; then
+      SESSION_ID=$(tr -d '\n\r' < "$f" | head -c 128)
+      [[ -n "$SESSION_ID" ]] && break
+    fi
+  done
+fi
+[[ -z "$SESSION_ID" ]] && exit 0
+cos_log_hook check-capture-worked fire
+
+ERROR_LOG="$COS_STATE_DIR/.capture-errors.log"
+ERRORS_FOUND=0
+
+# --- 1. Scan capture error log ---------------------------------------
+if [[ -f "$ERROR_LOG" ]] && [[ -s "$ERROR_LOG" ]]; then
+  ERRORS_FOUND=$(wc -l < "$ERROR_LOG" | tr -d ' ')
+fi
+
+# --- 2. Count observations in this session ---------------------------
+OBS_COUNT=-1
+if [[ -f "$COS_DB_PATH" ]]; then
+  # SQLite may not be installed in bare environments, so fallback to
+  # Python which we already depend on.
+  # bash 5.3.9 deadlocks `$(python3 - <<HEREDOC)`. Form B (helper file)
+  # is the only deadlock-immune pattern.
+  _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)"
+  unset _src _dir
+  HELPER="${HSRC}/_helpers/observation_count.py"
+  if [[ -f "$HELPER" ]]; then
+    OBS_COUNT=$(python3 "$HELPER" "$COS_DB_PATH" "$SESSION_ID" 2>/dev/null || echo -1)
+  else
+    OBS_COUNT=-1
+  fi
+fi
+
+# --- 2b. Count Write/Edit operations this session ------------------
+# A read-only session (no code edits) is EXPECTED to have 0 observations,
+# so the "0 obs" branch below is not actionable. We only flag drift when
+# the session actually attempted to capture something. Heuristic:
+# capture-observation.sh logs `fire tool=<X>` for every PostToolUse it
+# sees; counting `tool=Write` + `tool=Edit` entries for this session
+# tells us whether capture had any work to do.
+HOOKS_LOG="${COS_STATE_DIR}/.hooks.log"
+WRITE_EDIT_COUNT=0
+if [[ -f "$HOOKS_LOG" ]]; then
+  # The standard hook log line shape is:
+  #   [<ts>] [capture-observation] [fire] agent=<a> session=<sid> task=<t> tool=<T>
+  # so the literal "[capture-observation] [fire]" prefix comes BEFORE the
+  # session= field. The previous regex demanded the opposite order and
+  # silently always returned 0, falsely classifying every session as
+  # "read-only-session" even after Edits. Anchor on the prefix first,
+  # then assert the session id and tool downstream.
+  WRITE_EDIT_COUNT=$(grep -cE "\[capture-observation\] \[fire\].*session=${SESSION_ID}.*tool=(Write|Edit)" "$HOOKS_LOG" 2>/dev/null || echo 0)
+  WRITE_EDIT_COUNT=${WRITE_EDIT_COUNT//[^0-9]/}
+  : "${WRITE_EDIT_COUNT:=0}"
+fi
+
+# --- 3. Decide what to say ------------------------------------------
+# Silent success path: no errors AND observations > 0 → nothing to say.
+if [[ "$ERRORS_FOUND" == "0" ]] && [[ "$OBS_COUNT" -gt 0 ]]; then
+  cos_log_hook check-capture-worked ok "observations=${OBS_COUNT}"
+  exit 0
+fi
+
+# Silent expected path: no errors, 0 obs, AND 0 Write/Edit calls →
+# read-only / dispatch-only session. Capture had nothing to record;
+# suppress the warning (it would be noise on every read-only session).
+if [[ "$ERRORS_FOUND" == "0" ]] && [[ "$OBS_COUNT" -eq 0 ]] && [[ "$WRITE_EDIT_COUNT" -eq 0 ]]; then
+  cos_log_hook check-capture-worked ok "observations=0 reason=read-only-session"
+  exit 0
+fi
+
+# Be useful at session end. Keep output short.
+# Stop hooks in current Codex expect JSON on stdout when they emit
+# anything at exit 0, so warnings go to stderr instead.
+echo "" >&2
+echo "📊 [session recap] observations captured: $OBS_COUNT" >&2
+
+if [[ "$ERRORS_FOUND" -gt 0 ]]; then
+  echo "⚠️  capture-observation failed $ERRORS_FOUND time(s) this session." >&2
+  echo "   See last 3 errors:" >&2
+  tail -n 3 "$ERROR_LOG" | sed 's/^/     /' >&2
+  echo "   Likely cause: MCP / DB path broken. Run \`cos doctor\` to confirm." >&2
+fi
+
+if [[ "$OBS_COUNT" == "0" ]] && [[ "$WRITE_EDIT_COUNT" -gt 0 ]]; then
+  echo "⚠️  ${WRITE_EDIT_COUNT} Write/Edit call(s) this session, 0 observations recorded —" >&2
+  echo "   thinking_os memory did NOT learn from those edits. Check MCP wiring +" >&2
+  echo "   DB path; run \`cos doctor\` to confirm." >&2
+fi
+
+if [[ "$OBS_COUNT" == "-1" ]]; then
+  echo "⚠️  Could not query observations — DB missing or inaccessible at" >&2
+  echo "   $COS_DB_PATH" >&2
+fi
+
+# Truncate the error log for the next session (keep it scoped).
+if [[ -f "$ERROR_LOG" ]]; then
+  : > "$ERROR_LOG"
+fi
+cos_log_hook check-capture-worked warn "observations=${OBS_COUNT} errors=${ERRORS_FOUND}"
+
+exit 0

core/hooks/check-doc-size.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# PostToolUse Write|Edit hook: warn when docs grow beyond layer-specific budgets.
+# Soft limits — agent must judge whether to split or compress. No blocking.
+#
+# Budgets (lines, derived from header `layer:`):
+#   index      ≤ 200
+#   playbook   ≤ 500
+#   spec       ≤ 800
+#   policy     ≤ 400
+#   reference  ≤ 600
+#   adr        ≤ 300
+#   task       ≤ 250  (tighter than lint-task soft limit; both fire OK)
+# Files without a recognised layer header are skipped (not all md is governed).
+
+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 "check-doc-size" "entry" 2>/dev/null || true
+
+payload="$(cos_read_stdin_bounded 5)"
+file_path="$(echo "$payload" | python3 -c '
+import json, sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("file_path", ""))
+except Exception:
+    print("")
+' 2>/dev/null || echo "")"
+
+# Only check md files inside docs/
+case "$file_path" in
+    */docs/*.md) : ;;
+    *) exit 0 ;;
+esac
+
+[[ -f "$file_path" ]] || exit 0
+
+first_line="$(head -1 "$file_path" 2>/dev/null || echo "")"
+layer="$(echo "$first_line" | grep -oE 'layer:[a-z]+' | head -1 | cut -d: -f2)"
+[[ -n "$layer" ]] || exit 0
+
+case "$layer" in
+    index)     budget=200 ;;
+    playbook)  budget=500 ;;
+    spec)      budget=800 ;;
+    policy)    budget=400 ;;
+    reference) budget=600 ;;
+    adr)       budget=300 ;;
+    task)      budget=250 ;;
+    *) exit 0 ;;
+esac
+
+lines=$(wc -l < "$file_path" 2>/dev/null || echo 0)
+if (( lines > budget )); then
+    rel="${file_path#"$(pwd)/"}"
+    echo "WARN check-doc-size: $rel is ${lines} lines (layer:$layer budget ${budget})." >&2
+    echo "  Consider splitting into a sub-doc or compressing prose." >&2
+fi
+
+cos_log_hook "check-doc-size" "ok lines=$lines layer=$layer" 2>/dev/null || true
+exit 0

core/hooks/check-mcp-extras.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# check-mcp-extras.sh — SessionStart
+#
+# PURPOSE
+#   At session start, verify the global `cos` binary has the required Python
+#   extras (graph_os, board_os, rag/sentence_transformers). If any are missing,
+#   the MCP server crashes silently on launch — every cos_* tool call fails
+#   with no clear root cause visible to the agent.
+#
+#   Emits a loud, actionable warning with the exact fix command before the
+#   agent starts using cos_* tools.
+#
+# FAST — uses direct Python import check (<200ms). Does NOT start the server.
+# NON-BLOCKING — always exits 0.
+#
+# DESIGN
+#   1. Locate global cos binary via PATH (the one .mcp.json launches).
+#   2. Find its Python interpreter (sibling python3 in same bin/).
+#   3. Try importing required modules — failures = missing extras.
+#   4. If missing: emit warning + exact fix command.
+#   5. Log result regardless.
+
+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 check-mcp-extras entry 2>/dev/null || true
+
+# Locate global cos (the one .mcp.json uses — resolved via PATH)
+GLOBAL_COS="$(command -v cos 2>/dev/null || true)"
+if [[ -z "$GLOBAL_COS" ]]; then
+    cos_log_hook check-mcp-extras skip-cos-not-found 2>/dev/null || true
+    exit 0
+fi
+
+# Resolve the interpreter behind the cos entry point — the one whose site-packages
+# hold cos's extras. Shared with the outbox drain (cos_resolve_python in cos-env.sh).
+COS_PYTHON="$(cos_resolve_python)"
+if [[ -z "$COS_PYTHON" || ! -x "$COS_PYTHON" ]]; then
+    cos_log_hook check-mcp-extras skip-python-not-found 2>/dev/null || true
+    exit 0
+fi
+
+# Quick import check — no server startup needed
+MISSING="$("$COS_PYTHON" -c '
+missing = []
+checks = {
+    "graph_os":             "graph_os",
+    "board_os":             "board_os",
+    "sentence_transformers": "rag",
+}
+for mod, label in checks.items():
+    try:
+        __import__(mod)
+    except ImportError:
+        missing.append(label)
+print(",".join(missing))
+' 2>/dev/null || echo "check-failed")"
+
+if [[ -z "$MISSING" ]]; then
+    cos_log_hook check-mcp-extras ok 2>/dev/null || true
+    exit 0
+fi
+
+if [[ "$MISSING" == "check-failed" ]]; then
+    cos_log_hook check-mcp-extras python-check-error 2>/dev/null || true
+    exit 0
+fi
+
+# Find the source path for the fix command
+COS_SRC="$("$COS_PYTHON" -c '
+import pathlib, importlib.util
+spec = importlib.util.find_spec("cli")
+if spec and spec.origin:
+    print(pathlib.Path(spec.origin).parent.parent)
+' 2>/dev/null || true)"
+[[ -z "$COS_SRC" ]] && COS_SRC="<path-to-coding-os>"
+
+cos_log_hook check-mcp-extras "FAIL missing=${MISSING}" 2>/dev/null || true
+
+cat >&2 <<MSG
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  MCP will be DOWN — global cos missing: ${MISSING}
+
+   Every cos_* tool call will fail silently until fixed.
+
+   Fix (run in terminal, then restart Claude Code):
+     uv tool install --editable ${COS_SRC} --with "coding-os[rag,graph_os]"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+MSG
+
+exit 0

core/hooks/check-state.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Check a session-scoped state file belongs to the current session.
+# Usage: source check-state.sh  (then call: check_state <file> <max-age-seconds>)
+#
+# Returns via globals:
+#   STATE_VALID=true/false
+#   STATE_VALUE="the value without session prefix"
+#   STATE_REASON="why invalid" (if invalid)
+
+# Globals are read by callers after sourcing — shellcheck cannot follow that
+# control flow, so silence SC2034 at file scope.
+# shellcheck disable=SC2034
+
+check_state() {
+  local STATE_FILE_INPUT="$1"
+  local MAX_AGE="${2:-7200}"  # default 120 min
+
+  STATE_VALID=false
+  STATE_VALUE=""
+  STATE_REASON=""
+
+  # Source cos-env up front so cos_state_path is available for routing
+  # AND $COS_SESSION_FILE / $COS_PANEL_DIR resolve below.
+  source "$(dirname "${BASH_SOURCE[0]}")/cos-env.sh" 2>/dev/null || true
+
+  # Panel-first routing: if the caller passed a per-panel basename or an
+  # AGENT_DIR-anchored per-panel path, we look in $COS_PANEL_DIR first
+  # and fall back to the legacy $COS_AGENT_DIR location for one cycle
+  # so consumer projects mid-migration don't see "Session mismatch"
+  # spam. The reader trusts whichever path exists.
+  local STATE_FILE
+  if command -v cos_state_path >/dev/null 2>&1; then
+    STATE_FILE="$(cos_state_path "$STATE_FILE_INPUT")"
+  else
+    STATE_FILE="$STATE_FILE_INPUT"
+  fi
+  # NO AGENT_DIR fallback for per-panel files. Reading another panel's
+  # state via the shared agent dir is cross-panel leak — the failure
+  # mode this rule exists to prevent. Legacy fossils from earlier
+  # writers stay invisible until the panel re-stamps its own copy via
+  # write-state.sh (which now routes through $COS_PANEL_DIR).
+
+  # Check existence
+  if [[ ! -f "$STATE_FILE" ]]; then
+    STATE_REASON="File does not exist"
+    return
+  fi
+
+  # Read session ID and value
+  local CONTENT
+  CONTENT=$(head -1 "$STATE_FILE")
+  local FILE_SESSION
+  FILE_SESSION=$(echo "$CONTENT" | awk '{print $1}')
+  STATE_VALUE=$(echo "$CONTENT" | cut -d' ' -f2-)
+
+  # Check session match — STRICTLY from panel session-id file. No
+  # AGENT_DIR fallback (cross-panel leak protection).
+  # When the panel session-id file is missing, $COS_PANEL_ID is the
+  # synthesised identity that write-state.sh also uses.
+  local SESSION_FILE="$COS_SESSION_FILE"
+  local CURRENT_SESSION=""
+  if [[ -f "$SESSION_FILE" ]]; then
+    CURRENT_SESSION=$(cat "$SESSION_FILE")
+  elif [[ -n "${COS_PANEL_ID:-}" ]]; then
+    CURRENT_SESSION="$COS_PANEL_ID"
+  fi
+
+  if [[ -n "$CURRENT_SESSION" ]] && [[ -n "$FILE_SESSION" ]] && [[ "$FILE_SESSION" != "$CURRENT_SESSION" ]]; then
+    STATE_REASON="Session mismatch (file=$FILE_SESSION, current=$CURRENT_SESSION)"
+    return
+  fi
+
+  # Check freshness
+  local FILE_AGE
+  if [[ "$(uname)" == "Darwin" ]]; then
+    FILE_AGE=$(( $(date +%s) - $(stat -f %m "$STATE_FILE") ))
+  else
+    FILE_AGE=$(( $(date +%s) - $(stat -c %Y "$STATE_FILE") ))
+  fi
+
+  if [[ "$FILE_AGE" -gt "$MAX_AGE" ]]; then
+    STATE_REASON="Stale ($(( FILE_AGE / 60 ))min old, max $(( MAX_AGE / 60 ))min)"
+    return
+  fi
+
+  STATE_VALID=true
+}