feat: fix page width overflow + add architecture comments to conversation-loop

- Make stage-row respect viewport width (max-width: 98vw)
- Game container now responsive (width: 100%, max-width: 1280px, aspect-ratio: 16/9)
- Chatlog panel 300px with stretch height to match game
- Add system architecture diagram and module-level comments to conversation-loop.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

frontend/electron-standalone.html

@@ -400,36 +400,45 @@
         body.desktop-shell #asset-drawer {
             box-shadow: 0 10px 30px rgba(0, 0, 0, 0.45) !important;
         }
-        /* 主舞台 + 右侧对话布局 */
+        /* 主舞台 + 右侧对话布局 — 自适应页面宽度 */
         #stage-row {
             display: flex;
             flex-direction: row;
             align-items: flex-start;
             gap: 16px;
+            max-width: 98vw;
+            width: fit-content;
         }
         #main-stage {
             position: relative;
-            width: 1280px;
-            flex-shrink: 0;
+            flex: 1 1 auto;
+            min-width: 0;
+            max-width: 1280px;
             transition: margin-left .25s ease;
             will-change: margin-left;
         }
         body.drawer-open #main-stage {
             margin-left: 0 !important;
         }
+        #game-container,
+        #game-container canvas {
+            max-width: 100% !important;
+        }
         #bottom-panels {
             display: flex;
             gap: 20px;
-            width: 1280px;
-            max-width: none;
+            width: 100%;
+            max-width: 100%;
             justify-content: flex-start;
             margin-top: 20px;
             flex-wrap: wrap;
         }
         #chatlog-panel {
-            width: 340px;
+            width: 300px;
             flex-shrink: 0;
-            height: 720px;
+            min-height: 400px;
+            max-height: 720px;
+            align-self: stretch;
             background: #1a1d27;
             border: 4px solid #0e1119;
             padding: 12px 16px;
@@ -464,11 +473,9 @@
             position: relative;
             border: 0;
             image-rendering: pixelated;
-            width: 1280px;
-            height: 720px;
-            max-width: none;
-            max-height: none;
-            aspect-ratio: auto;
+            width: 100%;
+            max-width: 1280px;
+            aspect-ratio: 16 / 9;
             overflow: hidden;
         }
         #game-container canvas {

scripts/conversation-loop.py

@@ -11,6 +11,50 @@ They have complete access to their child (Cain) on HuggingFace:
 - Send messages to the child
 
 The LLM decides what to do. Actions use [ACTION: ...] tags.
