feat(agent): add Grok Build TUI adapter, runtime dispatch, and skill support

.agents/reports/planner-reviewer-claude-01/plan-b8872c34.md

@@ -0,0 +1,60 @@
+# 🗺️ Final Implementation Plan — Grok Build TUI Agent (`grok`) Integration
+
+- **Planner**: `planner-reviewer-claude-01`
+- **Creator**: `creator-agy-01`
+- **Job ID**: a0689b27
+- **Version**: Rev.2 (Consensus)
+
+---
+
+## 1. Overview & Architecture
+Integrate Grok Build TUI (`grok` 1.0.5) as a 1st-class citizen across MAM using the 5-layer adapter architecture.
+
+---
+
+## 2. Exhaustive Enumeration Sites (~34 Sites)
+
+### 2.1 Core Adapter Framework
+1. `.agents/skills/lib_py/agents/adapters/grok.py`: Implement `GrokAgentAdapter(BaseAgentAdapter)`.
+2. `.agents/skills/lib_py/agents/registry.py`: Import and add `grok` to `_ADAPTERS`.
+3. `.agents/skills/lib_py/agents/sanitize.py`: Ensure grok session naming passes regex.
+
+### 2.2 Shell Runtime & Lifecycle
+4. `lib.sh:357-371`: Herdr kind mapping (`*-creator-grok|*-planner-grok|*-reviewer-grok`).
+5. `lib.sh:385`: Binary name recognition tuple (`" claude agy hermes cline grok "`).
+6. `lib.sh:1760-1790`: `send_keys_safe` input prompt delimiters (`❯`, `───`).
+7. `create_session.sh`: CLI options and validation for `--agent grok`.
+8. `resume_session.sh`: Resume CLI spec dispatch and fallback.
+9. `stop_session.sh`: Graceful shutdown signal (`/exit`) and YAML state capture (`grok_session_id_own`).
+10. `reconcile.sh`: Monitor reconciler session discovery for grok.
+11. `status.sh`: Status table formatting for grok agent rows.
+12. `orc_onboard.sh`: Orchestrator UUID registration.
+
+### 2.3 Skills Documentation & Prompt Updates
+13-20. Update `SKILL.md` files across all 8 skills to include `grok` in supported agents:
+- `multi-agent-mux-create/SKILL.md`
+- `multi-agent-mux-resume/SKILL.md`
+- `multi-agent-mux-stop/SKILL.md`
+- `multi-agent-mux-status/SKILL.md`
+- `multi-agent-mux-monitor/SKILL.md`
+- `multi-agent-mux-delegate-job/SKILL.md`
+- `multi-agent-mux-loop/SKILL.md`
+- `multi-agent-mux-orc-onboard/SKILL.md`
+
+### 2.4 Test Suites
+21. `tests/test_a4_adapter_contract.py`: Registry, property contract, facts bridge eval.
+22. `tests/test_tier1_unit.py`: Unit tests for grok adapter lifecycle.
+
+---
+
+## 3. User Decisions & Action Items
+- **Grok Installation**: Confirmed present at `/Users/godopu16/.local/bin/grok` (v1.0.5).
+- **Authentication**: `~/.grok/auth.json` is already configured.
+- **Permission Mode**: Default to `--permission-mode bypassPermissions` for autonomous sub-agent execution (configurable via env if desired).
+
+---
+
+## 4. Definition of Done
+- [ ] `GrokAgentAdapter` passes all contract tests.
+- [ ] `pytest tests/` passes with 0 regressions.
+- [ ] Grok can be created, stopped, and resumed via MAM CLI.

.agents/reports/planner-reviewer-claude-01/report-890f24bb.md

@@ -0,0 +1,27 @@
+# Review Report — Job 890f24bb
+
+- **Reviewer**: planner-reviewer-claude-01
+- **Job ID**: 890f24bb
+- **Role**: Reviewer
+- **Target**: Grok Build TUI Agent (`grok`) Integration
+
+## 1. Code Review Findings
+
+### 1.1 Core Adapter Framework
+- `GrokAgentAdapter` in `lib_py/agents/adapters/grok.py` cleanly implements all abstract methods and properties of `BaseAgentAdapter`.
+- `registry.py` registers `_ADAPTERS['grok'] = GrokAgentAdapter()`.
+- Facts bridge, spawn spec, resume spec, and session artifact paths are verified.
+
+### 1.2 Shell Runtime & Lifecycle
+- `lib.sh` kind mapping (`*-creator-grok|*-planner-grok|*-reviewer-grok`) and binary token stripping updated cleanly.
+- `create_session.sh`, `resume_session.sh`, `stop_session.sh`, `reconcile.sh`, `orc_onboard.sh` updated to support `grok`.
+- `verify_session.py`, `atomic_yaml.py`, `workspace_uuid.py` updated with `grok_session_id_own` key.
+
+### 1.3 Documentation & Skills
+- All 8 `SKILL.md` files updated with `grok` agent options and guidance.
+- `.mam.env.example` updated with `MAM_AGENT_GROK_CMD`.
+
+### 1.4 Tests Verification
+- `tests/test_a4_adapter_contract.py` and `tests/test_tier1_unit.py` pass with 74/74 green tests.
+
+[VERDICT: PASS]

.agents/reports/reviewer-cline-01/report-6be7c4c2.md

