coding-os 0.3.2__py3-none-any.whl

core/hooks/auto-graph-reconcile-shell.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# auto-graph-reconcile-shell.sh
+# PostToolUse Bash — single ordered reconciler that replaces the pair
+# auto-reindex-shell-ops.sh + auto-prune-deleted-files.sh. Both used to
+# fire on the same rm/mv and hit the graph DB in two unordered background
+# jobs (the N10 race). This walks the touched paths ONCE and, in one job,
+# prunes the gone paths FIRST then reindexes the present ones — serialized,
+# never interleaved.
+#
+# Fire-and-forget, debounced, fail-open: detection is regex-only and all
+# heavy work runs detached so the Bash tool returns immediately.
+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 4)"
+
+# Fast-path: only file-mutating verbs matter — bail before any jq spawn.
+case "$INPUT" in
+  *mv*|*cp*|*rm*|*git*|*find*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL="$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")"
+[[ "$TOOL" != "Bash" ]] && exit 0
+
+# Only reconcile on success — a failed rm/mv left the tree unchanged.
+EXIT_CODE="$(printf '%s' "$INPUT" | jq -r '.tool_response.exit_code // .tool_response.exitCode // 0' 2>/dev/null || echo 0)"
+[[ "$EXIT_CODE" != "0" ]] && exit 0
+
+CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")"
+[[ -z "$CMD" ]] && exit 0
+
+# Gate: a file-mutating verb AND a source-touching path.
+if ! printf '%s' "$CMD" | grep -qE '(\bmv\b|\bcp\b|\brm\b|git[[:space:]]+(mv|rm|checkout|restore|reset|stash)|find[[:space:]].*-delete)'; then
+  exit 0
+fi
+if ! printf '%s' "$CMD" | grep -qE '\.(py|ts|tsx|md|sh|yaml|yml|go|rs|java|toml|json)\b|src/|core/|cli/|adapters/|templates/|docs/|tests/'; then
+  exit 0
+fi
+
+cos_log_hook auto-graph-reconcile-shell enter || true
+STATE_DIR="${COS_STATE_DIR:-${COS_AGENT_DIR:-.coding-os}}"
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}"
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+ERR_LOG="${STATE_DIR}/.graph-reconcile.log"
+
+PRUNE_SCRIPT=""
+for candidate in \
+  "${PROJECT_ROOT}/src/scripts/prune_deleted_path.py" \
+  "${PROJECT_ROOT}/scripts/prune_deleted_path.py" \
+  "$(dirname "$0")/../../scripts/prune_deleted_path.py"; do
+  [[ -f "$candidate" ]] && { PRUNE_SCRIPT="$candidate"; break; }
+done
+
+EXPLICIT_PATHS="$(printf '%s' "$CMD" | grep -oE '[A-Za-z0-9_./-]+\.(py|ts|tsx|md|sh|yaml|yml|go|rs|java|toml|json)\b' | sort -u || true)"
+BULK_RE='git[[:space:]]+(checkout|restore|reset|stash)([[:space:]]+\.|[[:space:]]+--[[:space:]]+\.|[[:space:]]*$)|find[[:space:]].*-delete|rm[[:space:]]+-rf'
+
+# Bulk op (branch switch / wholesale delete) or no extractable path →
+# one debounced full reindex; the full walk both prunes and re-adds.
+if printf '%s' "$CMD" | grep -qE "$BULK_RE" || [[ -z "$EXPLICIT_PATHS" ]]; then
+  SENTINEL="${STATE_DIR}/.reindex-scheduled"
+  if [[ -f "$SENTINEL" ]]; then
+    AGE=$(($(date +%s) - $(stat -c %Y "$SENTINEL" 2>/dev/null || stat -f %m "$SENTINEL" 2>/dev/null || echo 0)))
+    if (( AGE < 30 )); then
+      cos_log_hook auto-graph-reconcile-shell debounced "age=${AGE}s" || true
+      exit 0
+    fi
+  fi
+  date +%s > "$SENTINEL" 2>/dev/null || true
+  (
+    (
+      cos graph-reindex --force >>"$ERR_LOG" 2>&1
+      rm -f "$SENTINEL" 2>/dev/null || true
+    ) &
+  ) &
+  cos_log_hook auto-graph-reconcile-shell full "cmd_head=$(printf '%.80s' "$CMD")" || true
+  cos_record_activity graph "full reindex" 2>/dev/null || true
+  printf '%s' '{"systemMessage":"[graph] full reindex"}'
+  exit 0
+fi
+
+# Targeted: ONE ordered background job — prune the gone paths FIRST, then
+# reindex the present ones. Single job so the graph DB never sees a prune
+# and a reindex of the same file interleaved (the N10 race the two old
+# hooks created by firing in parallel).
+(
+  (
+    GONE=()
+    PRESENT=()
+    while IFS= read -r path; do
+      [[ -n "$path" ]] || continue
+      if [[ -f "$path" ]]; then
+        PRESENT+=( "$path" )
+      else
+        GONE+=( "$path" )
+      fi
+    done < <(printf '%s\n' "$EXPLICIT_PATHS")
+    if [[ ${#GONE[@]} -gt 0 && -n "$PRUNE_SCRIPT" ]]; then
+      "${COS_PYTHON:-python3}" "$PRUNE_SCRIPT" "${GONE[@]}" --quiet >>"$ERR_LOG" 2>&1
+    fi
+    for path in "${PRESENT[@]}"; do
+      "${COS_PYTHON:-python3}" -c "
+import sys
+sys.path.insert(0, 'src/core')
+sys.path.insert(0, 'src/core/thinking_os')
+from graph_os.tools.reindex_dispatch import dispatch
+dispatch('${path}', project_root='${PROJECT_ROOT}', force=True)
+" >>"$ERR_LOG" 2>&1
+    done
+  ) &
+) &
+
+_N=$(printf '%s' "$EXPLICIT_PATHS" | grep -c . || true)
+cos_log_hook auto-graph-reconcile-shell reconcile "${_N} paths" || true
+cos_record_activity graph "reconcile ${_N} paths" 2>/dev/null || true
+printf '%s' "{\"systemMessage\":\"[graph] reconcile ${_N} paths\"}"
+exit 0

core/hooks/auto-regen-doc-index.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# PostToolUse hook: after Write/Edit on a docs/**/*.md file,
+# regenerate the affected directory's 00-index.md from frontmatter.
+#
+# Design:
+#   - Fire-and-forget: regen is a single-dir Python invocation; the
+#     worker forks to background and the hook returns immediately.
+#   - Scoped: only fires for paths matching `docs/**/*.md`. Reading,
+#     skipping, and dispatching all happen in <50 ms.
+#   - Debounced: 5-second per-directory lockfile prevents N parallel
+#     regens when an agent edits multiple files in quick succession.
+#   - Fail-open: missing python or missing script = silent skip into
+#     $COS_STATE_DIR/.regen-doc-index-errors.log (bounded, ~200 lines).
+#   - Adapter-agnostic: reads COS_STATE_DIR / COS_PROJECT_ROOT from
+#     cos-env.sh; never hardcodes `.claude/` (Rule 1).
+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)"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Scope: only docs/*.md and only inside the project's docs tree.
+case "$FILE_PATH" in
+  *.md) ;;
+  *) exit 0 ;;
+esac
+
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}"
+DOCS_PREFIX="${PROJECT_ROOT%/}/docs/"
+case "$FILE_PATH" in
+  "$DOCS_PREFIX"*) ;;
+  docs/*) ;;  # relative path form
+  *) exit 0 ;;
+esac
+
+cos_log_hook auto-regen-doc-index fire "file=${FILE_PATH}"
+
+# ── Resolve the target dir + the regen script ────────────────────────
+TARGET_DIR=$(dirname "$FILE_PATH")
+SCRIPT_PATH=""
+# Resolve this hook through its (possibly symlinked) install path so a
+# consumer's .claude/hooks/auto-regen-doc-index.sh → meta-repo symlink lands
+# on the meta-repo's own src/scripts/regen_doc_index.py. Platform code runs
+# from the platform; it is never copied into every consumer (the
+# script was unshipped, so the consumer-root candidates below never matched).
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HOOK_REAL_DIR="$(cd -P "$(dirname "$_src")" && pwd 2>/dev/null)" || HOOK_REAL_DIR=""
+# Primary: meta-repo script via the resolved hook. Fallbacks: a consumer that
+# vendored the script under its own root (src/scripts or scripts).
+for candidate in \
+  "${HOOK_REAL_DIR:+${HOOK_REAL_DIR}/../../scripts/regen_doc_index.py}" \
+  "${PROJECT_ROOT}/src/scripts/regen_doc_index.py" \
+  "${PROJECT_ROOT}/scripts/regen_doc_index.py"; do
+  if [[ -n "$candidate" && -f "$candidate" ]]; then
+    SCRIPT_PATH="$candidate"
+    break
+  fi
+done
+
+if [[ -z "$SCRIPT_PATH" ]]; then
+  cos_log_hook auto-regen-doc-index skip "reason=script_missing"
+  exit 0
+fi
+
+# ── Debounce ─────────────────────────────────────────────────────────
+# 5-second window per target dir. Suppresses regen storms when an agent
+# saves multiple files in the same dir in quick succession.
+_DEBOUNCE_TTL=5
+_STATE_BASE="${COS_STATE_DIR:-${PROJECT_ROOT}/.coding-os}"
+_SAFE_DIR=$(printf '%s' "$TARGET_DIR" | tr '/' '_' | tr ' ' '_')
+_DEBOUNCE_FILE="${_STATE_BASE}/.regen-doc-index-debounce-${_SAFE_DIR}"
+_NOW=$(date +%s)
+if [[ -f "$_DEBOUNCE_FILE" ]]; then
+  _LAST=$(cat "$_DEBOUNCE_FILE" 2>/dev/null || echo 0)
+  if (( _NOW - _LAST < _DEBOUNCE_TTL )); then
+    cos_log_hook auto-regen-doc-index skip "reason=debounced dir=${TARGET_DIR}"
+    exit 0
+  fi
+fi
+mkdir -p "$(dirname "$_DEBOUNCE_FILE")"
+echo "$_NOW" > "$_DEBOUNCE_FILE"
+
+ERR_LOG="${_STATE_BASE}/.regen-doc-index-errors.log"
+mkdir -p "$(dirname "$ERR_LOG")"
+
+# ── Fire-and-forget regen in background ──────────────────────────────
+# Failures land in $ERR_LOG (bounded 200 lines). `cos hooks-log --follow`
+# surfaces dispatched / skip lines; ERR_LOG is the place to look when the
+# index stops refreshing. (Per-dir fail-counter removed — over-engineered
+# vs. just tailing the log.)
+(
+  "${COS_PYTHON:-python3}" "$SCRIPT_PATH" "$TARGET_DIR" >/dev/null 2>>"$ERR_LOG" &
+) &
+
+# Bound the error log to the last 200 lines so it can't balloon.
+if [[ -f "$ERR_LOG" ]]; then
+  LINES=$(wc -l < "$ERR_LOG" 2>/dev/null || echo 0)
+  if (( LINES > 200 )); then
+    tail -n 200 "$ERR_LOG" > "${ERR_LOG}.tmp" && mv "${ERR_LOG}.tmp" "$ERR_LOG"
+  fi
+fi
+
+cos_log_hook auto-regen-doc-index dispatched "dir=${TARGET_DIR}"
+exit 0

core/hooks/auto-reindex-docs.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# PostToolUse hook: after Write/Edit, re-index the
+# touched file into both the docs RAG layer AND the graph_os structural
+# layer so cos_doc_search and cos_graph_* stay fresh without manual
+# `make docs-index` / `cos graph-reindex` runs.
+#
+# Design:
+#   - Fire-and-forget: worker forks to background; Write/Edit returns
+#     immediately. Worst-case freshness lag = one dispatcher cycle.
+#   - Dispatcher is Python (`graph_os.tools.reindex_dispatch`) — Python
+#     owns the scope check + per-suffix extractor chain; shell just
+#     routes paths.
+#   - Scoped: docs layer handles only .md; graph layer handles every
+#     suffix the extractor map knows
+#     (.py/.ts/.tsx/.js/.jsx/.mjs/.cjs/.sh/.yaml/.yml/.md/.go/.json/.toml).
+#   - Fail-open: any missing dep is a silent skip. Errors land in
+#     $COS_STATE_DIR/.reindex-errors.log (bounded, ~200 lines).
+#   - Adapter-agnostic: reads COS_STATE_DIR / COS_DB_PATH from cos-env.sh.
+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)"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  *.md|*.py|*.ts|*.tsx|*.sh|*.yaml|*.yml|*.go|*.json|*.toml|*.js|*.jsx|*.mjs|*.cjs) ;;
+  *) exit 0 ;;
+esac
+
+cos_log_hook auto-reindex-docs fire "file=${FILE_PATH}"
+
+# ── Debounce (D3) ────────────────────────────────────────────────────
+# Coalesce rapid successive writes on the same path within a 3-second
+# window to prevent N parallel background workers when an agent edits
+# a file in quick succession. Strategy: write a per-path lockfile with
+# the current timestamp; skip if the file was touched in the last 3 s.
+_DEBOUNCE_TTL=3
+_STATE_BASE="${COS_STATE_DIR:-${PWD}/.coding-os}"
+_SAFE_PATH=$(printf '%s' "$FILE_PATH" | tr '/' '_' | tr ' ' '_')
+_DEBOUNCE_FILE="${_STATE_BASE}/.reindex-debounce-${_SAFE_PATH}"
+_NOW=$(date +%s)
+if [[ -f "$_DEBOUNCE_FILE" ]]; then
+  _LAST=$(cat "$_DEBOUNCE_FILE" 2>/dev/null || echo 0)
+  if (( _NOW - _LAST < _DEBOUNCE_TTL )); then
+    cos_log_hook auto-reindex-docs skip "reason=debounced file=${FILE_PATH##*/}"
+    exit 0
+  fi
+fi
+mkdir -p "$(dirname "$_DEBOUNCE_FILE")"
+echo "$_NOW" > "$_DEBOUNCE_FILE"
+
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}"
+CORE_DIR=""
+for candidate in \
+  "${COS_CORE_DIR:-}" \
+  "$(dirname "$0")/.." \
+  "${PROJECT_ROOT}/src/core" \
+  "${PROJECT_ROOT}/core"; do
+  if [[ -n "$candidate" && -d "${candidate}/graph_os" ]]; then
+    CORE_DIR="$(cd "$candidate" && pwd)"
+    break
+  fi
+done
+
+if [[ -z "$CORE_DIR" ]]; then
+  cos_log_hook auto-reindex-docs skip "reason=no_core_dir"
+  exit 0
+fi
+
+ERR_LOG="${COS_STATE_DIR:-${PROJECT_ROOT}/.coding-os}/.reindex-errors.log"
+mkdir -p "$(dirname "$ERR_LOG")"
+
+# Fire the re-index in background via the unified Python dispatcher.
+# Stdout is muted (hook must stay quiet); stderr → error log.
+(
+  "${COS_PYTHON:-python3}" -c "
+import os, sys
+sys.path.insert(0, '${CORE_DIR}')
+sys.path.insert(0, '${CORE_DIR}/thinking_os')
+try:
+    from graph_os.tools.reindex_dispatch import dispatch
+    report = dispatch(
+        '${FILE_PATH}',
+        project_root='${PROJECT_ROOT}',
+        db_path=os.environ.get('COS_DB_PATH'),
+    )
+    # Silent on no-op dispatches (skipped or fully cached). 'skipped'
+    # covers out-of-repo + unsupported suffix; cache=hit means every
+    # layer short-circuited via the file_index_state hash so there is
+    # nothing to report. Without this filter every Edit emits a stderr
+    # line into the unified tail even when the graph never changed.
+    # NOTE: comments here are inside a bash double-quoted python -c
+    # argument, so backticks would trigger command substitution. Plain
+    # ASCII only.
+    if report.get('status') != 'skipped' and report.get('cache') != 'hit':
+        print(f\"[auto-reindex] {report['status']}: {report['path']} \"
+              f\"({report['duration_ms']}ms, layers={list(report['layers'].keys())})\",
+              file=sys.stderr)
+except Exception as exc:
+    print(f'[auto-reindex] ERROR: {type(exc).__name__}: {exc}', file=sys.stderr)
+" 2>>"$ERR_LOG" &
+) &
+
+if [[ -f "$ERR_LOG" ]]; then
+  LINES=$(wc -l < "$ERR_LOG" 2>/dev/null || echo 0)
+  if (( LINES > 200 )); then
+    tail -n 200 "$ERR_LOG" > "${ERR_LOG}.tmp" && mv "${ERR_LOG}.tmp" "$ERR_LOG"
+  fi
+fi
+
+cos_log_hook auto-reindex-docs dispatched "file=${FILE_PATH}"
+
+# Visible signal — record activity (rendered by next pulse) + emit
+# systemMessage. python3 json.dumps escapes filename specials safely.
+_FN="${FILE_PATH##*/}"
+cos_record_activity graph "reindex ${_FN}" 2>/dev/null || true
+printf '{"systemMessage":%s}' "$(printf '[graph] reindex %s' "$_FN" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+
+exit 0