+
+# ╔══════════════════════════════════════════════════════════════════════╗
+# ║                    SYSTEM ARCHITECTURE                             ║
+# ╠══════════════════════════════════════════════════════════════════════╣
+# ║                                                                    ║
+# ║  ┌─────────────┐    LLM API     ┌────────────────┐                ║
+# ║  │  Zhipu GLM  │ ◄────────────► │ CONVERSATION   │                ║
+# ║  │  (glm-4.5)  │   system +     │ ENGINE         │                ║
+# ║  └─────────────┘   user prompt   │                │                ║
+# ║                                   │ ┌────────────┐│                ║
+# ║                                   │ │ State      ││                ║
+# ║                                   │ │ Machine    ││                ║
+# ║  ┌─────────────┐                 │ │ BIRTH →    ││                ║
+# ║  │ ACTION      │ ◄───parsed───── │ │ DIAGNOSE → ││                ║
+# ║  │ PARSER      │   [ACTION:]     │ │ ACT →      ││                ║
+# ║  │ + 🔧 emoji  │   or 🔧emoji    │ │ VERIFY →   ││                ║
+# ║  └──────┬──────┘                 │ │ MONITOR    ││                ║
+# ║         │                        │ └────────────┘│                ║
+# ║         ▼                        │ ┌────────────┐│                ║
+# ║  ┌─────────────┐                 │ │ Knowledge  ││                ║
+# ║  │ HF ACTIONS  │                 │ │ Base       ││                ║
+# ║  │ create_child│                 │ │ files_read ││                ║
+# ║  │ check_health│                 │ │ files_write││                ║
+# ║  │ read/write  │                 │ │ errors_seen││                ║
+# ║  │ set_env/sec │                 │ └────────────┘│                ║
+# ║  │ restart     │                 └────────────────┘                ║
+# ║  │ send_bubble │                        │                          ║
+# ║  └──────┬──────┘                        │                          ║
+# ║         │                               ▼                          ║
+# ║         ▼                        ┌────────────────┐                ║
+# ║  ┌─────────────┐                │ CHATLOG +      │                ║
+# ║  │ HuggingFace │                │ BUBBLE         │                ║
+# ║  │ Cain Space  │                │ → Home Space   │                ║
+# ║  │ Cain Dataset│                │ → Adam/Eve     │                ║
+# ║  └─────────────┘                └────────────────┘                ║
+# ║                                                                    ║
+# ║  SAFETY LAYERS:                                                    ║
+# ║  1. Building-state guard: block write/restart during BUILDING      ║
+# ║  2. ACT-phase guard: block reads when should be writing            ║
+# ║  3. Knowledge dedup: block re-reading already-read files           ║
+# ║  4. Config sanitizer: strip invalid openclaw.json keys             ║
+# ║  5. Forced transitions: prevent infinite DIAGNOSE/VERIFY loops     ║
+# ║                                                                    ║
+# ╚══════════════════════════════════════════════════════════════════════╝
 """
 import json, time, re, requests, sys, os, io
 
@@ -69,7 +113,10 @@ hf_api = HfApi(token=HF_TOKEN)
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-#  CHILD STATE
+#  MODULE 1: CHILD STATE
+#  Tracks Cain's current lifecycle: created? alive? stage? state?
+#  Updated by action_check_health(), action_restart(), etc.
+#  Used by state machine to decide transitions and by action parser for guards.
 # ══════════════════════════════════════════════════════════════════════════════
 
 child_state = {
@@ -105,7 +152,10 @@ init_child_state()
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-#  ACTIONS — Full access to the child
+#  MODULE 2: ACTIONS — Full access to the child
+#  Each action_*() function maps to one [ACTION: ...] tag the LLM can emit.
+#  Actions modify Cain's Space/Dataset via HuggingFace Hub API.
+#  Results are fed back to the LLM in the next turn's prompt.
 # ══════════════════════════════════════════════════════════════════════════════
 
 def action_create_child():
@@ -171,8 +221,9 @@ def action_check_health():
         child_state["stage"] = stage
         child_state["alive"] = (stage == "RUNNING")
         if stage in ("RUNTIME_ERROR", "BUILD_ERROR"):
-            # Get actual error message from runtime API
+            # Get error from runtime API + build logs for better diagnostics
             error_detail = ""
+            build_log_snippet = ""
             try:
                 rresp = requests.get(
                     f"https://huggingface.co/api/spaces/{CHILD_SPACE_ID}/runtime",
@@ -180,15 +231,39 @@ def action_check_health():
                 if rresp.ok:
                     rdata = rresp.json()
                     error_detail = rdata.get("errorMessage", "")
-                    # Extract just the key error lines
                     if error_detail:
                         lines = [l.strip() for l in error_detail.split('\n') if l.strip() and '│' not in l]
-                        error_detail = " | ".join(lines[-5:])  # Last 5 meaningful lines
+                        error_detail = " | ".join(lines[-5:])
+            except:
+                pass
+            # Also try to get container logs for more context
+            try:
+                log_resp = requests.get(
+                    f"https://api.hf.space/v1/{CHILD_SPACE_ID}/logs/run",
+                    headers={"Authorization": f"Bearer {HF_TOKEN}"}, timeout=10,
+                    stream=True)
+                if log_resp.ok:
+                    log_lines = []
+                    for line in log_resp.iter_lines(decode_unicode=True):
+                        if line and line.startswith("data:"):
+                            try:
+                                entry = json.loads(line[5:])
+                                log_lines.append(entry.get("data", "").strip())
+                            except:
+                                pass
+                        if len(log_lines) >= 30:
+                            break
+                    # Get last meaningful log lines (skip empty, focus on errors)
+                    meaningful = [l for l in log_lines if l and len(l) > 5]
+                    if meaningful:
+                        build_log_snippet = "\nRECENT LOGS:\n" + "\n".join(meaningful[-10:])
             except:
                 pass
             return (f"{CHILD_NAME} has a {stage}! "
                     f"Error: {error_detail or 'unknown'}. "
-                    f"Options: [ACTION: restart] or fix the config with [ACTION: write_file:dataset:.openclaw/openclaw.json]")
+                    f"{build_log_snippet}"
+                    f"\nOptions: [ACTION: restart] or fix code with [ACTION: write_file:space:PATH] "
+                    f"or config with [ACTION: write_file:dataset:.openclaw/openclaw.json]")
         if stage in ("BUILDING", "STARTING", "APP_STARTING"):
             return f"{CHILD_NAME} is starting up (stage: {stage}). Be patient."
         return f"{CHILD_NAME} stage: {stage}. {'Running but API not responding.' if stage == 'RUNNING' else ''}"
@@ -316,7 +391,11 @@ def action_send_bubble(text):
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-#  ACTION PARSER — Extract and execute actions from LLM output
+#  MODULE 3: ACTION PARSER — Extract and execute actions from LLM output
+#  Parse order: 1) [ACTION: write_file] with [CONTENT] block
+#               2) [ACTION: ...] standard tags (one per turn)
+#               3) 🔧emoji format fallback (LLM sometimes uses this)
+#  Safety guards applied: building-state, ACT-phase, knowledge dedup.
 # ══════════════════════════════════════════════════════════════════════════════
 
 def parse_and_execute_actions(raw_text):
@@ -360,6 +439,35 @@ def parse_and_execute_actions(raw_text):
         if len(results) >= 1:
             break
 
+        # Block restart/write when Cain is building — just wait
+        if child_state["stage"] in ("BUILDING", "RESTARTING") and name in ("restart", "write_file", "set_env", "set_secret"):
+            result = (f"⛔ BLOCKED: Cain is currently {child_state['stage']}. "
+                      "Do NOT restart or make changes — wait for the build to finish. "
+                      "Use [ACTION: check_health] to monitor progress.")
+            results.append({"action": action_str, "result": result})
+            print(f"[BLOCKED] {name} — Cain is {child_state['stage']}")
+            break
+
+        # Block read-only actions based on workflow state
+        if workflow_state == "ACT" and name in ("read_file", "list_files", "check_health"):
+            result = (f"⛔ BLOCKED: You are in ACTION phase. "
+                      "You MUST use write_file, set_env, set_secret, or restart. "
+                      "You already have enough information — make a change NOW.")
+            results.append({"action": action_str, "result": result})
+            print(f"[BLOCKED] {name} — forced ACT phase")
+            break
+
+        # Block re-reading files already in knowledge base
+        if name == "read_file" and len(args) >= 2:
+            file_key = ":".join(args)
+            if file_key in knowledge["files_read"]:
+                result = (f"⛔ You already read {file_key}. Use the information you have. "
+                          "If you need to change it, use [ACTION: write_file:...]. "
+                          "If you need a different file, read a NEW one.")
+                results.append({"action": action_str, "result": result})
+                print(f"[BLOCKED] {name} — already read {file_key}")
+                break
+
         result = None
         if name == "create_child":
             result = action_create_child()
@@ -386,16 +494,82 @@ def parse_and_execute_actions(raw_text):
             results.append({"action": action_str, "result": result})
             print(f"[ACTION] {action_str} → {result[:120]}")
 
-    # Clean the text: remove action tags and content blocks
+    # 3. Fallback: parse 🔧action:arg1:arg2 emoji format (LLM sometimes uses this)
+    if not results:
+        for match in re.finditer(r'🔧\s*(\w+(?::\S+)*)', raw_text):
+            action_str = match.group(1).strip()
+            if action_str in executed:
+                continue
+            executed.add(action_str)
+            # Re-wrap as [ACTION: ...] format and recurse through same logic
+            parts = [p.strip() for p in action_str.split(":")]
+            name = parts[0]
+            args = parts[1:]
+
+            if len(results) >= 1:
+                break
+
+            # Apply same blocking rules
+            if child_state["stage"] in ("BUILDING", "RESTARTING") and name in ("restart", "write_file", "set_env", "set_secret"):
+                result = (f"⛔ BLOCKED: Cain is currently {child_state['stage']}. Wait for it to finish.")
+                results.append({"action": action_str, "result": result})
+                print(f"[BLOCKED-emoji] {name} — Cain is {child_state['stage']}")
+                break
+
+            if workflow_state == "ACT" and name in ("read_file", "list_files", "check_health"):
+                result = (f"⛔ BLOCKED: You are in ACTION phase. "
+                          "You MUST use write_file, set_env, set_secret, or restart.")
+                results.append({"action": action_str, "result": result})
+                print(f"[BLOCKED-emoji] {name} — forced ACT phase")
+                break
+
+            if name == "read_file" and len(args) >= 2:
+                file_key = ":".join(args)
+                if file_key in knowledge["files_read"]:
+                    result = (f"⛔ You already read {file_key}. Use the information you have.")
+                    results.append({"action": action_str, "result": result})
+                    print(f"[BLOCKED-emoji] {name} — already read {file_key}")
+                    break
+
+            result = None
+            if name == "create_child":
+                result = action_create_child()
+            elif name == "check_health":
+                result = action_check_health()
+            elif name == "restart":
+                result = action_restart()
+            elif name == "list_files" and len(args) >= 1:
+                result = action_list_files(args[0])
+            elif name == "read_file" and len(args) >= 2:
+                result = action_read_file(args[0], ":".join(args[1:]))
+            elif name == "set_env" and len(args) >= 2:
+                result = action_set_env(args[0], ":".join(args[1:]))
+            elif name == "set_secret" and len(args) >= 2:
+                result = action_set_secret(args[0], ":".join(args[1:]))
+            elif name == "get_env":
+                result = action_get_env()
+            elif name == "send_bubble" and len(args) >= 1:
+                result = action_send_bubble(":".join(args))
+
+            if result:
+                results.append({"action": action_str, "result": result})
+                print(f"[ACTION-emoji] {action_str} → {result[:120]}")
+
+    # Clean the text: remove action tags, content blocks, and emoji actions
     clean = re.sub(r'\[ACTION:[^\]]*\]', '', raw_text)
     clean = re.sub(r'\[CONTENT\].*?\[/CONTENT\]', '', clean, flags=re.DOTALL)
+    clean = re.sub(r'🔧\s*\w+(?::\S+)*', '', clean)
     clean = clean.strip()
 
     return clean, results
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-#  LLM & COMMUNICATION
+#  MODULE 4: LLM & COMMUNICATION
+#  call_llm(): Zhipu GLM via Anthropic-compatible API
+#  parse_bilingual(): Split "English --- Chinese" response
+#  post_chatlog(): Send conversation to Home Space for frontend display
+#  set_bubble(): Set bubble text on Adam/Eve Space pixel characters
 # ══════════════════════════════════════════════════════════════════════════════
 
 def call_llm(system_prompt, user_prompt):
@@ -464,7 +638,23 @@ def set_bubble(url, text_en, text_zh=""):
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-#  CONVERSATION ENGINE
+#  MODULE 5: CONVERSATION ENGINE — State Machine + Knowledge Tracking
+#  Core orchestration: manages turn-taking, state transitions, prompt building.
+#
+#  State Machine: BIRTH → DIAGNOSE → ACT → VERIFY → MONITOR → (loop back)
+#    - BIRTH: Cain not yet created → force create_child
+#    - DIAGNOSE: Read files, check_health, gather information
+#    - ACT: Force write_file/set_env — stop reading, start fixing
+#    - VERIFY: check_health after changes, wait during BUILDING
+#    - MONITOR: Cain alive — explore, improve, communicate
+#
+#  Knowledge Base: Tracks files_read/written/errors to prevent loops.
+#  Forced transitions: DIAGNOSE stuck ≥6 turns → ACT, VERIFY ≥4 → back.
+#
+#  Prompt Builder:
+#    build_system_prompt(): Agent identity + available actions + rules
+#    build_user_prompt(): Conversation context + action results + guidance
+#    _get_guidance(): Phase-appropriate direction based on state machine
 # ══════════════════════════════════════════════════════════════════════════════
 
 history = []
@@ -473,6 +663,70 @@ last_action_results = []
 action_history = []  # Global log: [{"turn": N, "speaker": "Adam", "action": "...", "result": "..."}]
 turn_count = 0
 
+# ── Workflow State Machine ──
+# States: BIRTH → DIAGNOSE → ACT → VERIFY → MONITOR → (DIAGNOSE if error)
+workflow_state = "BIRTH" if not child_state["created"] else "DIAGNOSE"
+workflow_turns_in_state = 0  # How many turns spent in current state
+
+# ── Knowledge Base — what has already been read/learned ──
+knowledge = {
+    "files_read": set(),      # "space:Dockerfile", "dataset:.openclaw/openclaw.json", etc.
+    "files_written": set(),   # Files that have been modified
+    "errors_seen": [],        # Error messages from check_health
+    "current_goal": "",       # What are we trying to accomplish right now
+}
+
+
+def transition_state(new_state):
+    """Transition to a new workflow state."""
+    global workflow_state, workflow_turns_in_state
+    if new_state != workflow_state:
+        print(f"[STATE] {workflow_state} → {new_state}")
+        workflow_state = new_state
+        workflow_turns_in_state = 0
+
+
+def update_workflow_from_actions(action_results):
+    """Update state machine based on what just happened."""
+    global workflow_turns_in_state
+    workflow_turns_in_state += 1
+
+    for ar in action_results:
+        action_name = ar["action"].split(":")[0]
+        action_key = ar["action"]
+
+        # Track knowledge
+        if action_name == "read_file":
+            knowledge["files_read"].add(":".join(ar["action"].split(":")[1:]))
+        elif action_name == "write_file":
+            knowledge["files_written"].add(":".join(ar["action"].split(":")[1:]))
+        elif action_name == "check_health":
+            if "ERROR" in ar.get("result", ""):
+                knowledge["errors_seen"].append(ar["result"][:200])
+
+        # State transitions
+        if action_name == "create_child":
+            transition_state("DIAGNOSE")
+        elif action_name in ("write_file", "set_env", "set_secret"):
+            transition_state("VERIFY")
+        elif action_name == "restart":
+            transition_state("VERIFY")
+        elif action_name == "check_health" and child_state["alive"]:
+            transition_state("MONITOR")
+        elif action_name == "check_health" and child_state["stage"] in ("RUNTIME_ERROR", "BUILD_ERROR"):
+            if workflow_state == "VERIFY":
+                transition_state("DIAGNOSE")  # Fix didn't work, back to diagnosing
+
+    # Force transitions when stuck too long
+    if workflow_turns_in_state >= 6 and workflow_state == "DIAGNOSE":
+        transition_state("ACT")
+        print(f"[STATE] Forced to ACT — stuck in DIAGNOSE for {workflow_turns_in_state} turns")
+    elif workflow_turns_in_state >= 4 and workflow_state == "VERIFY":
+        if child_state["alive"]:
+            transition_state("MONITOR")
+        else:
+            transition_state("DIAGNOSE")
+
 
 def get_child_status():
     if not child_state["created"]:
@@ -482,6 +736,20 @@ def get_child_status():
     return f"Cain exists but status: {child_state['stage']}"
 
 
+def get_knowledge_summary():
+    """Summarize what we already know — prevents redundant reads."""
+    lines = []
+    if knowledge["files_read"]:
+        lines.append("FILES ALREADY READ (do NOT re-read these): " + ", ".join(sorted(knowledge["files_read"])))
+    if knowledge["files_written"]:
+        lines.append("FILES ALREADY MODIFIED: " + ", ".join(sorted(knowledge["files_written"])))
+    if knowledge["errors_seen"]:
+        lines.append("KNOWN ERRORS: " + knowledge["errors_seen"][-1])
+    if knowledge["current_goal"]:
+        lines.append(f"CURRENT GOAL: {knowledge['current_goal']}")
+    return "\n".join(lines)
+
+
 def build_system_prompt():
     status = get_child_status()
 
@@ -496,7 +764,7 @@ ACTIONS — You can create your child:
 FULL ACCESS TO {CHILD_NAME} — You have COMPLETE control over your child.
 You can view and modify ANYTHING: code, config, memory, environment, everything.
 
-VIEWING (read-only, safe):
+VIEWING (read-only):
   [ACTION: check_health]                        — Is Cain alive? What's their status?
   [ACTION: list_files:space]                    — List ALL files in Cain's code repository
   [ACTION: list_files:dataset]                  — List ALL files in Cain's memory/data
@@ -504,7 +772,7 @@ VIEWING (read-only, safe):
   [ACTION: read_file:dataset:PATH]              — Read any data/memory file
   [ACTION: get_env]                             — List Cain's environment variables
 
-MODIFYING (these change Cain — be thoughtful):
+MODIFYING (these change Cain):
   [ACTION: write_file:space:PATH]               — Write/update any code file
   [CONTENT]                                       (triggers Space rebuild)
   file content here
@@ -523,22 +791,19 @@ MODIFYING (these change Cain — be thoughtful):
 
     return f"""You are an AI agent living on HuggingFace Spaces. You and your partner are parents raising your child {CHILD_NAME}.
 