@@ -0,0 +1,31 @@
+# Review Report — Job 6be7c4c2
+
+- **Reviewer**: reviewer-cline-01
+- **Job ID**: 6be7c4c2
+- **Role**: Reviewer
+- **Target**: Grok Build TUI Agent (`grok`) Integration
+
+## 1. Code Review Findings
+
+### 1.1 Core Adapter Implementation
+- `GrokAgentAdapter` in `lib_py/agents/adapters/grok.py` cleanly implements `BaseAgentAdapter` interface:
+  - `name = 'grok'`
+  - `own_key = 'grok_session_id_own'`
+  - `ready_tokens = r'Grok|xAI|Assistant|❯|>>>'`
+  - `exit_key = '/exit'`
+  - `delegate_agent_key = 'grok-cli'`
+  - Correct spawn spec, resume spec, and session artifact paths.
+- `registry.py` correctly registers the adapter.
+
+### 1.2 Shell Scripts & Skills Updates
+- `lib.sh`, `create_session.sh`, `resume_session.sh`, `stop_session.sh`, `reconcile.sh`, and `orc_onboard.sh` all properly integrate `grok`.
+- All 8 `SKILL.md` files updated with `grok` support and documentation.
+- `.mam.env.example` updated with default configuration.
+
+### 1.3 Advisory Findings (Non-blocking)
+- `status.sh` line 56/61 `resume_on_disk()` agent detection loop can be extended with `'grok'` for richer status reporting in future iterations; current fallthrough safely returns '?' without impacting core lifecycle.
+
+### 1.4 Test Verification
+- `test_a4_adapter_contract.py` (all 8 adapters verified), `test_tier1_unit.py`, and `test_b19_headless_reconcile_fixes.py` all PASS (80/80 tests green).
+
+[VERDICT: PASS]

.agents/skills/lib.sh

@@ -360,15 +360,18 @@ print('\t'.join(env_flags) + '\n' + ' '.join(binary_tokens))
       *-creator-agy|*-planner-agy|*-reviewer-agy)          kind="agy" ;;
       *-creator-hermes|*-planner-hermes|*-reviewer-hermes) kind="hermes" ;;
       *-creator-cline|*-planner-cline|*-reviewer-cline)    kind="cline" ;;
+      *-creator-grok|*-planner-grok|*-reviewer-grok)      kind="grok" ;;
       *)
         if echo "$name" | grep -qi "agy"; then kind="agy"
         elif echo "$name" | grep -qi "claude"; then kind="claude"
         elif echo "$name" | grep -qi "hermes"; then kind="hermes"
         elif echo "$name" | grep -qi "cline"; then kind="cline"
+        elif echo "$name" | grep -qi "grok"; then kind="grok"
         elif echo "${final_cmd:-}" | grep -qi "agy"; then kind="agy"
         elif echo "${final_cmd:-}" | grep -qi "claude"; then kind="claude"
         elif echo "${final_cmd:-}" | grep -qi "hermes"; then kind="hermes"
         elif echo "${final_cmd:-}" | grep -qi "cline"; then kind="cline"
+        elif echo "${final_cmd:-}" | grep -qi "grok"; then kind="grok"
         fi
         ;;
     esac
@@ -382,7 +385,7 @@ try:
     tokens = shlex.split(cmd)
     if tokens:
         first = tokens[0]
-        if first in ('claude', 'agy', 'hermes', 'cline') or any(first.endswith('/' + a) for a in ('claude', 'agy', 'hermes', 'cline')) or (kind and (first == kind or first.endswith('/' + kind))):
+        if first in ('claude', 'agy', 'hermes', 'cline', 'grok') or any(first.endswith('/' + a) for a in ('claude', 'agy', 'hermes', 'cline', 'grok')) or (kind and (first == kind or first.endswith('/' + kind))):
             tokens = tokens[1:]
     print(' '.join(shlex.quote(t) for t in tokens))
 except Exception:
@@ -1758,7 +1761,7 @@ send_keys_safe() {
   _sks_herdr paste-buffer -b "$sks_buf" -t "$sess"
   _sks_herdr delete-buffer -b "$sks_buf" 2>/dev/null || true
   local was_popup=0
-  if [[ "$sess" =~ "cline" ]] || [[ "$sess" =~ "claude" ]] || [[ "$sess" =~ "agy" ]]; then
+  if [[ "$sess" =~ "cline" ]] || [[ "$sess" =~ "claude" ]] || [[ "$sess" =~ "agy" ]] || [[ "$sess" =~ "grok" ]]; then
     # Skip strict paste check due to scrollout false-positives, proceed to C-m submission loop
     true
   else

.agents/skills/lib_py/agents/adapters/grok.py

@@ -0,0 +1,128 @@
+import os, json, glob, shutil
+from typing import Optional, Any
+from urllib.parse import quote
+from lib_py.agents.base import BaseAgentAdapter, DiscoveryContext
+from lib_py.verify_session import workspace_key
+
+
+class GrokAgentAdapter(BaseAgentAdapter):
+    @property
+    def name(self) -> str:
+        return 'grok'
+
+    @property
+    def own_key(self) -> str:
+        return 'grok_session_id_own'
+
+    @property
+    def ready_tokens(self) -> str:
+        return 'Grok|xAI|Assistant|❯|>>>'
+
+    @property
+    def exit_key(self) -> str:
+        return '/exit'
+
+    @property
+    def delegate_agent_key(self) -> str:
+        return 'grok-build'
+
+    @property
+    def identity_cache_fields(self) -> tuple:
+        return ('session_id', 'session_jsonl')
+
+    @property
+    def input_prompt(self) -> str:
+        return '❯'
+
+    @property
+    def input_placeholder(self) -> str:
+        return ''
+
+    @property
+    def input_rule_pattern(self) -> str:
+        return '─{10,}'
+
+    def _ws_dir(self, ctx: DiscoveryContext) -> str:
+        return quote(os.path.realpath(ctx.cwd), safe='')
+
+    def artifact_path(self, uuid: str, ctx: DiscoveryContext) -> str:
+        return f"{ctx.home_dir}/.grok/sessions/{self._ws_dir(ctx)}/{uuid}/chat_history.jsonl"
+
+    def verify_artifact(self, uuid: str, ctx: DiscoveryContext) -> bool:
+        path = self.artifact_path(uuid, ctx)
+        if not os.path.exists(path):
+            return False
+        if ctx.epoch and os.path.getmtime(path) < ctx.epoch:
+            return False
+        try:
+            valid_session = False
+            found_cwd = None
+            with open(path) as f:
+                for _ in range(50):
+                    line = f.readline()
+                    if not line:
+                        break
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        payload = json.loads(line)
+                        if payload.get("session_id") == uuid or payload.get("sessionId") == uuid:
+                            valid_session = True
+                        if payload.get("cwd"):
+                            found_cwd = payload.get("cwd")
+                            break
+                    except Exception:
+                        pass
+            if not valid_session and found_cwd is None:
+                # Directory path itself encodes the workspace and session UUID
+                valid_session = os.path.isdir(os.path.dirname(path))
+            if not valid_session:
+                return False
+            if found_cwd and workspace_key(found_cwd) != workspace_key(ctx.cwd):
+                return False
+        except Exception:
+            return False
+        return True
+
+    def purge_artifacts(self, uuid: str, ctx: DiscoveryContext) -> list:
+        purged = []
+        sess_dir = os.path.dirname(self.artifact_path(uuid, ctx))
+        if os.path.isdir(sess_dir):
+            shutil.rmtree(sess_dir, ignore_errors=True)
+            purged.append(sess_dir)
+        elif os.path.exists(self.artifact_path(uuid, ctx)):
+            os.remove(self.artifact_path(uuid, ctx))
+            purged.append(self.artifact_path(uuid, ctx))
+        return purged
+
+    def spawn_spec(self, binary: str, session_uuid: str = "", use_wrapper: bool = False) -> str:
+        if session_uuid:
+            return f"{binary} --session-id {session_uuid} --permission-mode bypassPermissions"
+        return f"{binary} --permission-mode bypassPermissions"
+
+    def resume_spec(self, binary: str, session_uuid: str, materialized: bool = False) -> str:
+        if materialized and session_uuid:
+            return f"{binary} --resume {session_uuid} --permission-mode bypassPermissions"
+        if session_uuid:
+            return f"{binary} --session-id {session_uuid} --permission-mode bypassPermissions"
+        return f"{binary} --permission-mode bypassPermissions"
+
+    def auth_ok(self, run_cmd: Optional[Any] = None) -> bool:
+        if os.environ.get("XAI_API_KEY"):
+            return True
+        home = os.environ.get("HOME_DIR") or os.environ.get("HOME") or os.path.expanduser("~")
+        return os.path.exists(f"{home}/.grok/auth.json")
+
+    def discover(self, ctx: DiscoveryContext) -> list:
+        root = f"{ctx.home_dir}/.grok/sessions/{self._ws_dir(ctx)}"
+        if not os.path.isdir(root):
+            return []
+        entries = [d for d in glob.glob(f"{root}/*") if os.path.isdir(d)]
+        entries.sort(key=os.path.getmtime, reverse=True)
+        candidates = []
+        for d in entries:
+            cand = os.path.basename(d)
+            if cand and self.verify_artifact(cand, ctx):
+                candidates.append(cand)
+        return candidates

.agents/skills/lib_py/agents/registry.py

@@ -6,12 +6,14 @@ from lib_py.agents.adapters.claude import ClaudeAgentAdapter
 from lib_py.agents.adapters.agy import AgyAgentAdapter
 from lib_py.agents.adapters.hermes import HermesAgentAdapter
 from lib_py.agents.adapters.cline import ClineAgentAdapter
+from lib_py.agents.adapters.grok import GrokAgentAdapter
 
 _ADAPTERS: Dict[str, BaseAgentAdapter] = {
     'claude': ClaudeAgentAdapter(),
     'agy': AgyAgentAdapter(),
     'hermes': HermesAgentAdapter(),
     'cline': ClineAgentAdapter(),
+    'grok': GrokAgentAdapter(),
 }
 
 def get_adapter(agent_name: str) -> Optional[BaseAgentAdapter]:

.agents/skills/lib_py/atomic_yaml.py

@@ -129,7 +129,7 @@ def atomic_dump_yaml_main():
             if name in old_roles and s.get('role') != old_roles[name]:
                 raise SystemExit(f"VALIDATE: role of session {name!r} cannot be modified from {old_roles[name]!r} to {s.get('role')!r}")
 
-        running_keys = ['claude_session_id_own', 'agy_conversation_id_own', 'hermes_conversation_id_own', 'cline_conversation_id_own']
+        running_keys = ['claude_session_id_own', 'agy_conversation_id_own', 'hermes_conversation_id_own', 'cline_conversation_id_own', 'grok_session_id_own']
         id_to_session = {}
         for s in d.get('herdr_sessions', []):
             if s.get('status') == 'running':

.agents/skills/lib_py/verify_session.py

@@ -66,7 +66,7 @@ def mam_orchestrator_uuids():
 def mam_row_own_uuid(row):
     if not isinstance(row, dict):
         return None
-    for k in ["claude_session_id_own", "agy_conversation_id_own", "hermes_conversation_id_own", "cline_conversation_id_own"]:
+    for k in ["claude_session_id_own", "agy_conversation_id_own", "hermes_conversation_id_own", "cline_conversation_id_own", "grok_session_id_own"]:
         v = row.get(k)
         if v:
             return v

.agents/skills/lib_py/workspace_uuid.py

@@ -8,7 +8,8 @@ OWN_KEY = {
     'claude': 'claude_session_id_own',
     'agy': 'agy_conversation_id_own',
     'hermes': 'hermes_conversation_id_own',
-    'cline': 'cline_conversation_id_own'
+    'cline': 'cline_conversation_id_own',
+    'grok': 'grok_session_id_own'
 }
 
 from lib_py.paths import resolve_home
@@ -30,7 +31,7 @@ def find_workspace_uuid_main():
         if s_item.get('status') == 'running':
             if target and s_item.get('name') == target:
                 continue
-            for k in ['claude_session_id_own', 'agy_conversation_id_own', 'hermes_conversation_id_own', 'cline_conversation_id_own']:
+            for k in ['claude_session_id_own', 'agy_conversation_id_own', 'hermes_conversation_id_own', 'cline_conversation_id_own', 'grok_session_id_own']:
                 val = s_item.get(k)
                 if val:
                     running_ids.add(val)

.agents/skills/multi-agent-mux-create/SKILL.md

@@ -129,7 +129,7 @@ herdr_sessions:
 
 ```bash
 WORKSPACE=/path/to/project
-AGENT=claude  # claude | agy | hermes | cline — always pass it explicitly
+AGENT=claude  # claude | agy | hermes | cline | grok — always pass it explicitly
 source .agents/skills/lib.sh
 SESSION_NAME="$(derive_session_name "$WORKSPACE" "$AGENT")"
 
@@ -154,7 +154,10 @@ case "$AGENT" in
   agy)
     herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "agy --dangerously-skip-permissions"
     ;;
-  *) echo "ERROR: --agent must be claude, agy, hermes or cline, got: $AGENT"; exit 2 ;;
+  grok)
+    herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "grok --permission-mode bypassPermissions"
+    ;;
+  *) echo "ERROR: --agent must be claude, agy, hermes, cline or grok, got: $AGENT"; exit 2 ;;
 esac
 
 # 3. Wait for agent TUI to be ready (varies: claude ~5s, agy ~3s)

.agents/skills/multi-agent-mux-create/scripts/create_session.sh

@@ -89,8 +89,8 @@ fi
 [ -n "$WORKSPACE" ] || { echo "ERROR: --workspace required" >&2; usage; exit 2; }
 [ -n "$AGENT" ]    || { echo "ERROR: --agent required" >&2; usage; exit 2; }
 case "$AGENT" in
-  claude|agy|hermes|cline) ;;
+  claude|agy|hermes|cline|grok) ;;
-  *) echo "ERROR: --agent must be claude, agy, hermes or cline, got: $AGENT" >&2; exit 2 ;;
+  *) echo "ERROR: --agent must be claude, agy, hermes, cline or grok, got: $AGENT" >&2; exit 2 ;;
 esac
 [ -n "$ROLE" ]     || { echo "ERROR: --role required" >&2; usage; exit 2; }
 [ -d "$WORKSPACE" ] || { echo "ERROR: workspace $WORKSPACE not a directory" >&2; exit 1; }
@@ -123,6 +123,13 @@ elif [ "$AGENT" = "cline" ]; then
     echo "ERROR: cline is not functional or configured." >&2
     exit 1
   fi
+elif [ "$AGENT" = "grok" ]; then
+  if [ -f "$HOME/.grok/auth.json" ] || [ -n "$XAI_API_KEY" ]; then
+    true
+  elif ! grok --version >/dev/null 2>&1; then
+    echo "ERROR: grok is not functional or configured." >&2
+    exit 1
+  fi
 fi
 
 # 세션 이름 — lib.sh::derive_session_name 이 단일 소스 (P0-A)
@@ -199,10 +206,10 @@ spawn() {
         HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CMD_FULL"
       fi
       ;;
-    agy|hermes|cline)
+    agy|hermes|cline|grok)
       HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CMD_FULL"
       ;;
-    *) echo "ERROR: --agent must be claude, agy, hermes or cline, got: $AGENT" >&2; exit 2 ;;
+    *) echo "ERROR: --agent must be claude, agy, hermes, cline or grok, got: $AGENT" >&2; exit 2 ;;
   esac
 }
 

.agents/skills/multi-agent-mux-delegate-job/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: multi-agent-mux-delegate-job
-description: "Delegate a unit of work to any autonomous agent (claude-code, hermes, agy, cline, codex, or a human) and observe it asynchronously over an MQTT event channel. Supported roles include orchestrator, worker, and reviewer."
+description: "Delegate a unit of work to any autonomous agent (claude-code, hermes, agy, cline, grok-build, codex, or a human) and observe it asynchronously over an MQTT event channel. Supported roles include orchestrator, worker, and reviewer."
 version: 2.2.1
 author: godopu
 license: MIT
@@ -17,7 +17,7 @@ metadata:
 
 Delegate a unit of work to any autonomous agent, then **observe** it asynchronously instead of blocking. Every job gets a unique ID and a registry record. The worker agent publishes lifecycle events (`started`, `permission_required`, `progress`, `completed`, `error`) to a per-job MQTT topic, and the delegator/orchestrator subscribes to verify the final state.
 
-This skill allows any agent (`claude-code`, `hermes`, `agy`, `cline`, etc.) to play any role: **Orchestrator/Delegator**, **Worker/Implementer**, or **Reviewer**.
+This skill allows any agent (`claude-code`, `hermes`, `agy`, `cline`, `grok-build`, etc.) to play any role: **Orchestrator/Delegator**, **Worker/Implementer**, or **Reviewer**.
 
 ---
 
@@ -36,7 +36,7 @@ The `multi-agent-mux-delegate-job` bash wrapper handles job registration, subscr
 ```bash
 # 1) Submit a new job to a targeted agent session (e.g. herdr session name 'demo')
 multi-agent-mux-delegate-job submit \
-  --agent <claude-code|hermes-agent|agy-agent|cline-agent|human> \
+  --agent <claude-code|hermes-agent|agy-agent|cline-agent|grok-build|human> \
   --agent-session herdr:<session_name> \
   --prompt "Task description or instructions here" \
   --role <Worker|Planner|Reviewer> \

.agents/skills/multi-agent-mux-loop/SKILL.md

@@ -8,7 +8,7 @@ platforms: [linux, macos]
 environments: [terminal, herdr]
 metadata:
   hermes:
-    tags: [agent, herdr, multi-agent, loop, planning, review, orchestrator]
+    tags: [agent, herdr, multi-agent, loop, planning, review, orchestrator, grok]
     related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-stop, multi-agent-mux-delegate-job]
     prereq_skills: [multi-agent-mux-create]
 ---

