@matt82198/aesop 0.2.0 → 0.3.1

package/hooks/pre-push-policy.sh

@@ -252,7 +252,7 @@ check_branch_policy() {
   # Finding 3: Handle tty mode and final line without trailing newline
   if [ -t 0 ]; then
     # Running interactively on a tty; skip stdin processing with note
-    # but still check current branch as fallback
+    # but still check current branch as fallback. Note: main() blocks tty before this can matter.
     :
   else
     # Not a tty; read stdin normally
@@ -323,7 +323,9 @@ get_commit_range() {
   local saw_any_tuple=0
 
   if [ -t 0 ]; then
-    # Running interactively on a tty; no stdin to parse
+    # Running interactively on a tty; no stdin to parse → fail-closed (direct hook invocation)
+    # main() blocks tty before this is reached via the normal flow; nearly dead code but tests exercise it
+    printf 'Error: No stdin on tty; cannot parse pre-push ref tuples (interactive hook invocation)\n' >&2
     return 1
   fi
 
@@ -623,6 +625,13 @@ run_test_mode() {
   (
     export AESOP_ROOT="$tmpdir/aesop"
     mkdir -p "$AESOP_ROOT/state"
+    # SCOPED (identity-polluter class): quoted-name check runs inside an
+    # isolated fixture repo; must NEVER touch the live repo config.
+    SELFTEST_REPO="$tmpdir/selftest_identity_repo"
+    mkdir -p "$SELFTEST_REPO"
+    cd "$SELFTEST_REPO" || exit 1
+    git init -q
+    git config user.email "test@example.com"
     git config user.name 'John "Jack" Doe'
     log_block "reason_with_backslash\\test"
 
@@ -1038,15 +1047,23 @@ main() {
     exit $?
   fi
 
+  # Option B: Fail-closed TTY semantics — block interactive invocation before stdin capture.
+  # git pre-push ALWAYS pipes stdin; tty means human ran hook directly (not via git push).
+  # Refusing to skip security checks in interactive mode closes the window where empty stdin
+  # could be misinterpreted as a legitimate up-to-date push.
+  if [ -t 0 ]; then
+    printf 'Error: interactive invocation: this hook runs under git push; refusing to skip security checks (fail-closed)\n' >&2
+    log_block "interactive_invocation_blocked"
+    exit 1
+  fi
+
   # git pre-push provides ref info on stdin, and BOTH check_branch_policy and
   # check_secret_scan (via get_commit_range) need to read every ref tuple.
   # Capture the real pipe ONCE here and hand each consumer its own here-string
   # copy -- reading a pipe twice on the same fd starves the second reader
   # (once check_branch_policy drains it, get_commit_range would see nothing
   # but EOF and fail-closed on every push). A here-string preserves each
-  # function's existing tty-vs-pipe read semantics unchanged (an interactive
-  # tty yields no captured content, which both functions already treat the
-  # same way as "no ref tuples" via their existing fallback/fail-closed paths).
+  # function's existing tty-vs-pipe read semantics unchanged.
   local prepush_stdin=""
   if [ ! -t 0 ]; then
     prepush_stdin=$(cat)

package/monitor/collect-signals.mjs

@@ -613,6 +613,58 @@ function detectIsolationViolations() {
   return { violations, count: violations.length };
 }
 
+// 12) Agent stall detection
+// Calls tools/stall_check.py --json with bounded timeout; fails gracefully with NOT-AVAILABLE signal
+function checkAgentStalls() {
+  let stallCheckPy = path.join(path.dirname(MON), 'tools', 'stall_check.py');
+
+  // Fallback: look in SCRIPTS_ROOT if not found in tools
+  if (!fs.existsSync(stallCheckPy)) {
+    stallCheckPy = path.join(SCRIPTS_ROOT, 'stall_check.py');
+  }
+
+  // Fallback: look in the actual aesop source directory (for tests/CI environments)
+  if (!fs.existsSync(stallCheckPy)) {
+    const realMonitorCharter = path.join(__dirname, 'CHARTER.md');
+    if (fs.existsSync(realMonitorCharter)) {
+      stallCheckPy = path.join(__dirname, '..', 'tools', 'stall_check.py');
+    }
+  }
+
+  if (!fs.existsSync(stallCheckPy)) {
+    // stall_check.py not available; return NOT-AVAILABLE signal
+    return { available: false, count: 0, summary: 'Tool not found', stalls: [] };
+  }
+
+  try {
+    // Invoke stall_check.py with 5-second timeout (bounded, fail-open)
+    const result = spawnSync('python', [stallCheckPy, '--json'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    if (result.status !== 0 || result.error) {
+      // Tool execution failed; return NOT-AVAILABLE signal
+      return { available: false, count: 0, summary: 'Tool execution failed', stalls: [] };
+    }
+
+    const stalls = JSON.parse(result.stdout || '[]');
+    const stalledCount = stalls.filter(s => s.verdict && ['stale', 'dead'].includes(s.verdict)).length;
+
+    return {
+      available: true,
+      count: stalledCount,
+      total: stalls.length,
+      summary: stalledCount > 0 ? `${stalledCount} agent(s) stalled` : 'No stalls detected',
+      stalls: stalls,
+    };
+  } catch (e) {
+    // Parse error or other exception; return NOT-AVAILABLE signal
+    return { available: false, count: 0, summary: `Error: ${e.message}`, stalls: [] };
+  }
+}
+
 // === AUTO Actions ===
 // Log rotation: invoke rotate_logs.py if available and log needs rotation
 function performAutoLogRotation(logFiles, actionsLogPath) {
@@ -839,6 +891,7 @@ const gitState = checkGitState();
 const memory = checkMemoryFreshness();
 const logFiles = checkLogFiles(securityAlertsContent);
 const isolationViolations = detectIsolationViolations();
+const agentStalls = checkAgentStalls();
 
 // Extended signal checks (5, 6, 8, 10) — skipped if extended_signals is OFF
 const junk = extendedSignals ? detectJunkScripts() : { skipped: true };
@@ -888,6 +941,7 @@ const signals = {
   costTick,
   unreviewedPrompts,
   isolationViolations,
+  agentStalls,
 };
 
 const brief = [];
@@ -946,6 +1000,21 @@ if (isolationViolations.count === 0) {
 }
 brief.push('');
 
+brief.push('## Agent stalls');
+if (!agentStalls.available) {
+  brief.push(`NOT-AVAILABLE: ${agentStalls.summary}`);
+} else if (agentStalls.count === 0) {
+  brief.push('✓ No agent stalls detected.');
+} else {
+  brief.push(`🚨 **${agentStalls.count} agent(s) stalled** (${agentStalls.total} total scanned):`);
+  for (const stall of agentStalls.stalls) {
+    if (['stale', 'dead'].includes(stall.verdict)) {
+      brief.push(`  - ${stall.agent}: ${stall.verdict} (${stall.mtime_age_s}s old)`);
+    }
+  }
+}
+brief.push('');
+
 // Extended signals section (if disabled, just note they're off; if enabled, show details)
 if (extendedSignals) {
   brief.push('## Junk-script sprawl (temp/scratch)');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@matt82198/aesop",
-  "version": "0.2.0",
-  "description": "Multi-agent orchestration for AI coding agents, designed to survive failure \u2014 a plain-file brain, git as the only durable layer, cheap subagent fleets, and guardrails enforced in code.",
+  "version": "0.3.1",
+  "description": "Multi-agent orchestration for AI coding agents, designed to survive failure — a plain-file brain, git as the only durable layer, cheap subagent fleets, and guardrails enforced in code.",
   "bin": {
     "aesop": "bin/cli.js"
   },
@@ -70,8 +70,8 @@
   "scripts": {
     "test": "node --test --test-force-exit --test-timeout=60000 tests/*.test.mjs",
     "test:node": "node --test --test-force-exit --test-timeout=60000 tests/*.test.mjs",
-    "test:sh": "bash tests/test_pre_push_policy.sh && bash tests/test-run-watchdog.sh && bash tests/test-run-watchdog-halt.sh && bash tests/test-run-watchdog-lockguard.sh && bash tests/backup-fleet.test.sh && bash tests/test_reconstitute.sh && bash tests/test_reconstitute_fixes.sh && bash tests/test_agent_forensics.sh && bash tests/test-selfheal.sh && bash hooks/pre-push-policy.sh --test && bash tools/reconstitute.sh --test",
+    "test:sh": "bash tests/test_pre_push_policy.sh && bash tests/test-run-watchdog.sh && bash tests/test-run-watchdog-halt.sh && bash tests/test-run-watchdog-lockguard.sh && bash tests/backup-fleet.test.sh && bash tests/test_reconstitute.sh && bash tests/test_reconstitute_fixes.sh && bash tests/test_agent_forensics.sh && bash tests/test-selfheal.sh && bash hooks/pre-push-policy.sh --test",
     "test:py": "python -m unittest discover -s tests",
     "test:all": "npm run test:node && npm run test:sh && npm run test:py"
   }
-}
+}

package/state_store/__init__.py

@@ -12,7 +12,7 @@ in state_store/CLAUDE.md.
 from .api import StateAPI
 from .export import export_tracker
 from .ingest import ingest_tracker_json
-from .projections import project_tracker
+from .projections import project_tracker, project_agent_lifecycle
 from .store import EventStore, ConcurrencyConflict
 
 __all__ = [
@@ -20,6 +20,7 @@ __all__ = [
     "StateAPI",
     "ConcurrencyConflict",
     "project_tracker",
+    "project_agent_lifecycle",
     "export_tracker",
     "ingest_tracker_json",
 ]

package/state_store/projections.py

@@ -124,3 +124,66 @@ def save_snapshot(store, stream: str, event_version: int, projection: dict) -> N
         projection: the materialized state dict (e.g. full tracker projection)
     """
     store.save_snapshot(stream, event_version, projection)
+
+
+AGENT_LIFECYCLE_VERSION = 1
+
+
+def project_agent_lifecycle(events: list) -> dict:
+    """Project current agent lifecycle state from agent_* events.
+
+    Folds agent lifecycle events into a map of agent_id -> {state, transitions, last_activity}.
+
+    Event types:
+    - agent_dispatched: payload {"agent_id", "timestamp"}; marks dispatch start
+    - agent_working: payload {"agent_id", "timestamp"}; marks work in progress
+    - agent_done: payload {"agent_id", "timestamp"}; marks completion
+    - agent_stalled: payload {"agent_id", "timestamp"}; marks stall/error
+
+    Returns a dict: {"version": 1, "agents": [{"id", "state", "transitions", "last_activity"}, ...]}
+    where transitions is a list of {state, at (ISO 8601 timestamp)} in chronological order.
+    """
+    agents = {}
+
+    for ev in events:
+        etype = ev.get("type")
+        payload = ev.get("payload") or {}
+
+        if etype in ("agent_dispatched", "agent_working", "agent_done", "agent_stalled"):
+            agent_id = payload.get("agent_id")
+            timestamp = payload.get("timestamp")
+
+            if agent_id is None:
+                continue
+
+            # Initialize agent if first time seeing it
+            if agent_id not in agents:
+                agents[agent_id] = {
+                    "id": agent_id,
+                    "state": None,
+                    "transitions": [],
+                    "last_activity": None,
+                }
+
+            # Map event type to state
+            state_map = {
+                "agent_dispatched": "dispatch",
+                "agent_working": "working",
+                "agent_done": "done",
+                "agent_stalled": "stalled",
+            }
+            new_state = state_map.get(etype)
+
+            # Only append transition if state actually changed
+            if new_state and new_state != agents[agent_id]["state"]:
+                agents[agent_id]["state"] = new_state
+                if timestamp:
+                    agents[agent_id]["transitions"].append({
+                        "state": new_state,
+                        "at": timestamp,
+                    })
+                    agents[agent_id]["last_activity"] = timestamp
+
+    # Return as versioned list (ordered by agent_id for determinism)
+    agent_list = sorted(agents.values(), key=lambda a: a["id"])
+    return {"version": AGENT_LIFECYCLE_VERSION, "agents": agent_list}

package/state_store/read_api.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+state_store.read_api — Typed read-only facade for state surfaces.
+
+Consolidates read patterns for: tracker snapshot, orchestrator-status,
+heartbeat freshness, and ledger rows. This facade allows the underlying
+state representation to change (git → SQLite → Postgres) without altering
+caller code.
+
+Callers use:
+  api = ReadAPI(state_dir)
+  tracker = api.read_tracker_snapshot()
+  status = api.read_orchestrator_status()
+  is_fresh = api.is_orchestrator_status_fresh(threshold_s=300)
+  is_fresh = api.check_heartbeat_fresh(".watchdog-heartbeat", 200)
+  rows = api.read_ledger_rows()
+"""
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Ensure tools module is importable (sys.path fix for bootstrapping)
+repo_root = Path(__file__).parent.parent
+if str(repo_root) not in sys.path:
+    sys.path.insert(0, str(repo_root))
+
+from tools.common import check_heartbeat_staleness
+from tools.fleet_ledger import parse_ledger_rows as parse_ledger_rows_impl
+
+
+class ReadAPI:
+    """Read-only facade over state surfaces (tracker, orchestrator-status, heartbeats, ledger).
+
+    Designed to be swappable: backends can change (git → SQLite → Postgres) without
+    altering call sites. Current implementation reads from filesystem; future may
+    read from SQLite projections or API.
+    """
+
+    def __init__(self, state_dir):
+        """Initialize the read API with a state directory.
+
+        Args:
+            state_dir: Path to the state directory (e.g., "state" or "/absolute/path/state")
+        """
+        self.state_dir = Path(state_dir)
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+    def read_tracker_snapshot(self):
+        """Read the current tracker snapshot.
+
+        Returns the tracker.json file, or an empty dict if missing/unreadable.
+        In the future, this may read from the SQLite projection instead.
+
+        Returns:
+            dict: Tracker snapshot (items, metadata, etc.) or {} if unavailable.
+        """
+        tracker_file = self.state_dir / "tracker.json"
+        if not tracker_file.exists():
+            return {}
+
+        try:
+            content = tracker_file.read_text(encoding="utf-8")
+            return json.loads(content)
+        except Exception:
+            # Malformed JSON or read error: return empty dict (fail-open)
+            return {}
+
+    def read_orchestrator_status(self):
+        """Read orchestrator-status.json if present.
+
+        Returns:
+            dict with "updated_at" (required) and optional "phase", "activity" fields,
+            or None if file missing/unreadable.
+        """
+        status_file = self.state_dir / "orchestrator-status.json"
+        if not status_file.exists():
+            return None
+
+        try:
+            content = status_file.read_text(encoding="utf-8")
+            data = json.loads(content)
+            # Only require updated_at field for freshness checks;
+            # phase is optional (may not be set when status.json created before phase exists)
+            # Don't validate here—let callers decide what fields are required for their use case
+            return data
+        except Exception:
+            return None
+
+    def is_orchestrator_status_fresh(self, threshold_s=300):
+        """Check if orchestrator-status.json exists and is fresh.
+
+        Reads updated_at timestamp and compares to current time.
+        Returns False if file missing, unparseable, or stale.
+
+        Args:
+            threshold_s: Staleness threshold in seconds (default: 300s)
+
+        Returns:
+            bool: True if file is fresh, False if stale/missing/malformed.
+        """
+        status = self.read_orchestrator_status()
+        if status is None:
+            return False
+
+        try:
+            updated_at_str = status.get("updated_at")
+            if not updated_at_str:
+                return False
+
+            # Parse ISO format timestamp (handle both "Z" and "+00:00")
+            normalized = updated_at_str.replace("Z", "+00:00")
+            updated_at = datetime.fromisoformat(normalized)
+
+            now = datetime.now(timezone.utc)
+            age = (now - updated_at).total_seconds()
+
+            # Treat future-dated timestamps as stale (fail-closed)
+            if age < -120:  # More than 2min in future = clock skew, treat as stale
+                return False
+
+            # Clamp small negative ages to 0
+            age = max(0, age)
+
+            return age < threshold_s
+        except Exception:
+            return False
+
+    def check_heartbeat_fresh(self, heartbeat_filename, threshold_s=200):
+        """Check if a heartbeat file is fresh.
+
+        Delegates to tools.common.check_heartbeat_staleness (single source of truth).
+
+        Args:
+            heartbeat_filename: Filename in state_dir (e.g., ".watchdog-heartbeat")
+            threshold_s: Staleness threshold in seconds (default: 200s)
+
+        Returns:
+            bool: True if file exists and is fresh, False otherwise.
+        """
+        hb_file = self.state_dir / heartbeat_filename
+        # Use the shared implementation from common.py; invert staleness to freshness
+        is_stale, _, _ = check_heartbeat_staleness(hb_file, threshold_s)
+        return not is_stale
+
+    def read_ledger_rows(self):
+        """Read OUTCOMES-LEDGER.md and parse rows.
+
+        Delegates to tools.fleet_ledger.parse_ledger_rows() (single source of truth).
+        Returns empty list if file missing or unparseable.
+
+        Returns:
+            list: List of row dicts parsed from the ledger table, or [].
+        """
+        # Use the shared implementation from fleet_ledger.py
+        return parse_ledger_rows_impl()