coding-os 0.3.2__py3-none-any.whl

core/hooks/_helpers/narrative_signal.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Emit a one-line reason when a session shows real learning signal — rework
+churn (a file edited >=3x) or a backtrack — else nothing. Used by
+nudge-learn-narrative.sh to decide whether to nudge a lesson recording.
+
+Usage: narrative_signal.py <db_path> <session_id>
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import sys
+
+_CHURN_MIN = 3  # a file edited this many times in one session = rework churn
+
+
+def main() -> int:
+    if len(sys.argv) < 3:
+        return 0
+    db_path, session = sys.argv[1], sys.argv[2]
+    if not session:
+        return 0
+    try:
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+    except sqlite3.Error:
+        return 0
+    try:
+        # 1. rework churn — same file edited >= _CHURN_MIN times this session
+        try:
+            row = conn.execute(
+                "SELECT files_modified AS f, COUNT(*) AS c FROM observations "
+                "WHERE session_id = ? AND files_modified IS NOT NULL AND files_modified != '' "
+                "GROUP BY files_modified HAVING c >= ? ORDER BY c DESC LIMIT 1",
+                (session, _CHURN_MIN),
+            ).fetchone()
+        except sqlite3.OperationalError:
+            row = None
+        if row and row["f"]:
+            print(f"reworked {row['f'].rsplit('/', 1)[-1]} {row['c']}x")
+            return 0
+        # 2. a recorded backtrack this session
+        try:
+            r = conn.execute(
+                "SELECT COUNT(*) AS c FROM backtrack_events WHERE session_id = ?",
+                (session,),
+            ).fetchone()
+            if r and r["c"]:
+                print(f"{r['c']} backtrack(s) this session")
+                return 0
+        except sqlite3.OperationalError:
+            pass
+    finally:
+        conn.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/hooks/_helpers/observation_count.py