.agents/skills/multi-agent-mux-monitor/SKILL.md

@@ -8,7 +8,7 @@ platforms: [linux, macos]
 environments: [terminal, herdr]
 metadata:
   hermes:
-    tags: [agent, herdr, claude, antigravity, agy, monitor, observation, reconciliation]
+    tags: [agent, herdr, claude, antigravity, agy, grok, monitor, observation, reconciliation]
     related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-stop, multi-agent-mux-status]
     prereq_skills: [multi-agent-mux-create]
 ---

.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh

@@ -518,7 +518,7 @@ if herdr_confirmed:
         agent = None
         role = 'creator'
         for r_name in ('creator', 'planner', 'reviewer'):
-            for a_name in ('claude', 'agy', 'hermes', 'cline'):
+            for a_name in ('claude', 'agy', 'hermes', 'cline', 'grok'):
                 if name.endswith(f"-{r_name}-{a_name}"):
                     role = r_name
                     agent = a_name
@@ -537,7 +537,7 @@ if herdr_confirmed:
                         if tok.startswith('MAM_MANAGED='):
                             managed_path = tok.split('=', 1)[1]
                             if os.path.realpath(managed_path) == os.path.realpath(workspace_root):
-                                for a_name in ('claude', 'agy', 'hermes', 'cline'):
+                                for a_name in ('claude', 'agy', 'hermes', 'cline', 'grok'):
                                     if a_name in pm_check.get('cmd', '') or a_name in pm_check.get('cmd_full', ''):
                                         agent = a_name
                                         break
