🔺 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.
• INLINECODE6 and allow_cleanup are off by default and should be treated as elevated, opt-in features.
• INLINECODE8 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	INLINECODE9, mark-satisfied.sh, INLINECODE11	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

CODEBLOCK0

Add to HEARTBEAT.md for automatic operation:
CODEBLOCK1

Deployment Tiers

Choose the level of integration that matches your trust and needs:

Tier	Components	System effects	Risk
1. Interactive only	INLINECODE29, mark-satisfied.sh, INLINECODE31	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. 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. 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:

CODEBLOCK2

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 INLINECODE52
• "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. 1. Run bash scripts/mindstate-watchdog.sh --dry-run to verify behavior
2. Test in an isolated workspace: INLINECODE57
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:

"understanding": {
  "importance": 8,        // Promote: research-focused agent
  "decay_rate_hours": 6   // Faster decay = more urgency
}

---

⚙️ Core Mechanics

Turing-exp Tension Formula (v1.26.0)

CODEBLOCK4

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 INLINECODE61

Tension → Action Selection

CODEBLOCK5

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

CODEBLOCK6

Scripts

Script	Purpose
INLINECODE63	Register pending action (called by run-cycle.sh automatically)
INLINECODE64

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
INLINECODE67	HIGH	Was mark-satisfied.sh called? (audit.log check)
INLINECODE68

HIGH | Does expected file exist? | | file_modified | HIGH | Was file modified since proposal? | | self_report | LOW | Agent self-reports (counted separately in analytics) |

Usage

CODEBLOCK7

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): INLINECODE80

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 | INLINECODE88

Scripts

CODEBLOCK8

Gate Integration

• - gate-propose.sh stores action_mode in pending_actions.json
• INLINECODE91 logs outcome; warns (doesn't block) if deliberative action lacks conclusion
• INLINECODE92 records in audit.log

Design Principles

1. 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

CODEBLOCK9

Four Scripts

Script	When	What
INLINECODE96	Cron every 5min	Updates reality: pyramid state, filesystem changes, system health, stale cognition detection, physical temperature
INLINECODE97

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)

CODEBLOCK10

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

CODEBLOCK11

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:
CODEBLOCK12

To enable full self-healing (after reviewing scripts):
CODEBLOCK13

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:

export MINDSTATE_ASSETS_DIR=/tmp/test-assets

---

🔍 Scan Configuration

Scanners evaluate each need by analyzing workspace files.

Method	Cost	Accuracy	Setup
INLINECODE123 (default)	Free	Good	None
INLINECODE124

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).

CODEBLOCK15

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. 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.

1. 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).

1. 3. Self-reported state — mark-satisfied.sh trusts caller input. Audit trail in assets/audit.log with sensitive data scrubbing.

1. 4. Symlink protection — All find commands use -P flag (physical mode, never follows symlinks). Path traversal blocked via realpath validation.

1. 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.

1. 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.

1. 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.

1. 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).

1. 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:

   # 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.

1. 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 → INLINECODE179
• Credit cards → INLINECODE180
• Emails → INLINECODE181
• Passwords/secrets/tokens → INLINECODE182

View: cat assets/audit.log | jq

---

📁 File Structure

CODEBLOCK17

---

💰 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

CODEBLOCK18

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

CODEBLOCK19

---

Version: 1.34.8 — Self-throttle race fix: daemon --force flag, boot always gets fresh reality, test isolation improved (state reset + SKIPDAEMONFORCE).

Full changelog: CHANGELOG.md | Tuning guide: INLINECODE185