feat(livingcode): collect signal types + stabilize state-report ordering

Extends the livingcode shape with a fifth auto-collected vocabulary:
the signal `type` strings that flow through fireWebhooksForOrg and
deliverNativeNotifications.

Detection runs in two modes, applied per file:

  1. Files that call the delivery pipeline directly (cost-alerts.js,
     health-change-alerts.js) — every `type:` literal is kept.
  2. Other files contribute only `type:` literals paired with a
     red/amber `severity:` in close proximity. This catches
     signal-builder modules (signals.js returning arrays the cron
     later delivers) while rejecting demoFixtures.js-style files
     that contain both real signal fixtures AND unrelated
     `type:` fields — previously leaked `concept` into the skill.

Skill now carries a "Signal Types" section listing all 9 live
types (autonomy_spike, branch_stale, cost_exceeded,
green_insufficient, integration_health_changed, integration_mismatch,
mcp_degraded, stale_action, test).

Also fixes a pre-existing Windows-NTFS flake in
livingcode/state.py::read_latest_state_report. The function sorted
by `st_mtime`, which on NTFS has ~15ms resolution — back-to-back
writes tied and the "latest" report was non-deterministic.
Filenames now carry a monotonic process-local counter and the read
sorts lexically, so insertion order wins regardless of filesystem
timestamp granularity. Full livingcode test suite now green for
the first time (172 passing).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ucsandman

app/lib/doctor/generated/last-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "sha1:0a45543dd6eea2cca1b05176f7075258617c9ed5",
+  "timestamp": "sha1:a1474e482800bd24d85993b7e4ff9d69865042f4",
   "routes": [
     {
       "path": "/api/_archive/agent-schedules",
@@ -4258,5 +4258,16 @@
         "SLACK_WEBHOOK_URL"
       ]
     }
+  ],
+  "signal_types": [
+    "autonomy_spike",
+    "branch_stale",
+    "cost_exceeded",
+    "green_insufficient",
+    "integration_health_changed",
+    "integration_mismatch",
+    "mcp_degraded",
+    "stale_action",
+    "test"
   ]
 }

app/lib/doctor/generated/shape.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "sha1:0a45543dd6eea2cca1b05176f7075258617c9ed5",
+  "timestamp": "sha1:a1474e482800bd24d85993b7e4ff9d69865042f4",
   "routes": [
     {
       "path": "/api/_archive/agent-schedules",
@@ -4258,5 +4258,16 @@
         "SLACK_WEBHOOK_URL"
       ]
     }
+  ],
+  "signal_types": [
+    "autonomy_spike",
+    "branch_stale",
+    "cost_exceeded",
+    "green_insufficient",
+    "integration_health_changed",
+    "integration_mismatch",
+    "mcp_degraded",
+    "stale_action",
+    "test"
   ]
 }

livingcode/collectors/signals.py