@@ -611,7 +611,7 @@ def row_agent(s):
     return agent_of_row(s)
 
 OWN_KEY_BY_AGENT = {
-    a: _get_own_key(a) for a in ('claude', 'agy', 'hermes', 'cline')
+    a: _get_own_key(a) for a in ('claude', 'agy', 'hermes', 'cline', 'grok')
 }
 
 # === drift C0: 지정된 ID 는 발견이 아니라 '확인'만 필요하다 ===

.agents/skills/multi-agent-mux-orc-onboard/SKILL.md

@@ -8,7 +8,7 @@ platforms: [linux, macos]
 environments: [terminal, herdr]
 metadata:
   hermes:
-    tags: [agent, herdr, claude, antigravity, agy, cline, hermes, orchestrator, onboard, isolation]
+    tags: [agent, herdr, claude, antigravity, agy, cline, hermes, grok, orchestrator, onboard, isolation]
     related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-monitor]
     prereq_skills: [multi-agent-mux-create]
 ---
@@ -32,17 +32,19 @@ Registers an orchestrator session UUID into the `orchestrator_uuids` list of `.m
 
 ## Auto-Detection Hierarchy (Rev.2)
 
-When `--uuid` is omitted, `orc_onboard.sh` inspects the process ancestry tree of the nearest agent ancestor (`claude`, `agy`, `hermes`, `cline`) in the following order:
+When `--uuid` is omitted, `orc_onboard.sh` inspects the process ancestry tree of the nearest agent ancestor (`claude`, `agy`, `hermes`, `cline`, `grok`) in the following order:
 
 1. **CLI `argv`**:
    - `claude -r <uuid>` / `claude --session-id <uuid>`
    - `agy --conversation <uuid>`
    - `cline --id <uuid>` / `cline --session-id <uuid>`
+   - `grok --session-id <uuid>` / `grok --resume <uuid>`
 2. **Family-Matched Environment Variables**:
    - `claude` → `CLAUDE_CODE_SESSION_ID`
    - `agy` → `ANTIGRAVITY_CONVERSATION_ID`
    - `hermes` → `HERMES_SESSION_ID`
    - `cline` → `CLINE_SESSION_ID`
+   - `grok` → `GROK_SESSION_ID`
 3. **Fallback**:
    - If no valid ID matching the nearest agent family is found, exits with status 3 (`Could not detect orchestrator ID`).
 

.agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh

@@ -104,7 +104,7 @@ detect_nearest_agent() {
       local base
       base="$(basename "$tok")"
       case "$base" in
-        claude|agy|hermes|cline)
+        claude|agy|hermes|cline|grok)
           match="$base"
           break
           ;;
@@ -128,6 +128,9 @@ detect_nearest_agent() {
         cline)
           detected_id=$(echo "$cmd_line" | grep -oE '(--id|--session-id)[[:space:]=]+[^[:space:]]+' | head -n 1 | sed -E 's/^(--id|--session-id)[[:space:]=]+//' || true)
           ;;
+        grok)
+          detected_id=$(echo "$cmd_line" | grep -oE '(--session-id|--resume)[[:space:]=]+[^[:space:]]+' | head -n 1 | sed -E 's/^(--session-id|--resume)[[:space:]=]+//' || true)
+          ;;
       esac
 
       if [ -n "$detected_id" ] && is_valid_id "$detected_id"; then
@@ -142,6 +145,7 @@ detect_nearest_agent() {
         agy) env_var="${ANTIGRAVITY_CONVERSATION_ID:-}" ;;
         hermes) env_var="${HERMES_SESSION_ID:-}" ;;
         cline) env_var="${CLINE_SESSION_ID:-}" ;;
+        grok) env_var="${GROK_SESSION_ID:-}" ;;
       esac
 
       if [ -n "$env_var" ] && is_valid_id "$env_var"; then
@@ -202,7 +206,7 @@ except Exception:
 target = sys.argv[1]
 for s in d.get("herdr_sessions", []):
     if s.get("status") == "running":
-        for k in ["claude_session_id_own", "agy_conversation_id_own", "hermes_conversation_id_own", "cline_conversation_id_own"]:
+        for k in ["claude_session_id_own", "agy_conversation_id_own", "hermes_conversation_id_own", "cline_conversation_id_own", "grok_session_id_own"]:
             if s.get(k) == target:
                 sys.exit(1)
 sys.exit(0)

.agents/skills/multi-agent-mux-resume/SKILL.md

@@ -49,7 +49,7 @@ ideal resume path:
 
 `agent-sessions.yaml` and on-disk discovery are used to resolve the UUID in this order:
 
-1. **`herdr_sessions[]` row's per-row own id** (`claude_session_id_own` / `agy_conversation_id_own` / `hermes_conversation_id_own` / `cline_conversation_id_own`) — explicitly saved by `multi-agent-mux-stop` right before teardown (tier-1, race-free).
+1. **`herdr_sessions[]` row's per-row own id** (`claude_session_id_own` / `agy_conversation_id_own` / `hermes_conversation_id_own` / `cline_conversation_id_own` / `grok_session_id_own`) — explicitly saved by `multi-agent-mux-stop` right before teardown (tier-1, race-free).
 2. **Workspace-scoped on-disk scan** (adapter `discover()`)
 
 If both are empty → the workspace has no conversation yet. Fall back to `multi-agent-mux-create`.
@@ -58,7 +58,7 @@ If both are empty → the workspace has no conversation yet. Fall back to `multi
 
 ```bash
 WORKSPACE=/path/to/project
-AGENT=claude  # claude | agy | hermes | cline — pass it explicitly
+AGENT=claude  # claude | agy | hermes | cline | grok — pass it explicitly
 SESSION_NAME=<workspace>-creator-<agent>  # same convention as multi-agent-mux-create
 
 # Resolve the isolated herdr server name & load common utils
@@ -89,6 +89,7 @@ case "$AGENT" in
   agy)    CMD_FULL="agy --dangerously-skip-permissions --conversation $UUID" ;;
   hermes) CMD_FULL="hermes --resume $UUID" ;;
   cline)  CMD_FULL="cline -i --id $UUID" ;;
+  grok)   CMD_FULL="grok --resume $UUID --permission-mode bypassPermissions" ;;
 esac
 
 # 4. Spawn new herdr session + run agent with the saved id
@@ -99,7 +100,7 @@ case "$AGENT" in
     # auto-handle trust / bypass dialogs
     handle_startup_dialogs "$SESSION_NAME" 20
     ;;
-  agy|hermes|cline)
+  agy|hermes|cline|grok)
     eval "herdr new-session -d -s \"$SESSION_NAME\" -x 140 -y 40 -c \"$WORKSPACE\" \"$CMD_FULL\""
     ;;
 esac

.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh

@@ -109,6 +109,7 @@ if [ -z "$CMD_FULL" ]; then
     agy)    CMD_FULL="${RESOLVED_BIN} --dangerously-skip-permissions --conversation $UUID" ;;
     hermes) CMD_FULL="${RESOLVED_BIN} --resume $UUID" ;;
     cline)  CMD_FULL="${RESOLVED_BIN} -i --id $UUID" ;;
+    grok)   CMD_FULL="${RESOLVED_BIN} --resume $UUID --permission-mode bypassPermissions" ;;
     *)      echo "ERROR: unsupported agent: $AGENT" >&2; exit 2 ;;
   esac
 fi

.agents/skills/multi-agent-mux-status/SKILL.md

@@ -8,7 +8,7 @@ platforms: [linux, macos]
 environments: [terminal, herdr]
 metadata:
   hermes:
-    tags: [agent, herdr, claude, antigravity, agy, status, read-only, snapshot]
+    tags: [agent, herdr, claude, antigravity, agy, grok, status, read-only, snapshot]
     related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-stop, multi-agent-mux-monitor]
     prereq_skills: [multi-agent-mux-create, multi-agent-mux-monitor]
 ---

.agents/skills/multi-agent-mux-status/scripts/status.sh

@@ -53,12 +53,12 @@ def resume_on_disk(s):
     name = s.get('name', '')
     cwd = (s.get('pane') or {}).get('cwd', '')
     agent = None
-    for a in ('claude', 'agy', 'hermes', 'cline'):
+    for a in ('claude', 'agy', 'hermes', 'cline', 'grok'):
         if any(name.endswith(f'-{r}-{a}') for r in ('creator', 'planner', 'reviewer')) or name.endswith(f'-{a}'):
             agent = a
             break
     if not agent:
-        for a in ('claude', 'agy', 'hermes', 'cline'):
+        for a in ('claude', 'agy', 'hermes', 'cline', 'grok'):
             if f"-{a}" in name or f"_{a}" in name:
                 agent = a
                 break
@@ -95,6 +95,13 @@ def resume_on_disk(s):
         if u:
             return 'yes' if os.path.exists(f"{home}/.cline/data/sessions/{u}/{u}.json") else 'MISSING'
         return 'no'
+    if agent == 'grok':
+        u = s.get('grok_session_id_own')
+        if u:
+            import urllib.parse
+            ws_slug = urllib.parse.quote(cwd, safe='')
+            return 'yes' if os.path.exists(f"{home}/.grok/sessions/{ws_slug}/{u}/chat_history.jsonl") else 'MISSING'
+        return 'no'
     return '?'
 
 

.agents/skills/multi-agent-mux-stop/SKILL.md

@@ -37,7 +37,7 @@ The stop command is always **graceful by default**:
 
 ```bash
 SESSION_NAME=<workspace>-creator-<agent>  # convention