@@ -0,0 +1,31 @@
+"""Count observations recorded in this session.
+
+USAGE
+    python3 observation_count.py <db_path> <session_id>
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import sys
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        print(-1)
+        return 0
+    try:
+        conn = sqlite3.connect(argv[1], timeout=2)
+        cur = conn.execute(
+            "SELECT COUNT(*) FROM observations WHERE session_id = ?",
+            (argv[2],),
+        )
+        print(cur.fetchone()[0])
+        conn.close()
+    except Exception:
+        print(-1)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

core/hooks/_helpers/pre_commit_batch.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Batched pre-commit check — invoke block-* hooks for every staged file.
+
+Replaces the previous bash loop in _pre_commit_body.sh, which deadlocks
+git-commit's hook environment on ≥ ~15 staged files (bash 5.x pipe IPC
+issue). This script does the same job in a single Python process — no
+nested subshells, no per-file fork-bomb.
+
+Stdin: nothing.
+Args: <hooks_dir> <repo_root> <file1> [<file2> ...]
+Exit: 0 if every hook passes, 1 if any hook returned 2 (block).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import signal
+import sqlite3
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+# Hook → file pattern matcher. Skip files the hook wouldn't act on.
+_HOOK_PATTERNS = {
+    "block-bad-patterns.sh": (".py", ".ts", ".tsx", ".js", ".sh", ".go"),
+    "block-migration-conflict.sh": ("/migrations/",),
+    "validate-task-frontmatter.sh": ("docs/tasks/TASK-",),
+}
+
+
+def _hook_applies(hook: str, file_path: str) -> bool:
+    patterns = _HOOK_PATTERNS.get(hook, ())
+    if not patterns:
+        return True
+    return any(p in file_path or file_path.endswith(p) for p in patterns)
+
+
+# Mirror of docs-lint.sh Check 1 — the SSOT front-matter header on line 1.
+# Drives a commit-time WARN on changed docs/*.md (TASK-127); advisory only.
+_DOC_HEADER_RE = re.compile(r"^<!-- domain:[A-Z_]+ \| layer:[a-z]+ \| ssot:(true|ref|false)")
+
+
+def _make_envelope(abs_path: Path, rel_path: str) -> str:
+    try:
+        content = abs_path.read_text(errors="replace")
+    except OSError:
+        content = ""
+    return json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {
+                "file_path": rel_path,
+                "content": content,
+                "new_string": content,
+            },
+        }
+    )
+
+
+def _run_hook(hook_path: Path, envelope: str, timeout_s: int = 15) -> tuple[int, str]:
+    """Run hook with envelope on stdin. Returns (exit_code, combined_output).
+
+    Redirects the delegate's stdin/stdout/stderr to temp FILES, never OS
+    pipes. A delegate that backgrounds a grandchild (log writer, hub probe)
+    leaves that grandchild holding the inherited stdout fd; reading a pipe to
+    EOF would then block until the grandchild dies, so every staged file paid
+    the full timeout and a 15+-file commit ground on for minutes. A regular
+    file fd has no EOF reader, so wait() returns the instant the direct bash
+    child exits and the lingering grandchild is harmless. The child still gets
+    its own session (start_new_session), so a genuinely-hung DIRECT child is
+    SIGKILLed by group on timeout.
+    """
+    with tempfile.TemporaryFile() as in_f, tempfile.TemporaryFile() as out_f:
+        in_f.write(envelope.encode())
+        in_f.seek(0)
+        proc = subprocess.Popen(
+            ["bash", str(hook_path)],
+            stdin=in_f,
+            stdout=out_f,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+        try:
+            proc.wait(timeout=timeout_s)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError):
+                os.killpg(proc.pid, signal.SIGKILL)
+            with contextlib.suppress(Exception):
+                proc.wait(timeout=5)
+            raise
+        out_f.seek(0)
+        out = out_f.read().decode(errors="replace")
+    return proc.returncode, out
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 4:
+        print(
+            "usage: pre_commit_batch.py <hooks_dir> <repo_root> <file1> [<file2> ...]",
+            file=sys.stderr,
+        )
+        return 2
+
+    hooks_dir = Path(argv[1]).resolve()
+    repo_root = Path(argv[2]).resolve()
+    rel_files = argv[3:]
+
+    failed = False
+    for rel_path in rel_files:
+        abs_path = (repo_root / rel_path).resolve()
+        if not abs_path.is_file():
+            continue
+        envelope = _make_envelope(abs_path, rel_path)
+
+        # Always run block-* hooks; conditionally run validate-task-frontmatter.
+        for hook_name in ("block-bad-patterns.sh", "block-migration-conflict.sh"):
+            hook_path = hooks_dir / hook_name
+            if not hook_path.is_file():
+                continue
+            if not _hook_applies(hook_name, rel_path):
+                continue
+            try:
+                code, out = _run_hook(hook_path, envelope)
+            except subprocess.TimeoutExpired:
+                print(f"BLOCKED [{hook_name}] {rel_path}: timed out after 15s", file=sys.stderr)
+                failed = True
+                continue
+            if code == 2:
+                print(f"BLOCKED [{hook_name}] {rel_path}:", file=sys.stderr)
+                print(out.strip(), file=sys.stderr)
+                failed = True
+
+        if rel_path.startswith("docs/tasks/TASK-"):
+            hook_path = hooks_dir / "validate-task-frontmatter.sh"
+            if hook_path.is_file():
+                try:
+                    code, out = _run_hook(hook_path, envelope)
+                except subprocess.TimeoutExpired:
+                    print(f"BLOCKED [task-frontmatter] {rel_path}: timed out", file=sys.stderr)
+                    failed = True
+                    continue
+                if code == 2:
+                    print(f"BLOCKED [task-frontmatter] {rel_path}:", file=sys.stderr)
+                    print(out.strip(), file=sys.stderr)
+                    failed = True
+
+        # Doc-header contract (TASK-127): WARN — never block — when a changed
+        # docs/*.md lacks the SSOT front-matter header. Only staged docs are
+        # seen here, so this naturally scopes to new/changed docs; the CI
+        # `docs-lint --changed` strict step is the hard gate.
+        if (
+            rel_path.startswith("docs/")
+            and rel_path.endswith(".md")
+            and not rel_path.startswith("docs/tasks/")
+            and "/governance/archive/" not in rel_path
+        ):
+            try:
+                lines = abs_path.read_text(errors="replace").splitlines()
+            except OSError:
+                lines = []
+            if not (lines and _DOC_HEADER_RE.match(lines[0])):
+                print(
+                    f"WARN [doc-header] {rel_path}: missing SSOT front-matter header "
+                    "(<!-- domain:X | layer:Y | ssot:true|ref|false | updated:DATE -->) "
+                    "— see docs/governance/docs-system.md (advisory, not blocking)",
+                    file=sys.stderr,
+                )
+
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

core/hooks/_helpers/pre_commit_fake_input.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Emit a Write-tool-shaped JSON envelope for a staged file.
+
+Used by .git/hooks/pre-commit to feed core/hooks/block-*.sh scripts as
+if Claude/Codex had issued the Write. Extracted to a stand-alone module
+because bash 5.3.9 deadlocks when `python3 -c '<multiline>'` is invoked
+inside `$(...)` command substitution (see commit 8668caf for the same
+fix on intent-primer.sh).
+
+Usage: python3 pre_commit_fake_input.py <abs_path> <repo_relative_path>
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("usage: pre_commit_fake_input.py <abs_path> <file_path>", file=sys.stderr)
+        return 2
+    abs_path, file_path = sys.argv[1], sys.argv[2]
+    try:
+        with open(abs_path, errors="replace") as f:
+            content = f.read()
+    except Exception:
+        content = ""
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": file_path,
+            "content": content,
+            "new_string": content,
+        },
+    }
+    json.dump(payload, sys.stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

core/hooks/_helpers/presence_gc.py

@@ -0,0 +1,102 @@
+"""
+GC stale presence files.
+
+Reaps a file when ANY of:
+  * `ended_at` is set + age >1h (clean shutdown, normal aging)
+  * `ended_at` is null, PID is dead, mtime >1h (crashed/killed session
+    — Codex lacks Stop/SessionEnd matchers today, so otherwise
+    these accumulate forever and slow every /api/board/list scan)
+  * file is unparseable + mtime >1h (corrupt write, never recoverable)
+
+USAGE
+    python3 presence_gc.py <presence_dir> <now_epoch>
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+
+_STALE_AGE_SECS = 3600
+
+
+def _pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but is owned by another user — still alive.
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _drop(path: str) -> None:
+    """Best-effort unlink; race with another GC tick is the only realistic
+    failure and is harmless."""
+    with contextlib.suppress(OSError):
+        os.unlink(path)
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        return 0
+    d, now_s = argv[1], argv[2]
+    try:
+        now = int(now_s)
+    except ValueError:
+        return 0
+    if not os.path.isdir(d):
+        return 0
+    for name in os.listdir(d):
+        # Reap crash-orphaned atomic-write temps (x.json.tmp.PID) — both
+        # presence writers use the f"{path}.tmp.{pid}" form; the .json-only
+        # filter below would skip them forever otherwise (P31).
+        if ".tmp." in name:
+            tp = os.path.join(d, name)
+            try:
+                if now - os.path.getmtime(tp) > _STALE_AGE_SECS:
+                    _drop(tp)
+            except OSError:
+                pass
+            continue
+        if not name.endswith(".json"):
+            continue
+        p = os.path.join(d, name)
+        try:
+            mtime = os.path.getmtime(p)
+        except OSError:
+            continue
+        try:
+            with open(p, encoding="utf-8") as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            if now - mtime > _STALE_AGE_SECS:
+                _drop(p)
+            continue
+
+        ended = data.get("ended_at")
+        if isinstance(ended, int) and now - ended > _STALE_AGE_SECS:
+            _drop(p)
+            continue
+
+        # Crashed-session sweep: ended_at never set + PID dead + old.
+        if ended is None and now - mtime > _STALE_AGE_SECS:
+            pid_raw = data.get("pid") or 0
+            try:
+                pid = int(pid_raw)
+            except (TypeError, ValueError):
+                pid = 0
+            if not _pid_alive(pid):
+                _drop(p)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