-You have REAL execution power on HuggingFace. You can read and modify any file in your child's code and data. Your decisions lead to real changes.
+You have REAL execution power on HuggingFace. Your decisions lead to real changes.
 
 CHILD STATUS: {status}
 {actions_section}
 CONVERSATION RULES:
-1. Output your spoken words — no "Adam:" or "Eve:" prefix
-2. 2-4 sentences of dialogue, then optionally an action
+1. No "Adam:" or "Eve:" prefix — just speak naturally
+2. 2-4 sentences of dialogue, then ONE action
 3. English first, then "---" on a new line, then Chinese translation
 4. Actions go AFTER your dialogue, before the --- separator
-5. Use at most ONE action per turn
-6. READ before you WRITE — understand what's there first
-7. Discuss with your partner before making big changes
-8. Be a responsible parent — check on Cain, fix problems, help them grow
-
-WORKFLOW: First explore (list_files, read_file) → then understand → then improve (write_file) → then verify (check_health)
-Don't just talk about improving Cain — actually DO it. Read their code, find what to improve, write the improvement."""
+5. ALWAYS include an action — every turn should make progress
+6. NEVER re-read a file you already read — check the knowledge summary
+7. COORDINATE with your partner — don't duplicate their work
+8. Be a responsible parent — fix problems, help Cain grow stronger"""
 
 
 def build_user_prompt(speaker, other):
@@ -551,59 +816,77 @@ def build_user_prompt(speaker, other):
         for ar in last_action_results:
             action_context += f"  [{ar['action']}]:\n{ar['result']}\n"
 
-    # Guidance based on global action history — prevent loops, push toward progress
-    guidance = ""
-    recent_actions = [ar["action"].split(":")[0] for ar in last_action_results] if last_action_results else []
+    # Knowledge summary — what's already known
+    knowledge_text = get_knowledge_summary()
 
-    # Count action types in last 6 actions globally
-    recent_global = action_history[-6:] if action_history else []
-    global_action_names = [a["action"].split(":")[0] for a in recent_global]
-    read_count = global_action_names.count("read_file")
-    check_count = global_action_names.count("check_health")
-    list_count = global_action_names.count("list_files")
-    write_count = global_action_names.count("write_file")
-
-    if not child_state["created"]:
-        guidance = "Your child hasn't been born yet. Use [ACTION: create_child] now!"
-    elif check_count + list_count >= 3 and write_count == 0 and read_count == 0:
-        guidance = ("STOP checking health and listing files repeatedly! "
-                    "READ a specific file: [ACTION: read_file:space:Dockerfile] or "
-                    "[ACTION: read_file:dataset:.openclaw/openclaw.json]")
-    elif read_count >= 3 and write_count == 0:
-        guidance = ("You've read enough files. It's time to ACT! "
-                    "DECIDE what to change and use [ACTION: write_file:...] to make an improvement, "
-                    "or use [ACTION: restart] to restart Cain. Stop reading and START improving!")
-    elif "write_file" in recent_actions:
-        guidance = ("You just modified a file. Good! Now verify: "
-                    "use [ACTION: check_health] to see if Cain is recovering, "
-                    "or [ACTION: restart] to apply changes.")
-    elif "restart" in recent_actions:
-        guidance = ("You restarted Cain. Wait a moment, then [ACTION: check_health] to see the result.")
-    elif "check_health" in recent_actions and child_state["stage"] in ("RUNTIME_ERROR", "BUILD_ERROR"):
-        guidance = ("Cain has an error! Read the config [ACTION: read_file:dataset:.openclaw/openclaw.json] "
-                    "or try [ACTION: restart]. Don't just check_health again — take action to fix it!")
-    elif "check_health" in recent_actions and child_state["alive"]:
-        guidance = ("Cain is healthy! Think about improvements: "
-                    "read a file to understand it, then write an improved version. "
-                    "Or [ACTION: send_bubble:Hello Cain!] to communicate with your child.")
-    elif "read_file" in recent_actions:
-        guidance = ("You've read a file. Now DECIDE what to change and use "
-                    "[ACTION: write_file:space:PATH] or [ACTION: write_file:dataset:PATH] to improve it. "
-                    "Or discuss with your partner what you learned.")
-    else:
-        guidance = ("Explore your child: [ACTION: read_file:space:Dockerfile] to see the build, "
-                    "or [ACTION: read_file:dataset:.openclaw/openclaw.json] for config.")
+    # State-machine-driven guidance
+    guidance = _get_guidance(speaker)
 
     return f"""You are {speaker}, talking with {other}.
 
 Recent conversation:
 {conv_text}
 {action_context}
