docs(owner-gate): document owner maintenance gate

commands/owner-requests/CMD-20260710-memory-index-rebuild.yaml

@@ -0,0 +1,48 @@
+cmd_id: CMD-20260710-memory-index-rebuild
+operation: memory.index.rebuild
+risk: medium
+permission: OWNER_NON_DANGEROUS_ALL
+status: pending_owner_gate
+reason: Memory search is disabled because existing embedding index metadata does not match the current embedding provider configuration.
+requested_by: codex-chartgpt-bridge
+requested_at: "2026-07-10T08:00:00+08:00"
+command_key: openclaw.memory.index.force
+args:
+  force: true
+safety:
+  destructive: false
+  arbitrary_shell: false
+  credential_mutation: false
+  provider_mutation: false
+  external_network_write: false
+  production_data_delete: false
+  baseline_or_tag_mutation: false
+  main_branch_direct_write: false
+owner_gate:
+  required: true
+  approval_model: protected_branch_merge_or_signed_owner_commit
+  approved_by: null
+  approved_at: null
+  approval_commit: null
+execution:
+  runner: owner-maintenance-runner
+  lock_key: memory-index-rebuild
+  timeout_seconds: 1800
+  executed_by: null
+  executed_at: null
+  exit_code: null
+acceptance:
+  commands:
+    - openclaw memory search "V1R4C3"
+    - openclaw memory search "Gitea Branch Sync"
+    - openclaw memory search "Autonomous Controller"
+  expected:
+    - no_embedding_metadata_mismatch
+    - memory_search_returns_results
+    - memory_index_uses_current_embedding_provider
+success_signals:
+  - AIOS_OWNER_MAINTENANCE_MEMORY_INDEX_REBUILT
+  - AIOS_MEMORY_SEARCH_RESTORED
+rollback:
+  destructive: false
+  strategy: rebuild_previous_index_if_snapshot_exists

docs/owner-maintenance-gate.md

@@ -0,0 +1,49 @@
+# Owner Maintenance Gate
+
+This mechanism allows owner-approved non-dangerous maintenance actions without giving agents arbitrary host CLI access.
+
+## Permission tiers
+
+- READ_ONLY: status, health, baseline, versions, search inspection.
+- AUTO_PATCH: branch creation, repo file changes, patch commits, test/report artifacts.
+- OWNER_NON_DANGEROUS_ALL: owner may approve all non-destructive allowlisted maintenance command_keys.
+- OWNER_HIGH_RISK: main merge, baseline promotion, tag creation, credential/provider mutation, destructive cleanup, production restart, SSH/firewall changes.
+
+## Execution rule
+
+Agents can create requests. The runner can only execute fixed allowlist mappings:
+
+```text
+command_key: openclaw.memory.index.force
+argv: /usr/local/bin/openclaw memory index --force
+```
+
+The runner rejects arbitrary shell strings such as `bash -c`, `sh -c`, `curl | bash`, or recursive destructive commands.
+
+## Owner gate
+
+A request becomes executable only after protected-branch merge or signed owner commit fills:
+
+```yaml
+owner_gate:
+  approved_by: <owner>
+  approved_at: <timestamp>
+  approval_commit: <signed-owner-commit-sha>
+```
+
+## Memory index rebuild flow
+
+1. Detect embedding metadata mismatch.
+2. Create `commands/owner-requests/CMD-20260710-memory-index-rebuild.yaml`.
+3. Owner approves through GitOps owner gate.
+4. `runtime/owner_maintenance/allowlist_runner.py` validates safety metadata.
+5. Runner executes the fixed command vector.
+6. Runner records exit code and stdout/stderr hashes.
+7. Acceptance checks verify memory search works again.
+
+Expected signals:
+
+```text
+AIOS_OWNER_MAINTENANCE_MEMORY_INDEX_REBUILT
+AIOS_MEMORY_SEARCH_RESTORED
+```

patches/feature_v1r4c4-owner-maintenance-gate-v2-20260710.branch.json

@@ -0,0 +1,9 @@
+{
+  "type": "branch",
+  "branch": "feature/v1r4c4-owner-maintenance-gate-v2-20260710",
+  "base": "main",
+  "created_by": "chatgpt-gitops-bot",
+  "created_at": "2026-07-10T10:32:35Z",
+  "direct_main_push": false,
+  "owner_approval_required": true
+}

policies/owner-maintenance-gate.yaml