-AGENT=claude                              # claude | agy | hermes | cline — always pass it
+AGENT=claude                              # claude | agy | hermes | cline | grok — always pass it
 AGENT_SESSIONS_YAML=.mam/agent-sessions.yaml
 
 # 1) Session is registered?

.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh

@@ -94,8 +94,8 @@ while [ $# -gt 0 ]; do
 done
 if [ -n "$AGENT" ]; then
   case "$AGENT" in
-    claude|agy|hermes|cline) ;;
+    claude|agy|hermes|cline|grok) ;;
-    *) echo "ERROR: invalid agent type '$AGENT'. Allowed types are: claude, agy, hermes, cline." >&2; exit 2 ;;
+    *) echo "ERROR: invalid agent type '$AGENT'. Allowed types are: claude, agy, hermes, cline, grok." >&2; exit 2 ;;
   esac
 fi
 [ -n "$SESSION_NAME" ] || { echo "ERROR: --session required" >&2; usage; exit 2; }
@@ -290,6 +290,8 @@ if captured and not purge:
         target['hermes_conversation_id_own'] = captured
     elif agent == 'cline':
         target['cline_conversation_id_own'] = captured
+    elif agent == 'grok':
+        target['grok_session_id_own'] = captured
     target['resumable'] = True
 
 if purge and purge_uuid:

.mam.env.example

@@ -88,6 +88,10 @@
 #default: INFO
 # MAM_LOG_LEVEL=INFO
 
+# Optional xAI API Key for Grok Build CLI (if ~/.grok/auth.json is not present).
+#default: (unset → reads ~/.grok/auth.json)
+# XAI_API_KEY=replace_me
+
 # Retention period (days) for delegate-job event logs.
 #default: 7
 # MAM_EVENT_RETENTION_DAYS=7

tests/test_a4_adapter_contract.py

@@ -26,11 +26,18 @@ def test_resolve_home_contract():
     assert resolve_home() == home_val
 
 def test_agent_adapter_registry():
-    for agent in ('claude', 'agy', 'hermes', 'cline'):
+    EXPECTED_OWN_KEYS = {
+        'claude': 'claude_session_id_own',
+        'agy': 'agy_conversation_id_own',
+        'hermes': 'hermes_conversation_id_own',
+        'cline': 'cline_conversation_id_own',
+        'grok': 'grok_session_id_own',
+    }
+    for agent, expected in EXPECTED_OWN_KEYS.items():
         adapter = get_adapter(agent)
         assert adapter is not None
         assert adapter.name == agent
-        assert adapter.own_key == f"{agent}_{'session' if agent == 'claude' else 'conversation'}_id_own"
+        assert adapter.own_key == expected
         assert own_key(agent) == adapter.own_key
 
 def test_agent_of_row_priority():
@@ -67,6 +74,7 @@ def test_adapter_required_properties():
         'agy': ('Antigravity', 'Exit', 'antigravity-cli', ('conversation_id', 'conversation_db', 'conversation_brain_dir')),
         'hermes': ('Hermes', '/exit', 'hermes-agent', ('session_id',)),
         'cline': ('Cline|history|Chat|What can I do|slash commands', '/exit', 'cline-agent', ('session_id',)),
+        'grok': ('Grok|xAI|Assistant|❯|>>>', '/exit', 'grok-build', ('session_id', 'session_jsonl')),
     }
     for agent, (toks, exitk, delk, cache_f) in expected.items():
         adapter = get_adapter(agent)
@@ -82,7 +90,7 @@ def test_facts_bridge_eval_contract():
     env = os.environ.copy()
     skills_dir = str(Path(__file__).resolve().parent.parent / ".agents" / "skills")
     env["PYTHONPATH"] = f"{skills_dir}:{env.get('PYTHONPATH', '')}"
-    for agent in ('claude', 'agy', 'hermes', 'cline'):
+    for agent in ('claude', 'agy', 'hermes', 'cline', 'grok'):
         res = subprocess.run([sys.executable, "-m", "lib_py.agents", "facts", agent], capture_output=True, text=True, env=env)
         assert res.returncode == 0
         facts_output = res.stdout
@@ -174,6 +182,19 @@ def test_purge_artifacts_composite(tmp_path):
     assert len(purged_cl) == 1
     assert not os.path.exists(cline_dir)
 
+    # 5. Grok (session directory containing chat_history.jsonl)
+    grok_adapter = get_adapter('grok')
+    grok_ctx = DiscoveryContext(workspace=ws, agent_name='grok', home_dir=home)
+    g_path = grok_adapter.artifact_path('uuid-g', grok_ctx)
+    os.makedirs(os.path.dirname(g_path), exist_ok=True)
+    with open(g_path, 'w') as f:
+        f.write('{"session_id": "uuid-g"}')
+    assert os.path.exists(g_path)
+    purged_g = grok_adapter.purge_artifacts('uuid-g', grok_ctx)
+    assert len(purged_g) == 1
+    assert not os.path.exists(g_path)
+    assert not os.path.exists(os.path.dirname(g_path))
+
 def test_adapter_spawn_and_resume_specs():
     claude = get_adapter('claude')
     assert claude.spawn_spec('claude', 'u1') == 'claude --dangerously-skip-permissions --session-id u1'
@@ -194,6 +215,12 @@ def test_adapter_spawn_and_resume_specs():
     assert cline.resume_spec('cline', 'u1', materialized=True) == 'cline -i --id u1'
     assert cline.resume_spec('cline', 'u1', materialized=False) == 'cline -i'
 
+    grok = get_adapter('grok')
+    assert grok.spawn_spec('grok', 'u1') == 'grok --session-id u1 --permission-mode bypassPermissions'
+    assert grok.spawn_spec('grok', '') == 'grok --permission-mode bypassPermissions'
+    assert grok.resume_spec('grok', 'u1', materialized=True) == 'grok --resume u1 --permission-mode bypassPermissions'
+    assert grok.resume_spec('grok', 'u1', materialized=False) == 'grok --session-id u1 --permission-mode bypassPermissions'
+
 def test_adapter_auth_ok(tmp_path, monkeypatch):
     monkeypatch.setenv("HOME_DIR", str(tmp_path))
     # Claude auth runner
@@ -209,6 +236,17 @@ def test_adapter_auth_ok(tmp_path, monkeypatch):
     oauth_file.write_text("{}")
     assert agy.auth_ok() is True
 
+    # Grok auth check (env var or auth.json file)
+    grok = get_adapter('grok')
+    assert grok.auth_ok() is False
+    monkeypatch.setenv("XAI_API_KEY", "test-key")
+    assert grok.auth_ok() is True
+    monkeypatch.delenv("XAI_API_KEY", raising=False)
+    grok_auth = tmp_path / ".grok" / "auth.json"
+    grok_auth.parent.mkdir(parents=True, exist_ok=True)
+    grok_auth.write_text("{}")
+    assert grok.auth_ok() is True
+
     # Hermes & Cline always True
     assert get_adapter('hermes').auth_ok() is True
     assert get_adapter('cline').auth_ok() is True
@@ -268,6 +306,15 @@ def test_adapter_discover(tmp_path):
         f.write('{"session_id": "u-cl1", "cwd": "' + ws + '"}')
     assert cline.discover(ctx_cl) == ['u-cl1']
 