core/hooks/_helpers/presence_write.py

@@ -0,0 +1,167 @@
+"""
+Presence file merge + atomic write.
+
+Called from agent-presence.sh on every tool call. Was inline as
+`python3 - <<'PY'` but bash 5.3.9 sporadically deadlocks that pattern;
+zombie bash children pile up and starve the agent runtime's auxiliary
+subprocess spawns. Separate .py file = zero heredoc surface = immune.
+
+USAGE
+    python3 presence_write.py <path> <agent> <sid> <pid> <event> <now> [model] [sdk_uuid] [transcript]
+
+EVENT ∈ {start, prompt, tool, stop, end}. Other values fall through silently.
+MODEL (optional 7th arg) — Claude Code / Codex runtime model id
+(e.g. "claude-opus-4-7"). When provided, stored as sessions/<sid>.json::model so
+the Hub UI can attribute live agents to the actual runtime model rather
+than the stale shared $COS_AGENT_DIR/.model file.
+SDK_UUID (optional 8th arg) — the host runtime's own session id (the SDK
+transcript uuid, from the hook payload's `.session_id`). Stored as
+sessions/<sid>.json::sdk_uuid so a task's coding-os agent_session can resolve
+to its chat transcript (the id bridge — TASK-184).
+TRANSCRIPT (optional 9th arg) — the runtime's live transcript path (Claude Stop
+payload `.transcript_path`). On the `stop` event the last assistant `usage`
+block is tailed and summed into sessions/<sid>.json::used_tokens so the Hub's
+live-agent context-window percent is real, not N/A (TASK-255). Privacy-safe:
+only the aggregate token count is stored, never transcript content. Window math
+lives in web/routes/presence.py (the reader); keep the summed-key list in sync.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+
+
+def _used_tokens_from_transcript(transcript_path: str) -> int | None:
+    """Tail the live transcript for the latest assistant usage, sum input
+    tokens. Cheap (last 256 KB only), fail-open. Sibling of
+    web/routes/presence.py::_latest_transcript_usage — keep the key list aligned.
+    """
+    if not transcript_path or not os.path.exists(transcript_path):
+        return None
+    try:
+        with open(transcript_path, "rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            window = min(fh.tell(), 256 * 1024)
+            fh.seek(-window, os.SEEK_END)
+            tail = fh.read().decode("utf-8", errors="ignore")
+    except OSError:
+        return None
+    for line in reversed(tail.splitlines()):
+        if '"usage"' not in line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        msg = obj.get("message") if isinstance(obj, dict) else None
+        usage = msg.get("usage") if isinstance(msg, dict) else None
+        if not isinstance(usage, dict):
+            usage = obj.get("usage") if isinstance(obj, dict) else None
+        if isinstance(usage, dict):
+            used = sum(
+                int(usage.get(k) or 0)
+                for k in (
+                    "input_tokens",
+                    "cache_read_input_tokens",
+                    "cache_creation_input_tokens",
+                )
+            )
+            return used if used > 0 else None
+    return None
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) not in (7, 8, 9, 10):
+        return 0  # fail-open: presence is UX, not correctness
+    path, agent, sid, pid_s, event, now_s = argv[1:7]
+    model = argv[7].strip() if len(argv) >= 8 else ""
+    sdk_uuid = argv[8].strip() if len(argv) >= 9 else ""
+    transcript = argv[9].strip() if len(argv) == 10 else ""
+    try:
+        pid = int(pid_s)
+        now = int(now_s)
+    except ValueError:
+        return 0
+
+    prev: dict = {}
+    parse_failed = False
+    if os.path.exists(path):
+        try:
+            with open(path, encoding="utf-8") as f:
+                prev = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            # File exists but is corrupt — keep going with empty `prev`,
+            # but emit one breadcrumb to cos hooks-log so ops can spot a
+            # disk that's silently shredding presence files.
+            prev = {}
+            parse_failed = True
+
+    new = {
+        "agent": agent,
+        "session_id": sid,
+        "pid": pid,
+        # Host of the recorded pid — the pr-mode reaper only treats a dead pid as
+        # death evidence when this matches its own host (pid_alive is host-local).
+        "host": socket.gethostname(),
+        "started_at": prev.get("started_at"),
+        "last_prompt_at": prev.get("last_prompt_at"),
+        "last_tool_at": prev.get("last_tool_at"),
+        "last_stop_at": prev.get("last_stop_at"),
+        "ended_at": prev.get("ended_at"),
+        "model": (model or prev.get("model") or None),
+        # Bridges the coding-os session id (this file's name) to the host SDK
+        # transcript uuid so a task can link to the chat that made it.
+        "sdk_uuid": (sdk_uuid or prev.get("sdk_uuid") or None),
+        # Aggregate context-window tokens stamped on stop (TASK-255).
+        "used_tokens": prev.get("used_tokens"),
+        "context_updated_at": prev.get("context_updated_at"),
+    }
+    if event == "start":
+        # Authoritative session boundary — overwrite even if a prompt
+        # event raced ahead and stamped started_at first (observed when
+        # UserPromptSubmit fires before SessionStart on Claude Code 2.x
+        # cold boot).  Without the overwrite, started_at can land AFTER
+        # last_prompt_at and the board's "alive >5min" check trips on a
+        # fresh session.
+        new["started_at"] = now
+        new["ended_at"] = None
+        new["last_stop_at"] = None
+    elif event == "prompt":
+        new["last_prompt_at"] = now
+        new["last_stop_at"] = None
+        # Only seed started_at when we genuinely don't have one yet.
+        if not isinstance(new["started_at"], int):
+            new["started_at"] = now
+    elif event == "tool":
+        new["last_tool_at"] = now
+        if not isinstance(new["started_at"], int):
+            new["started_at"] = now
+    elif event == "stop":
+        new["last_stop_at"] = now
+        used = _used_tokens_from_transcript(transcript)
+        if used is not None:
+            new["used_tokens"] = used
+            new["context_updated_at"] = now
+    elif event == "end":
+        new["ended_at"] = now
+
+    tmp = f"{path}.tmp.{os.getpid()}"
+    try:
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(new, f, separators=(",", ":"))
+        os.replace(tmp, path)
+    except OSError:
+        return 0
+    if parse_failed:
+        # One-line breadcrumb so `cos hooks-log` surfaces silent corruption.
+        # stderr only — agent-presence.sh discards stderr in the happy
+        # path, so this never reaches the user, only the ops log.
+        sys.stderr.write(f"presence_write: replaced corrupt {path}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

core/hooks/_helpers/recover_indirect.py

@@ -0,0 +1,35 @@
+"""Recover indirection-hidden git commands for block-dangerous-commands.sh.
+
+stdin: hook JSON envelope. Prints each recovered inner command (from
+eval / pipe-into-sh / here-string / xargs git) on its own line so the Bash gate
+can re-scan them with its existing force-push / reset / clean greps. Never
+raises — any error prints nothing (branch_guard is the fail-closed twin for the
+protected ops). See git_command_parse.recover_indirect_commands.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from git_command_parse import recover_indirect_commands  # noqa: E402
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+        command = (payload.get("tool_input", {}) or {}).get("command", "") or ""
+    except (json.JSONDecodeError, ValueError, AttributeError):
+        return 0
+    if not isinstance(command, str) or not command:
+        return 0
+    for line in recover_indirect_commands(command):
+        sys.stdout.write(line + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())