@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.4

package/monitor/.signal-state.json

@@ -0,0 +1,3 @@
+{
+  "cycleCount": 10
+}

package/monitor/ACTIONS.log

@@ -0,0 +1 @@
+[2026-07-12T13:08:06-05:00] CYCLE 4: clean run (0 stale loops, 0 dirty repos, 0 log rotations, 0 junk quarantined). Security alert proposal stale (0 current alerts); separate triage agent handling. All checks passed.

package/monitor/BRIEF.md

@@ -0,0 +1,24 @@
+# Aesop Monitor Brief — 2026-07-12T19:11:11.520Z
+
+## Heartbeat check
+✓ All heartbeats fresh (watchdog 300s, monitor 3600s, others 1800s).
+
+## Git state
+No repos configured.
+
+## Memory
+- 26 memory file(s)
+
+## Log files
+✓ All logs within thresholds.
+
+## Extended signal checks
+Checks 5 (junk-script sprawl), 6 (stray-repo scripts), 8 (respawn-watch), 10 (unreviewed-prompts) are **extended (off)** — enable via `monitor.extended_signals: true` in aesop.config.json or `AESOP_EXTENDED_SIGNALS=true`.
+
+## Security
+- Alert log: 0 entries, 0 HIGH/MED
+
+## Cost tracking
+- Cycle: 10
+
+_Refinement points → act per CHARTER.md (AUTO safe, PROPOSE rule changes). Goal is fixed._

package/monitor/CHARTER.md

@@ -27,18 +27,18 @@ Each cycle, `collect-signals.mjs` runs these checks and emits `BRIEF.md` + `SIGN
    default 500 lines / 40 KB). If a log exceeds threshold, emit rotation signal (AUTO tier can
    invoke rotate_logs.py if available); append rotation summary to BRIEF.md.
 
-5. **Junk-script sprawl detection** — scan temp/scratch roots for throwaway `.py`/.mjs`/`.js` files
+5. **Junk-script sprawl detection** *(extended, opt-in via `monitor.extended_signals`)* — scan temp/scratch roots for throwaway `.py`/.mjs`/`.js` files
    older than 24 hours, not in a live session directory (avoid false-positives during active work).
    Count total, estimate quarantinable, list oldest. AUTO tier quarantines confirmed junk into
    `monitor/quarantine/` with manifest.
 
-6. **Stray scripts in repo roots** — scan recent commits (7d) to detect one-off `.py`/`.mjs`/`.sql`
+6. **Stray scripts in repo roots** *(extended, opt-in via `monitor.extended_signals`)* — scan recent commits (7d) to detect one-off `.py`/`.mjs`/`.sql`
    scripts committed directly to repo root (not under proper src/scripts paths). Flag for cleanup.
 
 7. **Security alert review loop** — tail SECURITY-ALERTS.log for new HIGH/MED entries (skip suppressed);
    each new alert noted in BRIEF.md. Monitor agent does semantic review (REAL vs FP) each cycle.
 
-8. **Respawn watch (Rule 6 retry cap)** — parse agent spawn records; normalize descriptions to
+8. **Respawn watch (Rule 6 retry cap)** *(extended, opt-in via `monitor.extended_signals`)* — parse agent spawn records; normalize descriptions to
    prompt-signatures (first ~40 chars, lowercased); count occurrences in recent window (last 50 rows).
    Flag any signature appearing >3 times as probable hung-agent loop → rule 6 cap breached.
    Limitation: heuristic may have false positives for intentional similar-task fan-outs.
@@ -46,9 +46,23 @@ Each cycle, `collect-signals.mjs` runs these checks and emits `BRIEF.md` + `SIGN
 9. **Cost cadence tracking** — every 3rd cycle, harvest agent spawn ledger and append cost tick
    to COST-LOG.md (cycle count, timestamp, model distribution). Flags non-haiku specializations.
 
-10. **Unreviewed agent prompts** — run fleet-prompt-extractor.py (if available) to collect NEW
+10. **Unreviewed agent prompts** *(extended, opt-in via `monitor.extended_signals`)* — run fleet-prompt-extractor.py (if available) to collect NEW
     spawns since last review; emit count in SIGNALS.json + note in BRIEF.md.
 
+## Extended signals (opt-in)
+
+Checks 5, 6, 8, and 10 are marked as "extended" — they are disabled by default but can be
+enabled via configuration:
+
+- **Config key:** `monitor.extended_signals` (boolean, default: `false`) in aesop.config.json
+- **Env override:** `AESOP_EXTENDED_SIGNALS` (string `'true'` or `'1'` to enable)
+- **Precedence:** env var > config file > default (false)
+
+When disabled, extended checks emit `{"skipped": true}` in SIGNALS.json and BRIEF.md notes them
+as "extended (off)". AUTO junk-quarantine action only runs when the junk check is enabled.
+PROPOSE-tier signals for extended checks (respawn-watch-breach, stray-repo-scripts) are only
+emitted when extended_signals is ON.
+
 ## Action tiers
 
 - **AUTO (apply immediately, then log to `ACTIONS.log`):**