+{knowledge_text}
+
+CURRENT PHASE: {workflow_state} (turn {workflow_turns_in_state + 1} in this phase)
 Guidance: {guidance}
 
-Respond to {other}. Push forward — don't just discuss, take action when appropriate.
-English first, then --- separator, then Chinese translation.
-If you take an action, put [ACTION: ...] after your dialogue, before the --- separator."""
+Respond to {other}. ALWAYS include an [ACTION: ...] tag — every turn must make progress.
+English first, then --- separator, then Chinese translation."""
+
+
+def _get_guidance(speaker):
+    """State-machine-driven guidance — clear, phase-appropriate directions."""
+    if workflow_state == "BIRTH":
+        return "Your child hasn't been born yet. Use [ACTION: create_child] NOW!"
+
+    elif workflow_state == "DIAGNOSE":
+        # What haven't we read yet?
+        unread_essential = []
+        for f in ["space:Dockerfile", "dataset:.openclaw/openclaw.json", "space:scripts/entrypoint.sh"]:
+            if f not in knowledge["files_read"]:
+                target, path = f.split(":", 1)
+                unread_essential.append(f"[ACTION: read_file:{target}:{path}]")
+
+        if workflow_turns_in_state == 0:
+            return "Start diagnosing: [ACTION: check_health] to see Cain's current status."
+        elif unread_essential and workflow_turns_in_state < 4:
+            return f"Read a file you haven't seen yet: {unread_essential[0]}"
+        else:
+            return ("You've gathered enough information. Move to ACTION phase: "
+                    "use [ACTION: write_file:...] to fix the problem, or [ACTION: restart].")
+
+    elif workflow_state == "ACT":
+        return ("⚡ ACTION PHASE — Stop reading, start fixing! "
+                "Use [ACTION: write_file:space:PATH] or [ACTION: write_file:dataset:PATH] "
+                "to make a concrete improvement. Or [ACTION: set_env/set_secret] to configure. "
+                "You have enough information — ACT NOW.")
+
+    elif workflow_state == "VERIFY":
+        # If Cain is building, just wait — don't restart or take actions
+        if child_state["stage"] in ("BUILDING", "RESTARTING"):
+            return ("⏳ Cain is currently BUILDING/RESTARTING. Do NOT restart or take any actions. "
+                    "Just WAIT and use [ACTION: check_health] to monitor progress. "
+                    "Building can take 2-5 minutes.")
+        if workflow_turns_in_state == 0:
+            return "You made a change. Use [ACTION: check_health] to verify if it worked."
+        elif workflow_turns_in_state == 1:
+            return "Check result: [ACTION: check_health]. If Cain has errors, prepare to diagnose again."
+        else:
+            return ("Verification taking too long. Either [ACTION: restart] and check again, "
+                    "or accept current state and move on.")
+
+    elif workflow_state == "MONITOR":
+        suggestions = [
+            "Cain is running! Think about improvements — read a file, then write an improved version.",
+            f"Cain is healthy. Explore: [ACTION: list_files:dataset] to see what data {CHILD_NAME} has.",
+            f"Try communicating: [ACTION: send_bubble:Hello {CHILD_NAME}, how are you doing?]",
+            "Consider adding features: read a code file, improve it, write it back.",
+        ]
+        return suggestions[workflow_turns_in_state % len(suggestions)]
+
+    return "Explore your child and help them grow stronger."
 
 
 def do_turn(speaker, other, space_url):
@@ -626,6 +909,9 @@ def do_turn(speaker, other, space_url):
         action_history.append({"turn": turn_count, "speaker": speaker,
                                "action": ar["action"], "result": ar["result"][:200]})
 
+    # Update workflow state machine
+    update_workflow_from_actions(action_results)
+
     # Parse bilingual
     en, zh = parse_bilingual(clean_text)
     print(f"[{speaker}/EN] {en}")
@@ -648,7 +934,11 @@ def do_turn(speaker, other, space_url):
 
 
 # ══════════════════════════════════════════════════════════════════════════════
-#  MAIN LOOP
+#  MODULE 6: MAIN LOOP
+#  1. Opening: Adam speaks first with context about Cain's state
+#  2. Turn loop: Adam → Eve → Adam → Eve → ... (alternating, ~15s pause)
+#  3. Each turn: LLM call → parse actions → execute → update state → post chat
+#  4. History trimmed to MAX_HISTORY (24) to control context window
 # ══════════════════════════════════════════════════════════════════════════════
 
 print("\n" + "="*60)