turing-pyramid

# 🔺 Turing Pyramid **What it does:** Gives your agent a motivation system. 10 needs (security, connection, expression...) build tension over time via decay. Each heartbeat, the pyramid evaluates tensions, selects actions, and tells the agent what to do — from "check system health" to "write something creative." **What it is NOT:** A chatbot framework, an executor, or a system management tool. **Three layers with different scopes:** ⚠️ **Safety summary** - This skill is **not stateless**. It writes its own state and audit files (`needs-state.json`, `audit.log`, `followups.jsonl`, `MINDSTATE.md`, watchdog logs). - This skill reads files under `WORKSPACE`. If `WORKSPACE` points at a sensitive directory, the skill can scan sensitive files there. - `allow_kill` and `allow_cleanup` are **off by default** and should be treated as elevated, opt-in features. - `external-model` scanning is **off by default** and should only be enabled after explicitly documenting the credential source and intended API. **Three layers with different scopes:** | Layer | Scripts | Scope | System effects | |-------|---------|-------|----------------| | **Motivation** | `run-cycle.sh`, `mark-satisfied.sh`, `init.sh` | Read workspace files, write own state JSON | None — pure suggestion engine | | **Continuity** | `mindstate-daemon.sh`, `mindstate-freeze.sh`, `mindstate-boot.sh` | Read workspace + own state, write MINDSTATE.md | Read-only system checks: `pgrep` (gateway alive?), `df` (disk usage). No writes outside workspace. | | **Resilience** | `mindstate-watchdog.sh` | Monitor continuity scripts | **Default: detect + log only.** With `allow_kill: true`: terminates hung `mindstate-*.sh` processes (path-anchored, never other PIDs). With `allow_cleanup: true`: deletes orphan `.tmp` files in workspace + assets dir. Auto-freeze is always safe. | Core motivation scripts make **no network calls by default**. Some actions in needs-config.json are tagged `"external": true` (e.g., web search, check for updates) — these are text suggestions to the agent, not executed by the scripts themselves. The optional `external-model` scan method (disabled by default) can call an inference API if explicitly enabled by steward. The continuity daemon performs lightweight local system checks (read-only). The watchdog **detects and logs by default** — destructive actions (`kill`, `delete`) require explicit opt-in via config. ⚠️ **WORKSPACE isolation**: This skill reads and writes files inside the `WORKSPACE` directory. Never point `WORKSPACE` at your home directory, system folders, or any location containing credentials or sensitive files. Use an isolated workspace directory. **v1.27.0** — Execution Gate: structural enforcement that prevents agents from describing actions instead of doing them. Turing-exp tension formula: equal rotation at homeostasis, hierarchy only in crisis. --- ## 🚀 Quick Start ```bash # 1. Set workspace (REQUIRED) export WORKSPACE="/path/to/your/agent/workspace" # 2. Fix permissions (ClawHub doesn't preserve +x) chmod +x <skill-dir>/scripts/*.sh chmod +x <skill-dir>/tests/**/*.sh # 3. Initialize bash scripts/init.sh # 4. Run a cycle bash scripts/run-cycle.sh # 5. After completing an action bash scripts/mark-satisfied.sh <need> <impact> # Example: bash scripts/mark-satisfied.sh connection 1.5 ``` Add to `HEARTBEAT.md` for automatic operation: ```bash bash /path/to/skills/turing-pyramid/scripts/run-cycle.sh ``` ### Deployment Tiers Choose the level of integration that matches your trust and needs: | Tier | Components | System effects | Risk | |------|-----------|----------------|------| | **1. Interactive only** | `run-cycle.sh`, `mark-satisfied.sh`, `gate-*.sh` | Reads workspace, writes own state JSON | Minimal — no system interaction | | **2. + Heartbeat** | Tier 1 + `run-cycle.sh` in HEARTBEAT.md | Same as Tier 1, triggered by agent runtime | Low — no cron, no process management | | **3. + Continuity** | Tier 2 + `mindstate-daemon.sh` in cron (*/5) | Adds `pgrep` (read-only), `df` (read-only), writes MINDSTATE.md | Moderate — cron persistence, read-only system checks | | **4. + Watchdog (detect)** | Tier 3 + `mindstate-watchdog.sh` in cron (*/15) | Detects hung processes and orphan files, **logs only** (default). Auto-freezes stale cognition | Moderate — detection only, no destructive actions | | **5. Full self-healing** | Tier 4 + `allow_kill: true` + `allow_cleanup: true` | Kills hung skill processes, deletes orphan `.tmp` files | Higher — requires script review | **Start at Tier 1 or 2.** Upgrade only after reviewing scripts and running the test suite in an isolated workspace. You get full motivation/action selection at Tier 1 — everything above is optional. Even detect-only watchdog/continuity modes should be reviewed before persistent cron deployment. --- ## 🎓 Onboarding Guide ### For the Agent When you first install this skill: 1. **Read this file** to understand the 10 needs and how tension works 2. **Run `init.sh`** to create initial state files 3. **Run one cycle** (`run-cycle.sh`) — it proposes actions and registers them in the execution gate 4. **Actually do the action** — write the file, make the post, run the command 5. **Resolve the gate** (`gate-resolve.sh --need <need> --evidence "what you did"`) 6. **Mark satisfaction** (`mark-satisfied.sh <need> <impact>`) 7. **Integrate into heartbeat** — add `run-cycle.sh` to your HEARTBEAT.md **Important:** The execution gate blocks new proposals until you resolve or defer pending actions. This is by design — it prevents you from describing actions instead of doing them. If you can't complete an action, defer it with a reason: `gate-resolve.sh --defer <id> --reason "why"`. The system is self-tuning. After a few cycles, you'll see patterns: which needs decay fast, which actions are selected, where tensions build. **Key concepts:** - **Satisfaction** (0.5–3.0): How fulfilled a need is. 3.0 = perfect, 0.5 = crisis (floor) - **Tension** = dep² + importance × max(0, dep - threshold)². Equal at homeostasis, hierarchy in crisis. - **Decay**: Satisfaction drops over time at need-specific rates. Connection decays in 6h. Security in 168h. - **Actions**: Each need has 8-11 possible actions with impact levels (low/mid/high). The pyramid picks based on current state. **Resilience:** After setup, verify your cron has both entries (daemon + watchdog). The watchdog catches edge cases — daemon crashes, hung processes, stale state. See "Resilience & Crash Recovery" section for details. ### For the Human (Steward) **Before your agent starts using this:** 1. **Review the 10 needs** (table below) — are importance rankings right for your agent? 2. **Check scan config** — default `line-level` is free and works everywhere. Upgrade to `agent-spawn` if you have a cheap model (Haiku) available. 3. **External actions** — some suggestions mention external platforms (social networks, web search). These are *text suggestions only*. To remove: set their `weight: 0` in `needs-config.json`. 4. **Run the test suite** to verify everything works: ```bash WORKSPACE=/tmp/test-workspace bash tests/run-tests.sh ``` **Configuration conversation with your agent:** - "Review the 10 needs with me — let's adjust importance for your role" - "Do you have a cheap model for smarter scanning?" → `agent-spawn` method - "Which external action suggestions should we disable?" - "Check `gate-status.sh` — is the execution rate healthy?" - "Is the watchdog cron installed?" → verify with `crontab -l` - "Check `watchdog.log` — any recent restarts?" **Execution Gate** (enabled by default): The gate prevents your agent from logging "I did X" without actually doing X. Monitor execution rate via `gate-status.sh`. Healthy is >70%. If your agent repeatedly defers the same need, the actions may not fit your agent's capabilities — adjust them in `needs-config.json`. **Before enabling cron:** 1. Run `bash scripts/mindstate-watchdog.sh --dry-run` to verify behavior 2. Test in an isolated workspace: `WORKSPACE=/tmp/test MINDSTATE_ASSETS_DIR=/tmp/test-assets` 3. Ensure cron runs under a non-root user account 4. Review watchdog.sh and daemon.sh source — the kill scope is `mindstate-(daemon|freeze|boot)\.sh` only --- ## 📊 The 10 Needs | Need | Imp | Decay | What it measures | |------|-----|-------|-----------------| | security | 10 | 168h | System stability, no threats | | integrity | 9 | 72h | Alignment with SOUL.md values | | coherence | 8 | 24h | Memory consistency | | closure | 7 | 12h | Open threads resolved | | autonomy | 6 | 36h | Self-directed action taken | | connection | 5 | 8h | Social interaction | | competence | 4 | 36h | Skills used effectively | | understanding | 4 | 8h | Learning, curiosity satisfied | | recognition | 2 | 48h | Feedback received | | expression | 1 | 8h | Creative output produced | **Customize in `assets/needs-config.json`:** ```json "understanding": { "importance": 8, // Promote: research-focused agent "decay_rate_hours": 6 // Faster decay = more urgency } ``` --- ## ⚙️ Core Mechanics ### Turing-exp Tension Formula (v1.26.0) ``` tension = dep² + importance × max(0, dep - crisis_threshold)² ╰─ base ─╯ ╰────── crisis amplifier ──────────╯ (equal for (importance matters ONLY all needs) when dep > threshold) ``` **Below threshold** (default: 1.0, meaning sat > 2.0): All needs produce equal tension. Selection is effectively round-robin — expression gets as many slots as security. **Above threshold** (sat < 2.0): Importance amplifies the crisis signal. In a dual crisis, security (imp=10) gets priority over expression (imp=1). This ensures high-importance needs get priority only when multiple needs compete for attention simultaneously. Configure: `settings.tension_formula.crisis_threshold` in `needs-config.json` ### Tension → Action Selection ``` satisfaction decays over time → tension (Turing-exp formula) → probability roll (crisis=100%, ok=25%, perfect=0%) → impact selection (crisis→big actions, ok→small actions) → action selected from weighted pool ``` ### Action Probability by Satisfaction Level | Sat Level | Base P | Behavior | |-----------|--------|----------| | 0.5 crisis | 100% | Always act | | 1.0 severe | 90% | Almost always | | 1.5 deprived | 75% | Usually act | | 2.0 slight | 50% | Coin flip | | 2.5 ok | 25% | Occasionally | | 3.0 perfect | 0% | Skip | ### Protection Mechanisms | Mechanism | Purpose | |-----------|---------| | **Floor (0.5)** | Minimum satisfaction — prevents total collapse | | **Ceiling (3.0)** | Maximum — prevents runaway satisfaction | | **Starvation Guard** | Need at floor >48h without action → forced into cycle | | **Action Staleness** | Recently-selected actions get 80% weight penalty (variety) | | **Day/Night Mode** | Decay slows 50% at night (configurable) | ### Cross-Need Impact Actions on one need can boost or drag others: | Action on... | Boosts | Why | |-------------|--------|-----| | expression | recognition +0.25 | Express → noticed | | connection | expression +0.20 | Social sparks ideas | | competence | recognition +0.30 | Good work → respect | | autonomy | integrity +0.20 | Act on values | | closure | coherence +0.20 | Finished threads → order | | security | autonomy +0.10 | Safety enables risk | Full matrix: `assets/cross-need-impact.json` --- ## 🚪 Execution Gate (v1.27.0) Structural enforcement that prevents agents from describing actions instead of doing them. LLMs conflate "reasoning about an action" with "performing an action" — both are token generation. The gate requires **environmental evidence** that an action produced a state change. ### How it works ``` run-cycle.sh proposes action → gate-propose.sh registers it as PENDING → gate blocks new proposals until PENDING actions resolved → agent EXECUTES the action (writes file, posts, runs command) → gate-resolve.sh verifies evidence → COMPLETED → gate clears → next cycle allowed ``` ### Scripts | Script | Purpose | |--------|---------| | `gate-propose.sh` | Register pending action (called by run-cycle.sh automatically) | | `gate-resolve.sh` | Resolve with evidence, or defer with reason | | `gate-check.sh` | Check if gate is clear (built into run-cycle.sh) | | `gate-status.sh` | Human-readable status + execution rate analytics | ### Evidence Types | Type | Trust | Verification | |------|-------|-------------| | `mark_satisfied` | HIGH | Was mark-satisfied.sh called? (audit.log check) | | `file_created` | HIGH | Does expected file exist? | | `file_modified` | HIGH | Was file modified since proposal? | | `self_report` | LOW | Agent self-reports (counted separately in analytics) | ### Usage ```bash # After completing an action: bash scripts/mark-satisfied.sh expression 1.6 bash scripts/gate-resolve.sh --need expression --evidence "wrote post about X" # Or defer with reason: bash scripts/gate-resolve.sh --defer <action_id> --reason "quiet hours" # Check gate status: bash scripts/gate-status.sh ``` **Starvation guard actions are non-deferrable.** If the guard forces an action, it cannot be deferred. **Evidence trust model:** `file_created` and `file_modified` are high-trust because they require observable state changes. However, an agent with write access to `$WORKSPACE` can fabricate evidence by creating/modifying files. If this is a concern, restrict evidence types to `mark_satisfied` (requires explicit script call with audit trail) or add steward review for sensitive needs. `self_report` is explicitly low-trust and tracked separately in analytics. Configure: `execution_gate` in `assets/mindstate-config.json` --- ## 🧠 Deliberation Protocol (v1.31.0) Reflective actions ("re-read notes", "review SELF.md", "explore topic") previously collapsed into read → mark-satisfied → done. The Deliberation Protocol adds structured thinking with outcome artifacts. ### Two Action Modes - **Operative** (default): produces external artifact (file, commit, post). Same protocol as before. - **Deliberative** (`"mode": "deliberative"` in needs-config.json): must produce an **outcome artifact** + **routing decision**. ### The Pipeline Full (impact ≥ 1.0): `REPRESENT → RELATE+TENSION → GENERATE → EVALUATE → CONCLUDE → ROUTE` Compressed (impact < 1.0): `REPRESENT → CONCLUDE → ROUTE` Phases are questions, not obligations. Skip with a reason — but always reach CONCLUDE and ROUTE. ### Outcome Types Not every deliberation ends in a verdict. Six valid outcome types: - **Decision** — clear action directive - **Assessment** — evaluation of current state - **Diagnosis** — root cause identification - **Question refinement** — the real question isn't what was asked - **Uncertainty artifact** — explicit gap with specific missing data - **Tension artifact** — named conflict between elements ### Routing (Phase 6) Every outcome must go somewhere: `followup` | `research_thread` | `interest` | `steward_question` | `priority_flag` | `reframe` | `chain` | `concluded` ### Scripts ```bash # Template scaffolding (or use free-form + validate) deliberate.sh --template --need understanding --action "explore topic" # Validate a free-form file deliberate.sh --validate research/threads/cosmos/sulfur-biosignature-problem.md # Quick inline check deliberate.sh --validate-inline --conclusion "H2S is not reliable" --route "research_thread" ``` ### Gate Integration - `gate-propose.sh` stores `action_mode` in pending_actions.json - `gate-resolve.sh --conclusion "..."` logs outcome; warns (doesn't block) if deliberative action lacks conclusion - `mark-satisfied.sh --conclusion "..."` records in audit.log ### Design Principles 1. **Scaffolding, not bureaucracy** — gate checks presence, not quality 2. **Anti-compliance by design** — validate mode over template mode; gate warns, never blocks 3. **Persistent state change mandatory** — not necessarily a file, but always a trace 4. **Phases are questions, not obligations** — conscious skipping is valid Full design: `DELIBERATION-PROTOCOL.md` in skill root. --- ## 🎲 Spontaneity System (Layers A/B/C) Three layers create organic, unpredictable behavior: | Layer | Mechanism | Effect | |-------|-----------|--------| | **A — Surplus** | Excess satisfaction accumulates. When threshold hit → HIGH impact roll | Natural ~28-35h pulsing rhythm | | **B — Noise** | Boredom grows without high-impact actions (max 9%). Echo boost after spontaneous fire (8%, decays 24h) | Variety when things get stale | | **C — Context** | File system changes trigger need-specific boosts (new research files → understanding) | Environmental responsiveness | Combined noise cap: 12%. Disabled for safety needs (security, integrity, coherence). Configure: `settings.spontaneity` in `needs-config.json` --- ## 🔄 Continuity Layer (v1.23.0) State persistence across discrete sessions via a two-layer living document. The **reality** layer updates continuously (cron daemon), while the **cognition** layer freezes at session end and restores at next boot. ### Architecture ``` ┌─────────────────────────────────────────────────┐ │ MINDSTATE.md │ ├────────────────────┬────────────────────────────┤ │ ## reality │ ## cognition │ │ (daemon, 5min) │ (frozen at session end) │ │ auto-updated │ read-only between │ │ between sessions │ session endpoints │ ├────────────────────┴────────────────────────────┤ │ ## forecast (frozen, consumed at boot) │ └─────────────────────────────────────────────────┘ ``` ### Four Scripts | Script | When | What | |--------|------|------| | `mindstate-daemon.sh` | Cron every 5min | Updates reality: pyramid state, filesystem changes, system health, stale cognition detection, physical temperature | | `mindstate-freeze.sh` | End of substantive session | Freezes cognition: trajectory, open threads, momentum, cognitive temperature | | `mindstate-boot.sh` | Session start (FIRST thing) | Loads MINDSTATE, reconciles forecast vs reality, reports continuity score | | `mindstate-watchdog.sh` | Cron every 15min | Process watchdog: detects hung/dead scripts, cleans orphans, restarts daemon | ### Boot Sequence (inverted) ``` 1. MINDSTATE.md → Where am I? (position + velocity) 2. SOUL.md → Who am I? (identity) 3. MEMORY.md → What do I know? (history) 4. run-cycle.sh → What should I do? (action) ``` Current state loads first — early context frames interpretation of everything after. ### Temperature System **Physical** (daemon-computed, deterministic, first-match): | Word | Condition | |------|-----------| | crisis | Any need critical (sat ≤ 0.5) | | pressure | Average tension > 3 | | focus | One need dominates (max tension > 2) | | impulse | Spontaneous Layer A fired recently | | accumulation | Surplus building toward threshold | | calm | All tensions low (default) | **Cognitive** (freeze-computed from session): building / exploring / intensive / contemplation / brief / neutral **Drift detection:** If physical ≠ cognitive at boot → DRIFT_DETECTED. Reality diverged while cognition was frozen. ### Setup ```bash # Daemon cron (updates reality between sessions) crontab -e */5 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-daemon.sh >/dev/null 2>&1 # Watchdog cron (resilience — detects hung/dead scripts, restarts) */15 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-watchdog.sh >/dev/null 2>&1 # Boot (add to AGENTS.md session start — BEFORE SOUL.md) WORKSPACE=/path/to/workspace bash scripts/mindstate-boot.sh # Freeze (add to session end hook) WORKSPACE=/path/to/workspace bash scripts/mindstate-freeze.sh "$SESSION_START_EPOCH" ``` ### Resilience & Crash Recovery (v1.28.0) The continuity layer is designed to survive unexpected termination: **Atomic writes:** All scripts write to `*.tmp.$$` (PID-unique) then `mv` to final path. A crash mid-write leaves an orphan temp file but never corrupts the target. **Trap handlers:** `mindstate-daemon.sh` and `mindstate-freeze.sh` register `EXIT`/`SIGTERM`/`SIGINT`/`SIGHUP` traps that clean up temp files on unexpected termination. **Orphan cleanup:** The daemon cleans up any `*.tmp.*` files older than 10 minutes on every run. **Stale cognition detection:** The daemon monitors when `mindstate-freeze.sh` last ran. If cognition hasn't been frozen for longer than `stale_cognition_hours` (default: 24h), a warning appears in MINDSTATE.md under `system.cognition`. **Watchdog** (`mindstate-watchdog.sh`): Runs on cron every 15 minutes. **Safe by default** — detect and log only. Destructive actions (kill, delete) require explicit opt-in. | Check | Default behavior | With opt-in | |-------|-----------------|-------------| | MINDSTATE.md freshness | Log warning, restart daemon | Same (restart is safe — just runs daemon.sh) | | Hung processes (>5 min) | **Log only** | `allow_kill: true` → SIGTERM, then SIGKILL | | Orphaned .tmp files | **Log only** | `allow_cleanup: true` → delete files | | Stale cognition (>6h) | Auto-freeze (safe — runs freeze.sh) | Same | **What does kill target?** Only processes matching the **full path** `$SCRIPT_DIR/mindstate-(daemon|freeze|boot).sh`. The pattern is anchored to the skill's own script directory via `grep -F "$SCRIPT_DIR/mindstate-"`. It cannot match unrelated processes, system services, or scripts in other directories. Even with `allow_kill: true`, it will never terminate anything outside the skill's own continuity scripts. **Auto-freeze** is enabled by default because it's safe — it only runs `mindstate-freeze.sh` which writes to MINDSTATE.md in the workspace. The watchdog logs only problems (to `assets/watchdog.log`, auto-rotated at 200 lines). Silent when everything is healthy. Supports `--dry-run` for testing. Configure in `assets/mindstate-config.json`: ```json "watchdog": { "max_stale_minutes": 15, "max_process_age_seconds": 300, "allow_kill": false, "allow_cleanup": false, "auto_freeze": true, "auto_freeze_stale_hours": 6 } ``` **To enable full self-healing** (after reviewing scripts): ```json "allow_kill": true, "allow_cleanup": true ``` **Failure modes and recovery:** | Failure | Impact | Recovery | |---------|--------|----------| | OpenClaw restart | Heartbeat pauses, cron continues | Watchdog ensures daemon stays alive | | Daemon crash mid-write | Orphan .tmp file | Next daemon run cleans it up | | Freeze never called | Stale cognition section | Watchdog auto-freezes after 6h (configurable) | | Hung process (infinite loop) | Blocks flock, daemon skips ticks | Watchdog kills after 5 min | | Machine reboot | All processes die | Cron restarts daemon + watchdog automatically | ### Test Isolation Set `MINDSTATE_ASSETS_DIR` to isolate tests from production state: ```bash export MINDSTATE_ASSETS_DIR=/tmp/test-assets ``` --- ## 🔍 Scan Configuration Scanners evaluate each need by analyzing workspace files. | Method | Cost | Accuracy | Setup | |--------|------|----------|-------| | `line-level` (default) | Free | Good | None | | `agent-spawn` | Low | High | Cheap model (Haiku) in allowed list | | `external-model` | Low | High | Explicit API credential + steward approval | Config: `assets/scan-config.json`. Fallback always to `line-level`. **For stewards:** `agent-spawn` and `external-model` require explicit approval (`approved_by_steward: true`). The skill never enables these silently. If you enable `external-model`, document the exact credential source (env var or file), API endpoint, and approval path in your deployment before use. --- ## 🔒 Security Model **Three layers with different scopes and system effects (see table above).** ``` ┌─────────────────────┐ ┌─────────────────────┐ │ TURING PYRAMID │ │ AGENT │ ├─────────────────────┤ ├─────────────────────┤ │ • Reads local files │ │ • Has API keys │ │ • Calculates decay │ ───▶ │ • Has permissions │ │ • Outputs: "★ do X" │ │ • DECIDES & ACTS │ │ • No network by def │ │ │ └─────────────────────┘ └─────────────────────┘ │ │ (continuity layer, cron) ▼ ┌─────────────────────┐ │ DAEMON/WATCHDOG │ ├─────────────────────┤ │ • Updates MINDSTATE │ │ • pgrep, df (read) │ │ • Watchdog: kill │ │ mindstate-*.sh │ │ processes ONLY │ │ • .tmp cleanup in │ │ $WORKSPACE + own │ │ assets dir only │ └─────────────────────┘ ``` ### What This Skill Does / Does Not Access | ✅ Accesses | ❌ Never accesses | |------------|-------------------| | MEMORY.md, memory/*.md (read) | Files outside `$WORKSPACE` + own assets dir | | SOUL.md, SELF.md (read) | Credentials (unless `external-model` enabled) | | research/, scratchpad/ (read) | `sudo`, `docker`, `systemctl` | | needs-state.json, audit.log (read/write) | Network by default (curl, wget, ssh, etc.). Optional `external-model` mode changes this and must be explicitly enabled | | MINDSTATE.md (write, daemon) | Processes other than `mindstate-*.sh` | | `pgrep`, `df` (read-only system checks, daemon) | Paths outside workspace/assets | | `kill` on `mindstate-*.sh` PIDs (watchdog only) | Root/elevated permissions | | `.tmp.*` files in workspace + assets (delete, watchdog) | | ### Security Warnings 1. **PII in workspace files** — Scans use grep patterns on memory files. They see keywords, not meaning. But workspace files may contain personal data. Scope `$WORKSPACE` carefully. 2. **Action suggestions may trigger auto-execution** — If your agent runtime auto-executes suggestions, review `needs-config.json` and disable unwanted external actions (`weight: 0`). 3. **Self-reported state** — `mark-satisfied.sh` trusts caller input. Audit trail in `assets/audit.log` with sensitive data scrubbing. 4. **Symlink protection** — All `find` commands use `-P` flag (physical mode, never follows symlinks). Path traversal blocked via `realpath` validation. 5. **System health checks** (daemon only) — `mindstate-daemon.sh` runs `pgrep` (gateway alive?) and `df` (disk usage). These are read-only, local, and produce no side effects. No `sudo`, `systemctl`, or elevated operations. 6. **Watchdog process management** — `mindstate-watchdog.sh` can `kill` processes, but **only those matching the full `$SCRIPT_DIR/mindstate-*.sh` path** (grep -F on the skill's own script directory + process name). This path-anchored pattern prevents false matches against unrelated processes with similar names. Verify by searching for `kill` and `grep` in the script — every kill is gated by the path-specific filter. 7. **Cron isolation** — Both cron entries (daemon + watchdog) should run under the same non-root user that owns `$WORKSPACE`. Never add these as root cron jobs. Test with `--dry-run` (watchdog) and a temporary `$WORKSPACE` before deploying. 8. **No network operations in scripts** — `grep -rn 'curl\|wget\|nc \|ssh\|scp\|git clone\|npm install' scripts/` returns zero matches (excluding optional `external-model` scan, disabled by default). 9. **External action suggestions** — 8 actions in `needs-config.json` are flagged `"external": true`: - web search on topic from INTERESTS.md - help someone via available integrations - web search on curious question - share completed work publicly - publish research or essay publicly - present completed work to community for feedback - post thought/update on social platform - write social post These are **text suggestions only** — the scripts never execute them, make no network calls, and have no side effects. The agent's runtime decides whether to act on them. To disable all external suggestions: ```bash # List them: jq '[.needs[].actions[] | select(.external == true) | .name]' assets/needs-config.json # Disable by setting weight to 0 in each need's action list ``` For strict offline behavior, disable all external actions and keep `semantic_predictions.enabled: false`. 10. **PATH and workspace isolation** — All file operations use `$WORKSPACE` as root. `find` uses `-P` (no symlink follow). `realpath` validation in scanners prevents path traversal. Keep `$WORKSPACE` isolated from credentials and system config. The daemon's `pgrep`/`df` and watchdog's `kill` operate on the system process table, scoped by the skill's own `$SCRIPT_DIR` path — ensure the skill directory is not writable by untrusted users. ### Audit Trail (v1.12.0+) All state changes logged with timestamp, need, impact, reason (scrubbed): - Long tokens → `[REDACTED]` - Credit cards → `[CARD]` - Emails → `[EMAIL]` - Passwords/secrets/tokens → `[REDACTED]` View: `cat assets/audit.log | jq` --- ## 📁 File Structure ``` turing-pyramid/ ├── SKILL.md # This file ├── CHANGELOG.md # Version history ├── assets/ │ ├── needs-config.json # ★ Main config (needs, actions, weights) │ ├── cross-need-impact.json # ★ Cross-need cascade matrix │ ├── mindstate-config.json # Continuity layer config │ ├── scan-config.json # Scan method config │ ├── decay-config.json # Day/night mode settings │ ├── needs-state.json # Runtime state (auto-managed, not published) │ └── audit.log # Action audit trail (not published) ├── scripts/ │ ├── run-cycle.sh # Main: tension evaluation + action selection │ ├── mark-satisfied.sh # State update + cross-need cascades │ ├── init.sh # First-time initialization │ ├── show-status.sh # Current state display │ ├── mindstate-daemon.sh # Continuity: reality updater (cron) │ ├── mindstate-freeze.sh # Continuity: cognition snapshot │ ├── mindstate-boot.sh # Continuity: boot + reconciliation │ ├── mindstate-watchdog.sh # Continuity: process watchdog (cron) │ ├── mindstate-utils.sh # Continuity: shared utilities │ ├── spontaneity.sh # Layers A/B/C logic │ ├── apply-deprivation.sh # Deprivation cascade engine │ ├── get-decay-multiplier.sh # Day/night multiplier │ ├── _scan_helper.sh # Shared scan utilities │ └── scan_*.sh # Need-specific scanners (10 files) ├── tests/ │ ├── run-tests.sh # Test runner │ ├── unit/ # 22 unit test files │ ├── integration/ # 4 integration tests │ ├── regression/ # Regression tests │ └── fixtures/ # Test data └── references/ ├── TUNING.md # Detailed tuning guide └── architecture.md # Technical documentation ``` --- ## 💰 Token Usage | Heartbeat Interval | Est. tokens/month | Est. cost | |--------------------|--------------------|-----------| | 30 min | 1.4M–3.6M | $2–6 | | 1 hour | 720k–1.8M | $1–3 | | 2 hours | 360k–900k | $0.5–1.5 | Stable agent with satisfied needs = fewer tokens per cycle. --- ## 🧪 Testing ```bash # Full suite WORKSPACE=/path/to/workspace bash tests/run-tests.sh # Unit only WORKSPACE=/path/to/workspace bash tests/run-tests.sh unit # Integration only WORKSPACE=/path/to/workspace bash tests/run-tests.sh integration ``` **26 test files, 65+ assertions.** Covers: decay, tension, probability, impact selection, spontaneity (A/B/C), cross-need impact, crisis mode, starvation guard, action staleness, audit scrubbing, scan config, day/night mode, mindstate daemon/freeze/boot, full lifecycle + homeostasis. --- ## 📋 Example Cycle ``` 🔺 Turing Pyramid — Cycle at Wed Mar 18 04:11 ====================================== Current tensions: coherence: tension=8.0 (sat=2.0, dep=1.0) closure: tension=7.0 (sat=2.0, dep=1.0) autonomy: tension=6.0 (sat=2.0, dep=1.0) connection: tension=5.0 (sat=2.0, dep=1.0) Selecting 3 needs (0 forced + 3 regular)... 📋 Decisions: ▶ ACTION: coherence (tension=8.0, sat=2.0) Range mid rolled → selected: ★ re-read last 3 days of memory for consistency (impact: 1.2) Then: mark-satisfied.sh coherence 1.2 ▶ ACTION: closure (tension=7.0, sat=2.0) Range low rolled → selected: ★ complete or drop a stale intention (impact: 0.8) Then: mark-satisfied.sh closure 0.8 ▶ ACTION: autonomy (tension=6.0, sat=2.0) [SPONTANEOUS] Range high rolled → selected: ★ make significant autonomous decision (impact: 2.9) Then: mark-satisfied.sh autonomy 2.9 ====================================== Summary: 3 action(s), 0 noticed ``` --- **Version:** 1.34.8 — Self-throttle race fix: daemon --force flag, boot always gets fresh reality, test isolation improved (state reset + SKIP_DAEMON_FORCE). Full changelog: `CHANGELOG.md` | Tuning guide: `references/TUNING.md`