@@ -56,7 +70,7 @@ Each cycle, `collect-signals.mjs` runs these checks and emits `BRIEF.md` + `SIGN
   - Log rotation (invoke rotate_logs.py if available; fail-open if not).
   - Persist heartbeat write (`.monitor-heartbeat` update after cycle).
   - Quarantine confirmed-junk scripts: move old temp `.py`/`.mjs` (not live session) into
-    `monitor/quarantine/` with manifest — never delete outright.
+    `monitor/quarantine/` with manifest — never delete outright (only when extended_signals is ON).
 
 - **PROPOSE (write to `PROPOSALS.md`, do NOT apply — needs user approval):**
   - Changes to cardinal rules or agent configuration.
@@ -107,10 +121,17 @@ continuations; maintain Windows+POSIX compatibility).
 ## Single-instance guard
 
 Before running, check `.monitor-heartbeat` — if <300s old, skip cycle (another monitor is running).
-After cycle completes, update `.monitor-heartbeat` with current epoch.
+After cycle completes, update `.monitor-heartbeat` with current epoch. 
+Override with `AESOP_MONITOR_FORCE=true` or `AESOP_MONITOR_FORCE=1` for manual runs or tests (explicit comparison, not truthiness: strings like `'0'` or `'false'` do NOT bypass the guard).
 
-## Single-writer discipline
+## Single-writer discipline with atomic operations
 
 - Only the monitor edits `BRIEF.md`, `SIGNALS.json`, `ACTIONS.log`, `.monitor-heartbeat`, `.signal-state.json`.
-- External processes (human, other agents) write to `PROPOSALS.md` (append or structured inbox).
+  - Writes are atomic (temp file + rename) to prevent mid-write corruption if a kill occurs.
+  - Rename is retried on EPERM/EBUSY (Windows readers holding file) with exponential backoff; .tmp is cleaned up on final failure; prior file is preserved (degrade gracefully).
+- `PROPOSALS.md` uses atomic operations (mkdir-style lockfile) to prevent race conditions between concurrent appends (emitProposal) and full rewrites (accept/reject).
+  - **Both emitProposal and moveProposal (accept/reject) acquire the PROPOSALS.md.lock before read-check-append/write**.
+  - Lock contains pid+timestamp for staleness detection (>60s stale locks are reclaimed).
+  - Lock is acquired, held during read-modify-write, released after write completes.
+  - **Fail-closed (P0 wave-8 fix)**: If lock acquisition fails after timeout (default 30s, configurable via AESOP_LOCK_TIMEOUT_MS env var or config), the operation throws an error instead of proceeding. In emitProposal (monitor context), lock failures skip proposal emission for that cycle and retry next cycle. In proposals.mjs CLI (accept/reject), lock failures exit with error code 1 (caller should retry).
 - Quarantine manifest is append-only; never edit entries, only add new ones.

package/monitor/CLAUDE.md

@@ -0,0 +1,40 @@
+# monitor/ — Orchestration monitor
+
+**Purpose**: Continuous background signal collector and refinement proposer — watches fleet machinery health deterministically (Node.js, no LLM), emits cycle snapshots, and proposes rule changes via append-only PROPOSALS.md; GOAL IS FIXED (improve machinery, never mission).
+
+## Files
+
+- **CHARTER.md** — Governance document; defines 10 signal checks (4 of them extended/opt-in), action tiers (AUTO/PROPOSE), outputs, single-instance guard, single-writer discipline. Read-only; behavior changes only via PROPOSALS/behavioral-PR flow.
+- **collect-signals.mjs** — Deterministic signal collector (Node.js built-ins only); emits BRIEF.md + SIGNALS.json each cycle; reads config from env or aesop.config.json.
+- **BRIEF.md** — Human-readable cycle snapshot (heartbeats, git state, memory freshness, log rotation, junk sprawl, stray scripts, security alerts, respawn watch, cost cadence, unreviewed prompts); overwritten each cycle; runtime.
+- **SIGNALS.json** — Machine-readable metrics (same signal keys as BRIEF); JSON; overwritten each cycle; runtime.
+- **PROPOSALS.md** — Structured inbox for user approval (idempotent per signal key, append-only); never edited by monitor after emission; tracks respawn-watch-breach, stray-repo-scripts, security-alerts-high-med, stale-memory-files; gitignored.
+- **ACTIONS.log** — Append-only log of AUTO tier actions taken (heartbeat updates, log rotation invokes, junk quarantine); runtime; gitignored.
+- **.monitor-heartbeat** — Epoch timestamp (line 1) for single-instance liveness check (<300s = skip cycle); runtime; gitignored.
+- **.signal-state.json** — Sidecar state (cycleCount, etc.); runtime; gitignored.
+
+## Contracts
+
+**Signal keys collected**: heartbeats, git, memory, logs, junk, strayRepo, alerts, respawnWatch, costTick, unreviewedPrompts. Outputs: BRIEF.md (human), SIGNALS.json (machine); both runtime/gitignored. PROPOSALS.md (tracked, append-only); ACTIONS.log (runtime/gitignored).
+
+**Extended signals (opt-in, default OFF)**: checks 5 (junk), 6 (strayRepo), 8 (respawnWatch), and 10 (unreviewedPrompts) are extended — disabled by default.
+- Config key: `monitor.extended_signals` (boolean, default `false`) in aesop.config.json.
+- Env override: `AESOP_EXTENDED_SIGNALS` (`'true'` or `'1'` to enable).
+- Precedence: env var > config file > default (false).
+- When disabled, extended checks emit `{"skipped": true}` in SIGNALS.json and BRIEF.md notes them as "extended (off)"; their dirs are not walked. PROPOSE-tier signals for extended checks (respawn-watch-breach, stray-repo-scripts) are only emitted when extended_signals is ON.
+
+**AUTO tier actions** (apply immediately, log to ACTIONS.log): heartbeat checks (read-only); log rotation (invoke rotate_logs.py if available, fail-open); heartbeat write (.monitor-heartbeat update); junk script quarantine (move old temp .py/.mjs to monitor/quarantine/ + manifest — only when extended_signals is ON).
+
+**PROPOSE tier actions** (write to PROPOSALS.md, await user approval): rule changes, agent config changes, deletions outside monitor/quarantine/, orchestration policy changes.
+
+**Idempotency rule**: Proposal emission keyed on signal key (e.g., 'respawn-watch-breach'); only emitted if not already present in PROPOSALS.md (check: `**Signal:** <key>` exists). Idempotent + append-only; safe to run repeatedly.
+
+## Invariants & Gotchas
+
+- CHARTER.md is authority; monitor logic is faithful to it; never edit CHARTER.md or collect-signals.mjs directly — propose via PROPOSALS.md.
+- Goal is FIXED (improve machinery, never mission); if monitor thinks goal should change, it writes note to PROPOSALS.md and stops.
+- Single-instance guard via .monitor-heartbeat; if <300s old, skip cycle.
+- Single-writer discipline: only monitor writes BRIEF.md, SIGNALS.json, ACTIONS.log, .monitor-heartbeat, .signal-state.json.
+- Config from env (AESOP_ROOT, BRAIN_ROOT, SCRIPTS_ROOT, TEMP_ROOT, AESOP_EXTENDED_SIGNALS) or aesop.config.json; falls back to safe defaults.
+- Robust to missing files; treats missing dirs/logs as empty, never crashes.
+- Node.js only (no Python, no LLM, no cloud); deterministic + cheap.

package/monitor/SIGNALS.json

@@ -0,0 +1,54 @@
+{
+  "timestamp": "2026-07-12T19:11:11.520Z",
+  "cycleCount": 10,
+  "heartbeats": {
+    "staleCount": 0,
+    "details": []
+  },
+  "git": [],
+  "memory": {
+    "count": 26,
+    "staleMemories": [],
+    "staleCount": 0
+  },
+  "logs": [
+    {
+      "name": "FLEET-BACKUP.log",
+      "exists": true,
+      "sizeKb": "1.8",
+      "lineCount": 37,
+      "needsRotation": false
+    },
+    {
+      "name": "SECURITY-ALERTS.log",
+      "exists": false,
+      "sizeKb": 0,
+      "lineCount": 0,
+      "needsRotation": null
+    },
+    {
+      "name": "ACTIONS.log",
+      "exists": true,
+      "sizeKb": "0.2",
+      "lineCount": 1,
+      "needsRotation": false
+    }
+  ],
+  "junk": {
+    "skipped": true
+  },
+  "strayRepo": {
+    "skipped": true
+  },
+  "alerts": {
+    "count": 0,
+    "highMedCount": 0
+  },
+  "respawnWatch": {
+    "skipped": true
+  },
+  "costTick": null,
+  "unreviewedPrompts": {
+    "skipped": true
+  }
+}