@@ -0,0 +1,94 @@
+"""Signal-type collector.
+
+Signals are the vocabulary webhooks subscribe to and native adapters render.
+Unlike EVENTS and VALID_SETTING_KEYS (which live in one file each), signal
+types are authored inline wherever something decides to alert — `signals.js`,
+`cost-alerts.js`, `health-change-alerts.js`, and future alerters.
+
+Rather than ask authors to register into a central list, we detect signal-
+emitting files by the call sites they use (`fireWebhooksForOrg(` or
+`deliverNativeNotifications(`) and harvest every `type: '<snake_case>'`
+literal from those files. That keeps the collector drift-proof: any new
+alerter wired through the canonical delivery pipeline is discovered
+automatically, while unrelated `type:` strings in other files are ignored.
+"""
+import os
+import re
+
+from livingcode.types import SettingKeyInfo  # noqa: F401 (kept for parity)
+
+SCAN_ROOTS = ["app/lib", "app/api"]
+SKIP_DIRS = {"node_modules", ".next", "__pycache__", "_archive"}
+SCAN_EXTENSIONS = {".js", ".mjs", ".ts", ".tsx"}
+
+_DELIVERY_CALL_RE = re.compile(
+    r"\b(?:fireWebhooksForOrg|deliverNativeNotifications)\s*\("
+)
+_TYPE_RE = re.compile(r"type:\s*['\"]([a-z][a-z0-9_]*)['\"]")
+# Signal-shape probe: type + severity ('red' or 'amber') within a small window.
+# `severity: 'red'|'amber'` is unique to signal objects in this codebase,
+# which lets us detect files that BUILD signals without delivering them
+# (e.g. signals.js, which returns signals for the cron to later deliver).
+_SIGNAL_SHAPE_WINDOW = 200  # characters — roughly 6-8 lines
+_SEVERITY_LITERAL_RE = re.compile(r"severity:\s*['\"](?:red|amber)['\"]")
+
+
+def _signal_types_in_file(content: str, scrape_all: bool) -> set[str]:
+    """Extract signal `type:` names from one file.
+
+    If `scrape_all` is True (the file calls the delivery pipeline directly),
+    every `type:` literal is treated as a signal — the delivery call site
+    is strong evidence that this file authors signals.
+
+    Otherwise, only `type:` literals that have a red/amber `severity:`
+    literal within a short proximity window are kept. This is the
+    signal-shape heuristic: it catches authored-elsewhere signals
+    (e.g. signals.js returning arrays the cron later delivers) while
+    rejecting unrelated `type:` literals that happen to share a file
+    with fixture/demo signals.
+    """
+    out: set[str] = set()
+    for m in _TYPE_RE.finditer(content):
+        if scrape_all:
+            out.add(m.group(1))
+            continue
+        start = max(0, m.start() - _SIGNAL_SHAPE_WINDOW)
+        end = min(len(content), m.end() + _SIGNAL_SHAPE_WINDOW)
+        if _SEVERITY_LITERAL_RE.search(content[start:end]):
+            out.add(m.group(1))
+    return out
+
+
+def collect_signal_types(repo_path: str) -> list[str]:
+    """Return sorted unique signal `type` strings.
+
+    Two detection modes applied per file:
+      1. Files calling `fireWebhooksForOrg` / `deliverNativeNotifications`
+         are assumed to be signal call sites — every `type:` is kept.
+      2. Other files contribute only `type:` literals that pair with a
+         red/amber `severity:` in close proximity. Catches signal-builder
+         modules (signals.js) without pulling in demo fixtures or unrelated
+         `type:` fields elsewhere in the same file.
+    """
+    types: set[str] = set()
+
+    for rel_root in SCAN_ROOTS:
+        root = os.path.join(repo_path, rel_root)
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+            for fname in filenames:
+                ext = os.path.splitext(fname)[1]
+                if ext not in SCAN_EXTENSIONS:
+                    continue
+                fpath = os.path.join(dirpath, fname)
+                try:
+                    with open(fpath, encoding="utf-8", errors="ignore") as f:
+                        content = f.read()
+                except OSError:
+                    continue
+                delivers = bool(_DELIVERY_CALL_RE.search(content))
+                types |= _signal_types_in_file(content, scrape_all=delivers)
+
+    return sorted(types)

livingcode/emitters/skill.py

@@ -155,6 +155,20 @@ def emit_skill(shape: ShapeModel) -> str:
             lines.append(f"| `{e.constant}` | `{e.event}` |")
         lines.append("")
 
+    # Signal vocabulary — types emitted by alerters, consumed by webhooks + adapters
+    if getattr(shape, "signal_types", []):
+        lines += ["## Signal Types", ""]
+        lines += [
+            "These are the `type` strings emitted through `fireWebhooksForOrg` "
+            "and `deliverNativeNotifications`. Webhooks can subscribe to any "
+            "subset by putting the type in their `events: [...]` array (or "
+            "use `['all']` for everything).",
+            "",
+        ]
+        for t in shape.signal_types:
+            lines.append(f"- `{t}`")
+        lines.append("")
+
     # Native notification adapters
     if getattr(shape, "adapters", []):
         lines += ["## Native Notification Adapters", ""]

livingcode/shape.py

@@ -14,6 +14,7 @@
 from livingcode.collectors.routes import collect_routes
 from livingcode.collectors.schema import collect_schema
 from livingcode.collectors.settings import collect_setting_keys
+from livingcode.collectors.signals import collect_signal_types
 from livingcode.types import ShapeModel
 
 
@@ -27,4 +28,5 @@ def build_shape(repo_path: str) -> ShapeModel:
         setting_keys=collect_setting_keys(repo_path),
         events=collect_events(repo_path),
         adapters=collect_adapters(repo_path),
+        signal_types=collect_signal_types(repo_path),
     )

livingcode/state.py

@@ -1,5 +1,6 @@
 """Filesystem operations for .organism/ state directory."""
 import json
+import threading
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -8,6 +9,16 @@
 ORGANISM_DIR = ".organism"
 SUBDIRS = ["state-reports", "heartbeats", "backlog", "cycle-history", "shape-snapshots"]
 