core/hooks/auto-task-sync.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# PostToolUse: Write/Edit on docs/tasks/*.md
+# Re-syncs the single file into the DB cache so the board is fresh
+# within one hook latency (<200ms per §8.2).
+#
+# Fail-soft: background subprocess; never blocks the tool response.
+
+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-task-sync" "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 "")"
+
+if [[ "$file_path" != *"docs/tasks/"*.md ]]; then
+    exit 0
+fi
+
+# Background, fire-and-forget. bash 5.3.9 deadlocks `python3 - <<HEREDOC`
+# — extracted to _helpers/task_sync.py.
+_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/task_sync.py"
+if [[ -f "$HELPER" ]]; then
+  (
+    COS_PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}" \
+      python3 "$HELPER" "$file_path" >/dev/null 2>&1
+  ) &
+fi
+
+cos_log_hook "auto-task-sync" "spawned" 2>/dev/null || true
+
+# Visible signal — record activity + emit systemMessage. task_id is
+# regex-restricted to `TASK-([A-Z][A-Z0-9]*-)?[0-9]+` so JSON interpolation is safe.
+task_id="$(basename "$file_path" .md | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || true)"
+if [[ -n "$task_id" ]]; then
+  cos_record_activity task "${task_id}" 2>/dev/null || true
+  printf '%s' "{\"systemMessage\":\"[task] ${task_id} synced\"}"
+fi
+
+exit 0