@@ -0,0 +1,80 @@
+version: 1
+name: owner-maintenance-gate
+baseline: V1R4C3
+created_at: "2026-07-10"
+purpose: Owner-controlled non-dangerous maintenance permissions without arbitrary host CLI access.
+
+principles:
+  - agents_may_detect_and_request
+  - owner_may_approve_non_dangerous_actions
+  - runner_executes_only_allowlisted_command_keys
+  - no_arbitrary_shell
+  - protected_branch_merge_is_default_owner_gate
+  - every_execution_must_be_audited
+
+permission_tiers:
+  READ_ONLY:
+    agent_allowed: true
+    owner_allowed: true
+    requires_owner_gate: false
+  AUTO_PATCH:
+    agent_allowed: true
+    owner_allowed: true
+    requires_owner_gate: false
+  OWNER_NON_DANGEROUS_ALL:
+    description: Owner may execute all non-destructive allowlisted maintenance command_keys after owner gate approval.
+    agent_allowed: false
+    owner_allowed: true
+    requires_owner_gate: true
+    approval_model: protected_branch_merge_or_signed_owner_commit
+  OWNER_HIGH_RISK:
+    description: main merge, baseline promotion, tag creation, credential/provider mutation, destructive cleanup, production restart, SSH/firewall mutation.
+    agent_allowed: false
+    owner_allowed: true
+    requires_owner_gate: true
+    extra_review_required: true
+
+safety_classification:
+  non_dangerous_requirements:
+    destructive: false
+    arbitrary_shell: false
+    credential_mutation: false
+    provider_mutation: false
+    external_network_write: false
+    production_data_delete: false
+    baseline_or_tag_mutation: false
+    main_branch_direct_write: false
+    command_key_must_be_allowlisted: true
+  always_high_risk:
+    - merge_to_main
+    - baseline_promotion
+    - tag_creation
+    - credential_rotation
+    - embedding_provider_change
+    - database_delete_or_drop
+    - rm_recursive_or_force
+    - service_restart_production
+    - firewall_or_ssh_config_change
+    - arbitrary_bash_or_shell
+
+allowlist:
+  openclaw.memory.index.force:
+    permission: OWNER_NON_DANGEROUS_ALL
+    risk: medium
+    destructive: false
+    command_vector:
+      - /usr/local/bin/openclaw
+      - memory
+      - index
+      - --force
+    timeout_seconds: 1800
+    lock_key: memory-index-rebuild
+    acceptance:
+      - openclaw memory search "V1R4C3"
+      - openclaw memory search "Gitea Branch Sync"
+      - openclaw memory search "Autonomous Controller"
+    success_signals:
+      - AIOS_OWNER_MAINTENANCE_MEMORY_INDEX_REBUILT
+      - AIOS_MEMORY_SEARCH_RESTORED
+
+status: proposed

runtime/owner_maintenance/allowlist_runner.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Owner maintenance allowlist runner.
+
+Executes only approved command_key mappings. It never runs arbitrary shell strings.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore
+except Exception:
+    yaml = None
+
+
+@dataclass(frozen=True)
+class AllowedCommand:
+    command_key: str
+    argv: tuple[str, ...]
+    permission: str
+    risk: str
+    destructive: bool
+    timeout_seconds: int
+
+
+ALLOWED_COMMANDS: dict[str, AllowedCommand] = {
+    "openclaw.memory.index.force": AllowedCommand(
+        command_key="openclaw.memory.index.force",
+        argv=("/usr/local/bin/openclaw", "memory", "index", "--force"),
+        permission="OWNER_NON_DANGEROUS_ALL",
+        risk="medium",
+        destructive=False,
+        timeout_seconds=1800,
+    ),
+}
+
+DENY_FLAGS = {
+    "arbitrary_shell",
+    "credential_mutation",
+    "provider_mutation",
+    "external_network_write",
+    "production_data_delete",
+    "baseline_or_tag_mutation",
+    "main_branch_direct_write",
+}
+
+
+def sha256_text(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8", errors="replace")).hexdigest()
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def load_request(path: Path) -> dict[str, Any]:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required to load owner request YAML")
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("owner request must be a YAML object")
+    return data
+
+
+def validate_request(req: dict[str, Any]) -> AllowedCommand:
+    command_key = req.get("command_key")
+    if command_key not in ALLOWED_COMMANDS:
+        raise PermissionError(f"command_key is not allowlisted: {command_key}")
+    allowed = ALLOWED_COMMANDS[command_key]
+    if req.get("permission") != allowed.permission:
+        raise PermissionError("request permission does not match allowlist")
+    safety = req.get("safety", {})
+    if not isinstance(safety, dict):
+        raise PermissionError("safety metadata is required")
+    if bool(safety.get("destructive", True)) != allowed.destructive:
+        raise PermissionError("destructive flag does not match allowlist")
+    denied = [flag for flag in DENY_FLAGS if safety.get(flag) is True]
+    if denied:
+        raise PermissionError(f"denied safety flags: {denied}")
+    gate = req.get("owner_gate", {})
+    if not isinstance(gate, dict) or gate.get("required") is not True:
+        raise PermissionError("owner_gate.required must be true")
+    if not gate.get("approved_by") or not gate.get("approved_at") or not gate.get("approval_commit"):
+        raise PermissionError("owner approval fields are required before execution")
+    return allowed
+
+
+def run_allowed_command(allowed: AllowedCommand, dry_run: bool) -> dict[str, Any]:
+    if dry_run:
+        return {"dry_run": True, "argv": list(allowed.argv), "exit_code": None}
+    proc = subprocess.run(
+        list(allowed.argv),
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=allowed.timeout_seconds,
+    )
+    return {
+        "dry_run": False,
+        "argv": list(allowed.argv),
+        "exit_code": proc.returncode,
+        "executed_at": utc_now(),
+        "stdout_sha256": sha256_text(proc.stdout),
+        "stderr_sha256": sha256_text(proc.stderr),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run an owner-approved allowlisted maintenance request")
+    parser.add_argument("request", type=Path)
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+    try:
+        req = load_request(args.request)
+        allowed = validate_request(req)
+        result = run_allowed_command(allowed, dry_run=args.dry_run)
+        print(json.dumps({"status": "ok", "command_key": allowed.command_key, "result": result}, indent=2))
+        return 0 if result.get("exit_code") in (None, 0) else int(result["exit_code"])
+    except Exception as exc:
+        print(json.dumps({"status": "error", "error": str(exc)}, indent=2), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())