+# Monotonic counter baked into every state-report filename. Previously,
+# filenames used microsecond-precision timestamps and resolved collisions
+# with a `-N` suffix — but `read_latest_state_report` sorted by `st_mtime`,
+# which on Windows NTFS has ~15ms resolution. Two back-to-back writes
+# therefore tied on mtime and the "most recent" file was non-deterministic.
+# An always-present zero-padded counter gives a lexical sort order that
+# matches insertion order regardless of filesystem timestamp granularity.
+_counter_lock = threading.Lock()
+_counter = 0
+
 
 def ensure_organism_dir(repo_path: str) -> Path:
     """Create .organism/ directory structure if it doesn't exist."""
@@ -19,32 +30,42 @@ def ensure_organism_dir(repo_path: str) -> Path:
 
 
 def _safe_timestamp() -> str:
-    """Generate a Windows-safe timestamp string (no colons, microsecond precision)."""
+    """Generate a Windows-safe, monotonic filename stem.
+
+    Format: `YYYY-MM-DDTHH-MM-SS-ffffff-NNNNNN` where NNNNNN is a process-local
+    counter. Lexical sort of two stems always matches the order they were
+    generated — no mtime dependency.
+    """
+    global _counter
     now = datetime.now(timezone.utc)
-    return now.strftime("%Y-%m-%dT%H-%M-%S-%f")
+    with _counter_lock:
+        _counter += 1
+        seq = _counter
+    return now.strftime("%Y-%m-%dT%H-%M-%S-%f") + f"-{seq:06d}"
 
 
 def write_state_report(repo_path: str, data: dict[str, Any]) -> str:
     """Write a state report JSON file. Returns the file path."""
     reports_dir = Path(repo_path) / ORGANISM_DIR / "state-reports"
     reports_dir.mkdir(parents=True, exist_ok=True)
-    base = _safe_timestamp()
-    filepath = reports_dir / f"{base}.json"
-    counter = 0
-    while filepath.exists():
-        counter += 1
-        filepath = reports_dir / f"{base}-{counter}.json"
+    filepath = reports_dir / f"{_safe_timestamp()}.json"
     with open(filepath, "w") as f:
         json.dump(data, f, indent=2, default=str)
     return str(filepath)
 
 
 def read_latest_state_report(repo_path: str) -> dict[str, Any] | None:
-    """Read the most recent state report. Returns None if none exist."""
+    """Read the most recent state report. Returns None if none exist.
+
+    Sorts by filename (lexical) — `_safe_timestamp()` guarantees monotonicity,
+    so this ordering is stable on every filesystem. Do NOT switch back to
+    mtime: NTFS coarse-granularity mtimes produced false ties that left the
+    'latest' report ambiguous.
+    """
     reports_dir = Path(repo_path) / ORGANISM_DIR / "state-reports"
     if not reports_dir.exists():
         return None
-    files = sorted(reports_dir.glob("*.json"), key=lambda p: p.stat().st_mtime)
+    files = sorted(reports_dir.glob("*.json"))
     if not files:
         return None
     with open(files[-1]) as f:

livingcode/tests/test_new_collectors.py

@@ -149,6 +149,120 @@ def test_missing_dir_returns_empty(self):
         self.assertEqual(collect_adapters("/does/not/exist"), [])
 
 