core/hooks/auto-trace-rotate.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Stop hook — rotate trace JSONL files (age-based) and unbounded logs
+# (size-based copytruncate).
+#
+# Trace targets: $COS_AGENT_DIR/traces/*.jsonl
+#   - gzip files older than COS_TRACE_GZIP_AGE_DAYS (default 3)
+#   - delete (gz or jsonl) older than COS_TRACE_DELETE_AGE_DAYS (default 30)
+#
+# Log targets: $COS_STATE_DIR/.{mcp,cos,hooks}.log + .cos.log.jsonl
+#   - when file >= COS_LOG_ROTATE_SIZE_BYTES (default 5_242_880 = 5MB):
+#     gzip-copy → archive .<name>.<ts>.gz, then truncate original in-place
+#     (server fds keep writing; classic logrotate copytruncate)
+#   - keep most-recent COS_LOG_ROTATE_KEEP archives (default 3), delete older
+#
+# Fire-and-forget; bounded; never blocks the caller.
+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
+
+GZIP_AGE_DAYS="${COS_TRACE_GZIP_AGE_DAYS:-3}"
+DELETE_AGE_DAYS="${COS_TRACE_DELETE_AGE_DAYS:-30}"
+LOG_ROTATE_SIZE_BYTES="${COS_LOG_ROTATE_SIZE_BYTES:-5242880}"
+LOG_ROTATE_KEEP="${COS_LOG_ROTATE_KEEP:-3}"
+
+GZIPPED=0
+DELETED=0
+LOGS_ROTATED=0
+
+# ── traces (age-based) ─────────────────────────────────────────────
+TRACE_DIR="${COS_AGENT_DIR:-}/traces"
+if [[ -n "${COS_AGENT_DIR:-}" ]] && [[ -d "$TRACE_DIR" ]]; then
+  case "$TRACE_DIR" in
+    *"/.coding-os/"*"/traces")
+      while IFS= read -r -d '' f; do
+        if gzip -q -- "$f" 2>/dev/null; then
+          GZIPPED=$((GZIPPED + 1))
+        fi
+      done < <(find "$TRACE_DIR" -maxdepth 1 -type f -name '*.jsonl' \
+                    -mtime "+$GZIP_AGE_DAYS" -print0 2>/dev/null)
+
+      while IFS= read -r -d '' f; do
+        if rm -f -- "$f" 2>/dev/null; then
+          DELETED=$((DELETED + 1))
+        fi
+      done < <(find "$TRACE_DIR" -maxdepth 1 -type f \
+                    \( -name '*.jsonl' -o -name '*.jsonl.gz' \) \
+                    -mtime "+$DELETE_AGE_DAYS" -print0 2>/dev/null)
+      ;;
+  esac
+fi
+
+# ── logs (size-based copytruncate) ─────────────────────────────────
+STATE_DIR="${COS_STATE_DIR:-}"
+if [[ -n "$STATE_DIR" ]] && [[ -d "$STATE_DIR" ]]; then
+  case "$STATE_DIR" in
+    *"/.coding-os")
+      ts=$(date -u +%Y%m%dT%H%M%SZ)
+      for name in .mcp.log .cos.log .cos.log.jsonl .hooks.log; do
+        f="$STATE_DIR/$name"
+        [[ -f "$f" ]] || continue
+        size=$(stat -f%z "$f" 2>/dev/null || stat -c%s "$f" 2>/dev/null || echo 0)
+        if [[ "$size" -ge "$LOG_ROTATE_SIZE_BYTES" ]]; then
+          archive="$STATE_DIR/${name}.${ts}.gz"
+          # Copytruncate race: bytes written between `gzip -c` and `: > "$f"`
+          # appear in both archive and origin (or are lost if origin truncates
+          # mid-write). Acceptable here — runs at Stop after the agent turn,
+          # MCP server quiescent. Move to logrotate(8)-style rename + SIGHUP
+          # if a writer ever logs faster than the gzip stream can drain.
+          if gzip -c -- "$f" > "$archive" 2>/dev/null; then
+            : > "$f"
+            LOGS_ROTATED=$((LOGS_ROTATED + 1))
+          fi
+        fi
+        # Trim old archives — keep newest $LOG_ROTATE_KEEP, delete rest.
+        old=$(ls -1t "$STATE_DIR/${name}".*.gz 2>/dev/null | tail -n +$((LOG_ROTATE_KEEP + 1)) || true)
+        if [[ -n "$old" ]]; then
+          echo "$old" | xargs rm -f -- 2>/dev/null || true
+        fi
+      done
+      ;;
+  esac
+fi
+
+cos_log_hook auto-trace-rotate fire \
+  "gzipped=${GZIPPED} deleted=${DELETED} logs_rotated=${LOGS_ROTATED}"
+
+exit 0