+    # 5. Grok
+    grok = get_adapter('grok')
+    ctx_g = DiscoveryContext(workspace=ws, agent_name='grok', home_dir=home)
+    g_sess = f"{home}/.grok/sessions/{grok._ws_dir(ctx_g)}/u-g1"
+    os.makedirs(g_sess, exist_ok=True)
+    with open(f"{g_sess}/chat_history.jsonl", 'w') as f:
+        f.write('{"session_id": "u-g1", "cwd": "' + ws + '"}\n')
+    assert grok.discover(ctx_g) == ['u-g1']
+
 def test_cli_bridge_subcommands_and_quote_safety():
     import subprocess, sys
     from pathlib import Path
@@ -286,7 +333,7 @@ def test_cli_bridge_subcommands_and_quote_safety():
     assert res.stdout.strip() == "/bin/claude --dangerously-skip-permissions --session-id uuid-test"
 
     # 3. exit-key
-    for agent, expected_key in [('claude', '/exit'), ('agy', 'Exit'), ('hermes', '/exit'), ('cline', '/exit')]:
+    for agent, expected_key in [('claude', '/exit'), ('agy', 'Exit'), ('hermes', '/exit'), ('cline', '/exit'), ('grok', '/exit')]:
         res = subprocess.run([sys.executable, "-m", "lib_py.agents", "exit-key", agent], capture_output=True, text=True, env=env)
         assert res.returncode == 0
         assert res.stdout.strip() == expected_key
@@ -298,6 +345,7 @@ def test_delegate_agent_resolution_and_fallback():
         'agy': 'antigravity-cli',
         'hermes': 'hermes-agent',
         'cline': 'cline-agent',
+        'grok': 'grok-build',
     }
     # 1. Adapter property
     for agent, expected_key in expected_map.items():
@@ -316,6 +364,7 @@ def test_delegate_agent_resolution_and_fallback():
             hermes) delegate_agent="hermes-agent" ;;
             cline)  delegate_agent="cline-agent" ;;
             agy)    delegate_agent="antigravity-cli" ;;
+            grok)   delegate_agent="grok-build" ;;
             *) echo "ERROR: cannot resolve delegate agent key for '$AGENT'" >&2; exit 2 ;;
           esac
         fi

tests/test_b19_headless_reconcile_fixes.py

@@ -18,19 +18,19 @@ def test_bug2_headless_layout_does_not_overflow():
 
     # 2. Genuine small pane (overflow)
     payload_small = {"result": {"panes": [{"pane_id": "p1", "rect": {"width": 50, "height": 30}}]}}
-    d_small = compute_2xk_layout(payload_small)
+    d_small = compute_2xk_layout(payload_small, min_cols=60, min_rows=20)
     assert d_small.is_overflow, f"Small pane should be overflow, got {d_small}"
     assert d_small.direction == "overflow"
 
     # 3. Wide pane (split right)
     payload_wide = {"result": {"panes": [{"pane_id": "p1", "rect": {"width": 160, "height": 30}}]}}
-    d_wide = compute_2xk_layout(payload_wide)
+    d_wide = compute_2xk_layout(payload_wide, min_cols=60, min_rows=20)
     assert not d_wide.is_overflow
     assert d_wide.direction == "right"
 
     # 4. Tall pane (split down)
     payload_tall = {"result": {"panes": [{"pane_id": "p1", "rect": {"width": 80, "height": 60}}]}}
-    d_tall = compute_2xk_layout(payload_tall)
+    d_tall = compute_2xk_layout(payload_tall, min_cols=60, min_rows=20)
     assert not d_tall.is_overflow
     assert d_tall.direction == "down"
 

tests/test_tier1_unit.py

@@ -946,6 +946,48 @@ def test_layout_single_workspace_54x23_compact_tiling_tier1():
     assert d4.reason == "column_width_overflow"
 
 
+# ==============================================================================
+# FEATURE: Grok Build TUI Agent Integration
+# ==============================================================================
+
+def test_grok_adapter_contract_in_tier1():
+    """Verify GrokAgentAdapter registration and properties in Tier 1 suite."""
+    from lib_py.agents.registry import get_adapter
+    adapter = get_adapter('grok')
+    assert adapter is not None
+    assert adapter.name == 'grok'
+    assert adapter.own_key == 'grok_session_id_own'
+    assert adapter.delegate_agent_key == 'grok-build'
+    assert adapter.exit_key == '/exit'
+    assert adapter.ready_tokens == 'Grok|xAI|Assistant|❯|>>>'
+
+
+def test_grok_shell_and_scripts_integration(mam_sandbox):
+    """Verify lib.sh, create_session.sh, stop_session.sh, and workspace_uuid contain grok."""
+    # 1. lib.sh kind mapping & binaries
+    lib_path = mam_sandbox / "skills" / "lib.sh"
+    lib_content = lib_path.read_text()
+    assert '*-creator-grok|*-planner-grok|*-reviewer-grok)      kind="grok"' in lib_content
+    assert "'claude', 'agy', 'hermes', 'cline', 'grok'" in lib_content
+    assert '[[ "$sess" =~ "grok" ]]' in lib_content
+
+    # 2. create_session.sh validation
+    create_path = mam_sandbox / "skills" / "multi-agent-mux-create" / "scripts" / "create_session.sh"
+    create_content = create_path.read_text()
+    assert 'claude|agy|hermes|cline|grok)' in create_content
+
+    # 3. stop_session.sh validation & state capture
+    stop_path = mam_sandbox / "skills" / "multi-agent-mux-stop" / "scripts" / "stop_session.sh"
+    stop_content = stop_path.read_text()
+    assert 'claude|agy|hermes|cline|grok)' in stop_content
+    assert "target['grok_session_id_own'] = captured" in stop_content
+
+    # 4. workspace_uuid OWN_KEY
+    from lib_py.workspace_uuid import OWN_KEY
+    assert OWN_KEY.get('grok') == 'grok_session_id_own'
+
+
+