+class TestSignalsCollector(unittest.TestCase):
+    """The signals collector scans files that CALL the delivery pipeline
+    (fireWebhooksForOrg / deliverNativeNotifications) and harvests
+    `type: '<name>'` literals. Files that don't import either function must
+    be ignored — otherwise status enums, tool_type strings, etc. would
+    leak in as false positives."""
+
+    def setUp(self):
+        self.tmpdir = tempfile.mkdtemp()
+        self.lib = os.path.join(self.tmpdir, "app", "lib")
+        os.makedirs(self.lib, exist_ok=True)
+
+    def _write(self, rel_path, body):
+        full = os.path.join(self.tmpdir, rel_path)
+        os.makedirs(os.path.dirname(full), exist_ok=True)
+        with open(full, "w", encoding="utf-8") as f:
+            f.write(body)
+
+    def test_collects_types_from_delivery_call_sites(self):
+        self._write("app/lib/cost-alerts.js", """
+import { fireWebhooksForOrg } from './webhooks.js';
+export function buildSignal() {
+  return { type: 'cost_exceeded', severity: 'red' };
+}
+export async function fire(sql, org) {
+  await fireWebhooksForOrg(org, [{ type: 'cost_exceeded' }], sql);
+}
+""")
+        self._write("app/lib/signals.js", """
+import { deliverNativeNotifications } from './notification-adapters/index.js';
+export function agentMismatch() {
+  return { type: 'integration_mismatch', severity: 'amber' };
+}
+export async function flushSignals(sql, org, signals, settings) {
+  await deliverNativeNotifications(org, signals, settings, sql);
+}
+""")
+        from livingcode.collectors.signals import collect_signal_types
+        types = collect_signal_types(self.tmpdir)
+        self.assertEqual(types, ['cost_exceeded', 'integration_mismatch'])
+
+    def test_ignores_files_that_dont_call_delivery(self):
+        # Looks like a signal but nothing in this file calls the pipeline,
+        # so the collector must leave its `type:` alone.
+        self._write("app/lib/unrelated.js", """
+export const TOOL_TYPES = [
+  { type: 'bash' },
+  { type: 'edit' },
+];
+""")
+        from livingcode.collectors.signals import collect_signal_types
+        self.assertEqual(collect_signal_types(self.tmpdir), [])
+
+    def test_catches_signal_builders_that_dont_deliver(self):
+        """signals.js returns signal objects for a caller to deliver later —
+        the collector must catch those via the signal-shape heuristic
+        (type + red/amber severity in close proximity)."""
+        self._write("app/lib/signals.js", """
+export function collectSignals() {
+  return [
+    { type: 'integration_mismatch', severity: 'red', label: 'Bad cred' },
+    { type: 'stale_running_action', severity: 'amber', label: 'Stuck' },
+  ];
+}
+""")
+        from livingcode.collectors.signals import collect_signal_types
+        types = collect_signal_types(self.tmpdir)
+        self.assertEqual(types, ['integration_mismatch', 'stale_running_action'])
+
+    def test_rejects_unrelated_types_in_signal_builder_files(self):
+        """A file like demoFixtures.js can contain REAL signal fixtures
+        (type+severity) alongside unrelated `type:` fields (memory entities,
+        tool types). Only the signal-shaped ones should survive — if we
+        qualify once and then scrape every `type:` in the file, demo entity
+        `type:` values leak into the skill."""
+        self._write("app/lib/demo/demoFixtures.js", """
+// Unrelated memory entity — has `type:` but no severity nearby.
+export const MEMORY = {
+  entities: [
+    { name: 'Concept A', type: 'concept', mentions: 32 },
+    { name: 'Concept B', type: 'concept', mentions: 28 },
+  ],
+};
+// Lots of padding so the proximity window doesn't reach up to the memory block.
+// .........................................................................
+// .........................................................................
+// .........................................................................
+// .........................................................................
+// Actual signal fixture lives way down here.
+export const SIGNAL_FIXTURES = [
+  { severity: 'red', type: 'autonomy_spike', agent_id: 'x' },
+];
+""")
+        from livingcode.collectors.signals import collect_signal_types
+        types = collect_signal_types(self.tmpdir)
+        # The real signal survives; the unrelated `concept` entities don't.
+        self.assertIn('autonomy_spike', types)
+        self.assertNotIn('concept', types)
+
+    def test_dedupes_across_files(self):
+        self._write("app/lib/a.js", """
+import { fireWebhooksForOrg } from './webhooks.js';
+const s = { type: 'shared_type', severity: 'red' };
+fireWebhooksForOrg('org', [s], {});
+""")
+        self._write("app/lib/b.js", """
+import { deliverNativeNotifications } from './notification-adapters/index.js';
+const s = { type: 'shared_type', severity: 'amber' };
+deliverNativeNotifications('org', [s], [], {});
+""")
+        from livingcode.collectors.signals import collect_signal_types
+        self.assertEqual(collect_signal_types(self.tmpdir), ['shared_type'])
+
+
 class TestSkillEmitterNewSections(unittest.TestCase):
     """Verify the emitter renders the new sections when the shape carries them."""
 
@@ -175,9 +289,14 @@ def test_renders_all_three_new_sections(self):
             adapters=[
                 AdapterInfo(name='slack', required_keys=['SLACK_WEBHOOK_URL']),
             ],
+            signal_types=['cost_exceeded', 'integration_health_changed'],
         )
         out = emit_skill(shape)
 
+        self.assertIn('## Signal Types', out)
+        self.assertIn('`cost_exceeded`', out)
+        self.assertIn('`integration_health_changed`', out)
+
         self.assertIn('## Configuration Knobs', out)
         self.assertIn('### AI Providers', out)
         self.assertIn('### Cost alerts', out)

livingcode/types.py

@@ -238,6 +238,7 @@ class ShapeModel:
     setting_keys: list[SettingKeyInfo] = field(default_factory=list)
     events: list[EventInfo] = field(default_factory=list)
     adapters: list[AdapterInfo] = field(default_factory=list)
+    signal_types: list[str] = field(default_factory=list)
 
 
 @dataclass