Skip to main content

Operations

This page is the operator entry point for runtime procedures in jhf-openclaw-env. It intentionally stays concise and points to the canonical runbooks and contracts.

Core Runtime Verify Paths​

Fast repository checks​

  • python infrastructure/validate_environment_contracts.py
  • python infrastructure/validate_module_features_registry.py
  • python infrastructure/validate_openclaw_runtime_config.py
  • python infrastructure/validate_execution_track.py
  • python scripts/verify_portainer_compose_bindings.py --check
  • bash scripts/scan_and_fix.sh --dry-run --max-issues 1

<internal-runtime-redacted> Portainer access​

  • Portainer's compose-managed HTTPS control port is loopback-only on <internal-runtime-redacted>.
  • Verify the repository posture with python scripts/verify_portainer_compose_bindings.py --check.
  • Open the management UI through the SSH tunnel: ssh -L 9443:&lt;internal-runtime-redacted&gt;:9443 &lt;lane-konto&gt;@&lt;internal-runtime-redacted&gt;.
  • PORTAINER_OC_TOKEN remains unchanged; the tunnel changes reachability only.

Host runtime checks​

  • bash scripts/host_preflight_openclaw_env.sh
  • bash scripts/host_post_change_verify.sh
  • bash scripts/host_post_reboot_verify.sh
  • bash scripts/host_post_dockerd_reconcile_verify.sh

Guardrail/recovery checks​

  • bash scripts/host_openclaw_runtime_guardrail.sh
  • bash scripts/host_reconcile_core_after_dockerd.sh
  • bash scripts/host_reconcile_jhf_tools_restart_safety.sh
  • bash scripts/host_tune_low_load_memory_limits.sh [--apply]
  • bash scripts/host_verify_shared_host_disk_budget.sh
  • bash scripts/host_reclaim_shared_host_disk_pressure.sh [--apply] [--host HOST] [--user USER]
  • bash scripts/host_reclaim_shared_host_disk_pressure.sh --apply --builder-cache-only only when the documented owner decision permits BuildKit-cache cleanup and the read-only preflight shows it is the sole breached reclaim class (--apply omitted is strictly observational and fails closed if the cleanup guard detects stale diagnostics).
  • bash scripts/host_reclaim_shared_host_swap_pressure.sh [--apply] [--host HOST] [--user USER]
  • bash scripts/verify_post_dockerd_core_reconcile_30m.sh
  • bash scripts/host_reconcile_gitea_org_runners.sh
  • bash scripts/host_reconcile_heddle_checkout_main.sh --allow-dirty-reset
  • bash scripts/host_verify_heddle_checkout_validator_bundle.sh
  • bash scripts/host_reconcile_warp_checkout_main.sh --allow-dirty-reset
  • bash scripts/host_verify_warp_production_roster.sh
  • bash scripts/host_reconcile_pattern_checkout_main.sh --allow-dirty-reset reconciles the dedicated &lt;internal-home-redacted&gt; owner checkout backup-first to exact Gitea main; read-only mode fails closed on ignored checkout state, while the explicit allow flag archives tracked, untracked, and ignored state before bounded cleanup. It does not deploy or mutate a runtime.

Windows client checks​

  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_verify_helpifyr_client_readiness.ps1 aggregates Windows DNS, Windows TLS, and Python/OpenSSL trust evidence for the local SSO client lane
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_sync_helpifyr_client_dns.ps1 -PlanOnly
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_verify_helpifyr_client_dns.ps1
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_sync_helpifyr_client_dns.ps1
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_verify_helpifyr_client_tls.ps1
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_sync_helpifyr_client_trust.ps1
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_clear_helpifyr_browser_state.ps1
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_clear_helpifyr_browser_state.ps1 -Apply
  • python scripts/verify_helpifyr_schannel_revocation_chain.py --json

Auth and Access Runtime Checks​

  • OSS SSO Status Matrix (docs/OSS_SSO_STATUS_MATRIX.md)
  • bash scripts/host_verify_erp_identity_lifecycle_boundary.sh
  • bash scripts/host_verify_erp_identity_surface_fabric_parity.sh
  • bash scripts/host_verify_sso_v4_env_auth_runtime.sh
  • bash scripts/host_materialize_gitea_ci_oidc_sso.sh
  • bash scripts/host_verify_proxy_auth_topology.sh
  • bash scripts/host_verify_local_admin_quarantine.sh
  • bash scripts/host_verify_future_module_runtime_auth_onboarding.sh
  • bash scripts/host_verify_helpifyr_tls_client_trust.sh
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts/windows_verify_helpifyr_client_readiness.ps1
  • python scripts/verify_helpifyr_python_tls_client_trust.py --json
  • python scripts/verify_helpifyr_schannel_revocation_chain.py --json
  • python scripts/verify_helpifyr_client_trust_contract.py
  • python scripts/verify_erp_identity_surface_fabric_parity.py
  • python scripts/verify_oss_sso_status_matrix.py
  • python scripts/verify_helpifyr_sso_https_surface_inventory.py
  • python scripts/verify_helpifyr_sso_https_surface_inventory.py --check-live
  • python scripts/verify_helpifyr_sso_https_surface_inventory.py --check-live --ssh-target &lt;internal-runtime-redacted&gt;&lt;internal-runtime-redacted&gt;
  • python scripts/capture_issue2114_asterisk_grafana_workstation_truth.py --reported-browser-failure for the bounded workstation-vs-<internal-runtime-redacted> contradiction lane when Asterisk or Grafana browser SSO is reported broken while the repo-owned launcher and host-managed E2E paths may already be green

Runtime Mutation Rule​

For runtime-affecting changes, always capture:

  1. Pre-change snapshot/evidence
  2. Mutation/apply evidence
  3. Post-change verify evidence
  4. Post-push live verify evidence

Canonical evidence ledger: LIVE_OPERATIONS_LOG.md (docs/LIVE_OPERATIONS_LOG.md)

Credential Reminder​

  • Canonical local operator credential source: ~/.config/helpifyr/operator.env
  • Includes:
    • GITEA_TOKEN
    • host SSH credentials (OPENCLAW_HOST, OPENCLAW_HOST_USER, OPENCLAW_HOST_PW)
    • host sudo password (OPENCLAW_HOST_SUDO_PW)
  • Sanitized verify: python scripts/operator_env.py --json --keys GITEA_TOKEN,OPENCLAW_HOST,OPENCLAW_HOST_USER,OPENCLAW_HOST_SUDO_PW
  • Canonical <internal-runtime-redacted> operator-env staging lane for admitted managed keys: bash scripts/host_stage_operator_env_keys.sh --keys GITEA_TOKEN
  • Canonical bounded <internal-runtime-redacted> Gitea Helpifyr Identity materializer: bash scripts/host_materialize_gitea_ci_oidc_sso.sh
    • hardening policy inputs are env-driven: GITEA_CI_OIDC_GROUP_CLAIM_NAME, GITEA_CI_OIDC_REQUIRED_CLAIM_NAME, GITEA_CI_OIDC_REQUIRED_CLAIM_VALUE, GITEA_CI_OIDC_ADMIN_GROUP, GITEA_CI_OIDC_RESTRICTED_GROUP, GITEA_CI_OIDC_GROUP_TEAM_MAP, GITEA_CI_OIDC_GROUP_TEAM_MAP_REMOVAL
  • Canonical bounded <internal-runtime-redacted> Gitea owner-runtime policy verifier: bash scripts/host_verify_gitea_ci_oidc_source_ci_plane.sh
    • supports explicit expected policy readback for the same claim/team fields
  • Canonical bounded Lantern HITL runtime auth materializer: bash scripts/host_materialize_lantern_runtime_auth_env.sh
  • Canonical bounded Plan Studio Phase-1 owner-binding materializer (requires an owner-approved Keystore source and fails closed when it is absent): bash scripts/host_materialize_plan_studio_owner_bindings.sh
  • Canonical bounded Shuttle Plan Studio C8 owner-token materializer (requires the owner-approved jhf-keystore#289 source and recreates only the C8 service): bash scripts/host_materialize_plan_studio_shuttle_owner_token.sh
  • Canonical bounded Lantern HITL runtime auth verifier: python scripts/verify_issue1637_lantern_runtime_auth_materialization.py
  • Canonical bounded Lantern Customer360 MCP admission verifier: python scripts/verify_issue1693_lantern_customer360_mcp_admission.py
  • Canonical bounded Weft <internal-runtime-redacted> live-Graph env sync lane: bash scripts/host_sync_weft_m365_live_graph_env.sh The lane stages a candidate in the target directory, verifies the downstream Weft secret-ref posture against that candidate, and only then snapshots and atomically replaces the target env file. A failed verifier leaves the target file and mode unchanged.
  • Canonical bounded Weft <internal-runtime-redacted> live-Graph env verifier: python scripts/verify_issue1282_weft_m365_live_graph_env.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud selfhost OIDC env sync lane: bash scripts/host_sync_weft_nextcloud_oidc_env.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud selfhost OIDC env verifier: python scripts/verify_issue1313_weft_nextcloud_oidc_env.py --allow-blocked
  • Canonical bounded <internal-runtime-redacted> Weft checkout dirty-state recovery lane: bash scripts/host_resolve_issue1317_weft_checkout_dirty.sh
  • Canonical bounded <internal-runtime-redacted> Weft checkout dirty-state verifier: python scripts/verify_issue1317_weft_checkout_dirty.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud public OIDC launcher trust sync lane: bash scripts/host_sync_weft_nextcloud_oidc_trust.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud public OIDC launcher trust verifier: python scripts/verify_issue1318_weft_nextcloud_oidc_launcher_trust.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud OIDC callback-landing narrowing lane: bash scripts/host_sync_weft_nextcloud_oidc_callback_landing.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud OIDC callback-landing verifier: python scripts/verify_issue1328_weft_nextcloud_oidc_callback_landing.py --allow-blocked
  • Canonical <internal-runtime-redacted> Weft checkout reconcile lane for bounded selfhost Collabora materialization: bash scripts/host_reconcile_weft_checkout_main.sh --allow-dirty-reset
    • admitted cleanup scope inside this lane is limited to Weft-owned compose/runtime-data* residue after backup capture
    • unrelated dirty state in the <internal-runtime-redacted> Weft checkout remains fail-closed even with --allow-dirty-reset
  • Canonical bounded Weft <internal-runtime-redacted> selfhost Collabora materialization lane: bash scripts/host_materialize_issue1293_weft_collabora_runtime.sh
  • Canonical bounded Weft <internal-runtime-redacted> selfhost Collabora verifier: python scripts/verify_issue1293_weft_collabora_runtime.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> selfhost mail env sync lane: bash scripts/host_sync_weft_selfhost_mail_env.sh
  • Canonical bounded Weft <internal-runtime-redacted> selfhost mail materialization lane: bash scripts/host_materialize_issue1315_weft_selfhost_mail_runtime.sh
  • Canonical bounded Weft <internal-runtime-redacted> selfhost mail verifier: python scripts/verify_issue1315_weft_selfhost_mail_runtime.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> selfhost mail backup/restore drill materializer: bash scripts/host_materialize_issue1358_weft_selfhost_mail_backup_restore.sh
  • Canonical bounded Weft <internal-runtime-redacted> selfhost mail backup/restore drill verifier: python scripts/verify_issue1358_weft_selfhost_mail_backup_restore.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart backup/freshness materializer: bash scripts/host_materialize_issue1565_weft_stalwart_backup_freshness.sh
  • Canonical <internal-runtime-redacted> dangling-Stalwart-bind forensic/reconcile lane: bash scripts/host_reconcile_issue1864_weft_stalwart_data_bind.sh
    • default execution is read-only and reports human_approval_required
    • a restore requires an explicit verified artifact and --apply --human-approved-restore; it must never create or overwrite an empty data root
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart backup/freshness verifier: python scripts/verify_issue1565_weft_stalwart_backup_freshness.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart restore drill from canonical backup materializer: bash scripts/host_materialize_issue1572_weft_stalwart_restore_drill.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart restore drill from canonical backup verifier: python scripts/verify_issue1572_weft_stalwart_restore_drill.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail TLS alignment materializer: bash scripts/host_materialize_issue1361_weft_nextcloud_mail_tls_alignment.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail TLS alignment verifier: python scripts/verify_issue1361_weft_nextcloud_mail_tls_alignment.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail authenticated-send materializer: bash scripts/host_materialize_issue1363_weft_nextcloud_mail_authenticated_send.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail authenticated-send verifier: python scripts/verify_issue1363_weft_nextcloud_mail_authenticated_send.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Calendar/Contacts materialization lane: bash scripts/host_materialize_issue1338_weft_calendar_contacts_runtime.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Calendar/Contacts verifier: python scripts/verify_issue1338_weft_calendar_contacts_runtime.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud public ingress restore lane: bash scripts/host_materialize_issue1495_weft_nextcloud_public_ingress.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud public ingress restore verifier: python scripts/verify_issue1495_weft_nextcloud_public_ingress.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> runtime-state bind reconcile lane: bash scripts/host_materialize_issue1581_weft_runtime_state_bind.sh
  • Canonical bounded Weft <internal-runtime-redacted> runtime-state bind reconcile verifier: python scripts/verify_issue1581_weft_runtime_state_bind.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail TLS/diagnose restore lane: bash scripts/host_materialize_issue1499_weft_nextcloud_mail_tls_diagnose_restore.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail TLS/diagnose restore verifier: python scripts/verify_issue1499_weft_nextcloud_mail_tls_diagnose_restore.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail auth-posture restore lane: bash scripts/host_materialize_issue1500_weft_nextcloud_mail_auth_posture.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail auth-posture restore verifier: python scripts/verify_issue1500_weft_nextcloud_mail_auth_posture.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart live-auth reload lane: bash scripts/host_materialize_issue1514_weft_stalwart_live_auth_reload.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart live-auth reload verifier: python scripts/verify_issue1514_weft_stalwart_live_auth_reload.py --allow-blocked
  • Canonical read-only <internal-runtime-redacted> Stalwart OIDC-directory runtime verifier: python scripts/verify_issue2145_stalwart_oidc_directory_runtime.py --allow-blocked
  • Canonical bounded <internal-runtime-redacted> Stalwart OIDC-directory materializer (preview by default; use --apply only after review and merge): bash scripts/host_materialize_issue2145_stalwart_oidc_directory_runtime.sh [--apply] The apply path settles the post-recreate management readback before evaluating Heddle postconditions and only reports a rollback as completed after a final active-directory readback confirms the restored state.
  • Canonical read-only <internal-runtime-redacted> Stalwart legacy management/OIDC-consumer contract verifier: python scripts/verify_issue2145_stalwart_legacy_management_contract.py --allow-blocked
  • Canonical bounded <internal-runtime-redacted> Stalwart HYBRID directory + admin-UI SSO materializer (jhf-openclaw-env#3233; preview by default; --apply is a lane-separated post-merge Claude-Lane action per helpifyr-fabric#2887 §2, never run from the authoring branch/PR session): bash scripts/host_materialize_issue3233_stalwart_hybrid_directory_sso.sh [--check|--apply|--rollback] --check switches storage.directory from heddle-stalwart-admin to internal only in preview: JML-provisioned principals live in the internal (rocksdb) directory, while the existing heddle-stalwart-admin OIDC directory is kept and extended with the stalwart-webui client-id/secret and a class-map.mailserver_admin -&gt; admin role gate so it authenticates only human admin-UI logins admitted by the Heddle Fabric-admission provider (see JaddaHelpifyr/jhf-heddle docs/STALWART_FABRIC_ADMISSION_PROVIDER.md for the stalwart_management_admitted / management_scope claim contract). --apply backs up config.toml first, verifies the fallback-admin path and the container-internal OIDC discovery endpoint stay reachable, and auto-rolls back on any postcondition failure. --rollback restores the most recent backup. The client secret is read from the Heddle-owned &lt;internal-home-redacted&gt; (STALWART_WEBUI_OIDC_CLIENT_SECRET, 0600) and is never printed; readback only reports presence/absence booleans. The host-side management API base URL is OPENCLAW_STALWART_MGMT_URL (default http://&lt;internal-runtime-redacted&gt;:18082); after the WEFT-M01 bind change (jhf-weft#721) the admin/JMAP publish lives on the docker bridge gateway, so pass OPENCLAW_STALWART_MGMT_URL=http://&lt;bridge-gateway&gt;:18082 (docker network inspect bridge -f '&#123;&#123;(index .IPAM.Config 0).Gateway&#125;&#125;'). The container-internal OIDC discovery probe uses wget when present and falls back to a bash /dev/tcp GET because the Stalwart image ships no HTTP client.
  • Canonical <internal-runtime-redacted> Heddle Keycloak Stalwart signed-admission provider lane (jhf-openclaw-env#3252, program helpifyr-fabric#3537, refs jhf-heddle#776/#777, jhf-openclaw-env#3242; the --apply/--rollback steps are a lane-separated post-merge Claude-Lane action inside an Owner-confirmed window, never run from the authoring session): OPENCLAW_HOST=&lt;host-alias&gt; bash scripts/host_materialize_issue3252_heddle_stalwart_signed_admission_provider.sh --check ... --apply --confirm-window &lt;id&gt; / ... --rollback --confirm-window &lt;id&gt; The lane repoints STALWART_FABRIC_DECISION_URL to .../stalwart-management/admission, adds STALWART_FABRIC_JWKS_URL, STALWART_FABRIC_ADMISSION_ISSUER and STALWART_FABRIC_ADMISSION_AUDIENCE (issuer/audience/read token from jhf-fabric-auth.env, fail closed when empty) and carries tenant/company/environment over from the durable .../runtime-secrets/jhf-heddle-stalwart-provider.env (fail closed when absent, never invented). Every compose call uses the same --project-name and --env-file (the values were lost live when the container was recreated without the env file). --check is read-only drift verification (container env vs durable file vs compose render vs Fabric overlay; names, non-secret values and sha256 fingerprints only) plus /jwks 200 and the container token on /admission and /decision (200/422, not 401). --apply snapshots (redacted inspect, env copy, rollback image tag), rewrites the durable file, rebuilds jhf-heddle-keycloak:stalwart-management-provider from clean jhf-heddle main, recreates only keycloak, re-runs the check and rolls back automatically on failure. Receipts: runtime/evidence/issue3252-heddle-stalwart-signed-admission.&lt;stamp&gt;/receipt-&lt;mode&gt;.json. Compose success is decided by exit code only (the variable is not set warning storm for other services is ignored and never reaches a receipt); before recreating, the compose render of the keycloak service must equal the running container in every key except the intended STALWART_FABRIC_* ones (fail closed). The Fabric probe runs in the container and falls back to host-side curl (ISSUE3252_HOST_PROBE_BASE maps the docker-internal Fabric base to a host-reachable one; token via private header file, never argv). The Heddle checkout gate ignores untracked files (status --porcelain --untracked-files=no) and runs git with -c safe.directory=&lt;checkout&gt;. The script never uses cd (the operator cannot traverse &lt;internal-home-redacted&gt;): compose runs as sudo -n docker compose --project-name ... --env-file &lt;abs&gt; --project-directory &lt;abs&gt; -f &lt;abs&gt;, git as the checkout owner with -c safe.directory. --apply probes Fabric host-side (overlay token, status codes only) before touching anything, records a pre-apply baseline (unrelated pre-existing drift never triggers the automatic rollback), proves the rebuilt image ships FabricAdmissionVerifier/FabricJwksSource/ FabricDecisionReader in the provider jar (jar sha256 in the receipt) before the recreate, writes the env file atomically, holds a lock dir, and ends with failed_rollback_failed (exit 1) when the automatic rollback itself fails. The on-host body re-validates mode and --confirm-window. Compose interpolates the whole project (every service), and the running container was created with the project default env, so every compose call passes BOTH env files: --env-file &lt;checkout&gt;/.env --env-file &lt;durable provider env&gt; (later wins, so the durable STALWART_FABRIC_* override). The .env path is HEDDLE_PROJECT_ENV (default &lt;checkout&gt;/.env); it must exist (else blocked_missing_heddle_project_env), is only read, and no value from it is ever printed or receipted. The render guard compares the rendered keycloak environment from both files with the running container: every key except the intended STALWART_FABRIC_* must be equal, otherwise blocked_keycloak_render_differs_from_running_container. The compose label com.docker.compose.project.environment_file is empty when the project default env was used; compose records repeated --env-file arguments comma-joined there (assumed, to be confirmed live), so after the apply the label may be empty, &lt;checkout&gt;/.env,&lt;durable&gt; or either single file, anything else is reported as env_file_label_problem. The older 2135 materializer is superseded for these inputs.
  • Canonical read-only <internal-runtime-redacted> Stalwart hybrid-directory/SSO verifier (also reports the raw port 18082 socket binding for the WEFT-M01 follow-up): python scripts/verify_issue3233_stalwart_hybrid_directory_sso.py --host &lt;alias&gt; --allow-blocked --management-url (default from env OPENCLAW_STALWART_MGMT_URL, else http://&lt;internal-runtime-redacted&gt;:18082) sets the remote-side Stalwart management API base URL used for every settings call, mirroring the materializer's own OPENCLAW_STALWART_MGMT_URL; after the WEFT-M01 bind change (jhf-weft#721) pass the bridge-gateway URL there too. The port 18082 binding is classified as loopback_only (<internal-runtime-redacted>/::1 only), host_only_bridge_gateway (every listener on the single non-loopback address that equals the docker bridge gateway, read remotely via docker network inspect bridge -f '&#123;&#123;(index .IPAM.Config 0).Gateway&#125;&#125;') — the admitted post-WEFT-M01 posture, treated the same as loopback_only — or 0.0.0.0_public (anything else), which always stays a blocking finding.
  • Canonical read-only Stalwart admin ingress verifier (route, DNS, TLS, and direct-port posture; --pre-closure requires explicit proxy/SSO evidence): bash scripts/host_verify_stalwart_management_ingress.sh [--pre-closure]
  • Canonical controlled direct-port closure lane (preview by default; never run --apply until proxy/SSO readback is green and a human ticket is recorded): bash scripts/host_apply_issue1865_stalwart_direct_port_closure.sh [--apply|--rollback]
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail restart-readiness lane: bash scripts/host_materialize_issue1517_weft_nextcloud_mail_restart_readiness.sh
  • Canonical bounded Weft <internal-runtime-redacted> Nextcloud Mail restart-readiness verifier: python scripts/verify_issue1517_weft_nextcloud_mail_restart_readiness.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> functional mailbox inventory/owner readback lane: bash scripts/host_materialize_issue1566_weft_functional_mailbox_owner_readback.sh
  • Canonical bounded Weft <internal-runtime-redacted> functional mailbox inventory/owner readback verifier: python scripts/verify_issue1566_weft_functional_mailbox_owner_readback.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> shared-mailbox ownership/work-claim readback lane: bash scripts/host_materialize_issue1577_weft_shared_mailbox_work_claim_readback.sh
  • Canonical bounded Weft <internal-runtime-redacted> shared-mailbox ownership/work-claim readback verifier: python scripts/verify_issue1577_weft_shared_mailbox_work_claim_readback.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> deferred functional/shared mailbox delegation verifier: python scripts/verify_issue1340_weft_mailbox_delegation_deferred.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> explicit functional/shared mailbox principal-gap verifier: python scripts/verify_issue1346_weft_functional_mailbox_principal_gap.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> functional mailbox principal materializer: bash scripts/host_materialize_issue1349_weft_functional_mailbox_principal.sh
  • Canonical bounded Weft <internal-runtime-redacted> functional mailbox principal materialized verifier: python scripts/verify_issue1349_weft_functional_mailbox_principal_materialized.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> delegated mailbox usage narrowing verifier: python scripts/verify_issue1351_weft_delegated_mailbox_usage_narrowed.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> direct functional mailbox JMAP auth materializer: bash scripts/host_materialize_issue1354_weft_functional_mailbox_auth_surface.sh
  • Canonical bounded Weft <internal-runtime-redacted> direct functional mailbox JMAP auth verifier: python scripts/verify_issue1354_weft_functional_mailbox_auth_surface.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> shared-mailbox ownership materializer: bash scripts/host_materialize_issue1365_weft_shared_mailbox_ownership.sh
  • Canonical bounded Weft <internal-runtime-redacted> shared-mailbox ownership verifier: python scripts/verify_issue1365_weft_shared_mailbox_ownership.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> alternative mailbox-group relation materializer: bash scripts/host_materialize_issue1370_weft_mailbox_group_alt_path.sh
  • Canonical bounded Weft <internal-runtime-redacted> alternative mailbox-group relation verifier: python scripts/verify_issue1370_weft_mailbox_group_alt_path.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart capability-gap materializer: bash scripts/host_materialize_issue1373_weft_stalwart_capability_gap.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart capability-gap verifier: python scripts/verify_issue1373_weft_stalwart_capability_gap.py --allow-blocked
    • exact-main relation/JMAP chain source: scripts/fixtures/issue1370.weft_mailbox_group_alt_path.readback.json
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart candidate-compatibility materializer: bash scripts/host_materialize_issue1378_weft_stalwart_compatibility.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart candidate-compatibility verifier: python scripts/verify_issue1378_weft_stalwart_compatibility.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart version-lift rehearsal materializer: bash scripts/host_materialize_issue1380_weft_stalwart_rehearsal.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart version-lift rehearsal verifier: python scripts/verify_issue1380_weft_stalwart_rehearsal.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart copied-config compatibility materializer: bash scripts/host_materialize_issue1382_weft_stalwart_config_gap.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart copied-config compatibility verifier: python scripts/verify_issue1382_weft_stalwart_config_gap.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart config regeneration materializer: bash scripts/host_materialize_issue1384_weft_stalwart_config_regeneration.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart config regeneration verifier: python scripts/verify_issue1384_weft_stalwart_config_regeneration.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart copied-runtime ownership translation materializer: bash scripts/host_materialize_issue1386_weft_stalwart_ownership_translation.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart copied-runtime ownership translation verifier: python scripts/verify_issue1386_weft_stalwart_ownership_translation.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart post-translation v0.15 bridge materializer: bash scripts/host_materialize_issue1388_weft_stalwart_v015_bridge.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart post-translation v0.15 bridge verifier: python scripts/verify_issue1388_weft_stalwart_v015_bridge.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.15.5 bridge rehearsal materializer: bash scripts/host_materialize_issue1390_weft_stalwart_v015_rehearsal.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.15.5 bridge rehearsal verifier: python scripts/verify_issue1390_weft_stalwart_v015_rehearsal.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.16 dump/convert helper materializer: bash scripts/host_materialize_issue1392_weft_stalwart_v016_dump_convert.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.16 dump/convert helper verifier: python scripts/verify_issue1392_weft_stalwart_v016_dump_convert.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.16 tomllib-prerequisite materializer: bash scripts/host_materialize_issue1394_weft_stalwart_v016_tomllib_prereq.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.16 tomllib-prerequisite verifier: python scripts/verify_issue1394_weft_stalwart_v016_tomllib_prereq.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart helper-auth classification materializer: bash scripts/host_materialize_issue1396_weft_stalwart_helper_auth_gap.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart helper-auth classification verifier: python scripts/verify_issue1396_weft_stalwart_helper_auth_gap.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart management-credential-source materializer: bash scripts/host_materialize_issue1397_weft_stalwart_management_credential_source.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart management-credential-source verifier: python scripts/verify_issue1397_weft_stalwart_management_credential_source.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart canonical host-secret-contract materializer: bash scripts/host_materialize_issue1399_weft_stalwart_management_secret_contract.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart canonical host-secret-contract verifier: python scripts/verify_issue1399_weft_stalwart_management_secret_contract.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart runtime-secret env contract-admission materializer: bash scripts/host_materialize_issue1402_weft_stalwart_management_secret_env_contract.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart runtime-secret env contract-admission verifier: python scripts/verify_issue1402_weft_stalwart_management_secret_env_contract.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart runtime-secret env unstaged-gap materializer: bash scripts/host_materialize_issue1404_weft_stalwart_management_secret_env_staging_gap.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart runtime-secret env unstaged-gap verifier: python scripts/verify_issue1404_weft_stalwart_management_secret_env_staging_gap.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input-source gap materializer: bash scripts/host_materialize_issue1406_weft_stalwart_secure_input_source_gap.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input-source gap verifier: python scripts/verify_issue1406_weft_stalwart_secure_input_source_gap.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input-source contract-gap materializer: bash scripts/host_materialize_issue1408_weft_stalwart_secure_input_source_contract_gap.sh
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input-source contract-gap verifier: python scripts/verify_issue1408_weft_stalwart_secure_input_source_contract_gap.py --allow-blocked
    • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input-source materialization-gap materializer: bash scripts/host_materialize_issue1410_weft_stalwart_secure_input_source_materialization_gap.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input-source materialization-gap verifier: python scripts/verify_issue1410_weft_stalwart_secure_input_source_materialization_gap.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input sync/stage-gap materializer: bash scripts/host_materialize_issue1412_weft_stalwart_secure_input_source_sync_stage_gap.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart secure-input sync/stage-gap verifier: python scripts/verify_issue1412_weft_stalwart_secure_input_source_sync_stage_gap.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart operator-env managed-key-gap materializer: bash scripts/host_materialize_issue1414_weft_stalwart_operator_env_managed_key_gap.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart operator-env managed-key-gap verifier: python scripts/verify_issue1414_weft_stalwart_operator_env_managed_key_gap.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart dedicated runtime-secret stage-wrapper-gap materializer: bash scripts/host_materialize_issue1416_weft_stalwart_stage_wrapper_gap.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart dedicated runtime-secret stage-wrapper-gap verifier: python scripts/verify_issue1416_weft_stalwart_stage_wrapper_gap.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart managed-key-family-admission materializer: bash scripts/host_materialize_issue1418_weft_stalwart_managed_key_family_admission.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart managed-key-family-admission verifier: python scripts/verify_issue1418_weft_stalwart_managed_key_family_admission.py --allow-blocked
  • Canonical Weft Stalwart runtime-secret stage wrapper: bash scripts/host_stage_weft_stalwart_management_env.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart dedicated stage-wrapper materializer: bash scripts/host_materialize_issue1420_weft_stalwart_stage_wrapper_materialization.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart dedicated stage-wrapper verifier: python scripts/verify_issue1420_weft_stalwart_stage_wrapper_materialization.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart stage-replay source-gap materializer: bash scripts/host_materialize_issue1423_weft_stalwart_stage_source_gap.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart stage-replay source-gap verifier: python scripts/verify_issue1423_weft_stalwart_stage_source_gap.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart successful stage-replay materializer: bash scripts/host_materialize_issue1461_weft_stalwart_stage_replay.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart successful stage-replay verifier: python scripts/verify_issue1461_weft_stalwart_stage_replay.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart post-secret helper-auth reprobe materializer: bash scripts/host_materialize_issue1471_weft_stalwart_helper_auth_reprobe.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart post-secret helper-auth reprobe verifier: python scripts/verify_issue1471_weft_stalwart_helper_auth_reprobe.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart fallback-admin hash alignment materializer: bash scripts/host_materialize_issue1479_weft_stalwart_fallback_admin_hash_alignment.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart fallback-admin hash alignment verifier: python scripts/verify_issue1479_weft_stalwart_fallback_admin_hash_alignment.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart runtime-drift reconcile materializer: bash scripts/host_materialize_issue1483_weft_stalwart_runtime_drift.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart runtime-drift reconcile verifier: python scripts/verify_issue1483_weft_stalwart_runtime_drift.py --allow-blocked
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.15.5 production bridge-cutover materializer: bash scripts/host_materialize_issue1487_weft_stalwart_v015_cutover.sh
  • Canonical bounded Weft <internal-runtime-redacted> Stalwart v0.15.5 production bridge-cutover verifier: python scripts/verify_issue1487_weft_stalwart_v015_cutover.py --allow-blocked
  • Canonical Weft <internal-runtime-redacted> Stalwart v0.15.5 -> v0.16.x cutover lane (jhf-openclaw-env#3243, program helpifyr-fabric#3537), modes --check (read-only plan), --backup, --rehearse (on a copy, incl. rollback test), --apply, --rollback: bash scripts/host_materialize_issue3243_weft_stalwart_v016_cutover.sh --check
  • Canonical Weft <internal-runtime-redacted> Stalwart v0.16.x cutover verifier (receipt classification, live gates, cutover-time inventory patch and change list): python scripts/verify_issue3243_weft_stalwart_v016_cutover.py --run-check --allow-blocked
    • --backup, --apply and --rollback require --confirm-window &lt;id&gt; (the Owner-confirmed downtime window); nothing in this lane runs on merge
    • status: the live cutover to stalwartlabs/stalwart:v0.16.23 (digest sha256:be215678796691bc39bdda918ecc50d14a9032a099a1d1950e51950aec7e2592) was completed on 2026-09-26 (apply backup 20260925T231851Z-apply, pre-window backup 20260925T223628Z); 0.15.5 is now only the recorded source/rollback image. Host env after the cutover: WEFT_STALWART_IMAGE=stalwartlabs/stalwart:v0.16.23, WEFT_STALWART_DATA_DIR=/var/lib/stalwart, config root &lt;data-root&gt;/etc016 at /etc/stalwart (written by scripts/host_sync_weft_selfhost_mail_env.sh)
    • warning: after a --rollback re-pin the host stalwart.env to WEFT_STALWART_IMAGE=stalwartlabs/stalwart:v0.15.5 and WEFT_STALWART_DATA_DIR=/opt/stalwart by hand (the lane rollback only uses a private env copy). A plain compose up, the env sync plus recreate, or the 1315 materializer recreates the container from the tag-only image and drops the lane override (OIDC extra_hosts, SSL_CERT_FILE bundle, command reset, exact tag@digest): do not run them against the cut-over host until jhf-weft compose OIDC/CA support exists
    • runbook note (#3246): phase B runs with live queues (normal mode, recovery admin still set) and without --dns &lt;internal-runtime-redacted&gt; on the apply path, so outbound delivery and ACME can start against the live data root; keep the window closed to mail traffic until the final container is up. Phase A/B containers are stopped with docker stop -t 30 before removal, recovery.env is 0600, and certificate-tool output never reaches a receipt
    • the Heddle timer jhf-heddle-stalwart-mailbox-projection.timer is stopped for the window and kept stopped after apply (the deployed projector may still be the 0.15 REST version until jhf-heddle#769); the receipt carries timer_state and timer_start_command, WEFT_STALWART_RESTART_TIMER=1 opts into a restart after the projector probe
  • Canonical bounded Weft <internal-runtime-redacted> post-v0.15.5 helper/hash config-path re-anchor owner issue: JaddaHelpifyr/jhf-openclaw-env#1488
    • active runtime config truth after the cutover is the live /opt/stalwart/etc/config.toml path family when present
    • legacy /opt/stalwart-mail remains compatibility-only and must not stay the default assumption in helper/hash readback lanes
  • Canonical bounded Weft <internal-runtime-redacted> selfhost mail deliverability verifier: python scripts/verify_issue1331_weft_selfhost_mail_deliverability.py --allow-blocked
  • The bounded Weft live-Graph owner posture now includes both:
    • Graph URL/ref keys
    • non-demo M365 identifiers (WEFT_M365_TENANT_ID, WEFT_M365_SITE_ID, WEFT_M365_DRIVE_ID)
  • Default posture: stages only requested managed keys into &lt;internal-home-redacted&gt; on <internal-runtime-redacted>, preserves unrelated remote entries, never prints secret values, and fails closed when a requested key is missing locally.
  • . is legacy fallback only and must not be treated as the canonical accumulation path.

OpenClaw Model Runtime Note​

  • Canonical default model policy is deepseek/deepseek-v4-flash for all standard OpenClaw agents and runtime-generated heartbeat/subagent lanes.
  • Explicit model exceptions are limited to:
    • jadda-voice-warm -&gt; anthropic/claude-haiku-4-5
  • Repository verifier: python scripts/verify_openclaw_agent_model_policy.py
  • Live reconcile: bash scripts/host_reconcile_openclaw_agent_model_policy.sh
  • Live verify: python scripts/verify_openclaw_agent_model_policy.py --live-via-ssh &lt;internal-runtime-redacted&gt;&lt;internal-runtime-redacted&gt;
  • Required success signal: a bounded real main turn must start successfully; config or roster readback alone is not enough.

Repo-Local Scan&Fix Automation​

  • canonical execution standard prompt: prompts/scan_and_fix_execution_standard.md
  • canonical dispatcher: scripts/scan_and_fix.sh
  • default posture:
    • Gitea open issues are the Source of Truth
    • serial dispatch is worktree-safe and repo-scoped
    • real execution uses --executor-cmd or local openclaw CLI when present
    • --dry-run is required for safe prompt inspection without execution

Repo-Local Scan&Pull Automation​

  • canonical merge dispatcher: scripts/scan_and_pull.sh
  • canonical implementation: scripts/scan_and_pull.py
  • default posture:
    • Gitea open pull requests are the Source of Truth
    • use --mode scan with GITEA_TOKEN for a read-only queue; use --mode review --owner &lt;owner&gt; --repo &lt;repo&gt; --number &lt;number&gt; with GITEA_MERGE_TOKEN to submit and read back an exact-head Gitea APPROVED; use --mode merge with GITEA_MERGE_ACTOR_TOKEN to merge
    • the wrapper resolves and exports exactly one role token per process; reviewer and merge-actor credentials are never loaded together
    • owner repository discovery requests every Gitea page through the terminal empty page and preserves first-seen repository order without duplicates
    • merge only when mergeable=true and an explicit redacted status-authority record matches the exact owner/repository/PR/head, uses event pull_request, and records a terminal-success run and job. The contract is contracts/ci/scan_and_pull_status_authority_v1.json; aggregate commit state and latest contexts remain diagnostic and are not sufficient authority. The independent local approval record and the persisted Gitea APPROVED state exactly match the current head; reviewer, author, and merge actor must be three distinct identities; any authority mismatch, missing field, or non-terminal/non-success run or job remains fail-closed
    • the merge request uses Gitea's documented lowercase do action field and includes the exact admitted head_commit_id
    • approvals default to artifacts/scan_and_pull/review_approvals.json; set SCAN_AND_PULL_REVIEW_APPROVALS_FILE or pass --review-approvals-file for an explicit artifact override. The JSON object must contain an approvals array of records with owner, repo, number, head, and reviewer; the reviewer must differ from the PR author.
    • the merge actor never closes issues; perform owner-bounded post-merge evidence and a separate GITEA_TOKEN closeout before changing issue state
    • a head reachable from its base while Gitea reports merged=false is an integrated_pr_audit_conflict: Scan&Pull records it with mutation: none and never closes or merges that PR. The conflict stays fail-closed for that PR but does not block evaluation of an unrelated candidate that satisfies every exact-head approval and CI gate.
    • --dry-run is required for safe review or merge preview without mutation
    • status authority defaults to artifacts/scan_and_pull/status_authority.json; set SCAN_AND_PULL_STATUS_AUTHORITY_FILE or pass --status-authority-file. Missing, stale, mismatched, non-terminal, unredacted, duplicate, or ambiguous authority evidence remains fail-closed.

Post-Merge Mainline Reconcile​

  • canonical post-merge reconcile entrypoint: python scripts/post_merge_mainline_reconcile.py
  • canonical delivery evidence verifier: python scripts/verify_agent_platform_delivery_evidence_lane.py
  • canonical delegated closeout verifier: python scripts/verify_agent_delegated_closeout_evidence_lane.py
  • default posture:
    • Gitea PR merge truth is authoritative
    • reconcile only the directly affected repo
    • local main readback and remote owner-checkout main readback are mandatory
    • runtime reconcile is owner-bounded and command-driven, not host-global
    • runtime stays unreconciled until bounded runtime verify/readback succeeds
    • the canonical closeout sequence remains: gitea_merge_readback -&gt; local_main_readback -&gt; remote_owner_checkout_readback -&gt; runtime_reconcile -&gt; runtime_verify_against_running_main
    • delegated closeout bundles add one more bounded proof layer: required artifact-bundle completeness plus visual evidence when the Fabric work-type posture marks it required
    • canonical post-merge replay for the <internal-runtime-redacted> heavy-workload guardrail: bash scripts/host_verify_issue758_759_heavy_workload_guardrail.sh --exercise-heavy-lanes
  • canonical jhf-openclaw-env lane after merge of a runtime-relevant PR: 
    python scripts/post_merge_mainline_reconcile.py \
      --pr 627 \
      --remote-host &lt;internal-runtime-redacted&gt; \
      --remote-user administrator \
      --remote-checkout &lt;internal-home-redacted&gt; \
      --remote-reconcile-command "bash scripts/host_reconcile_openclaw_env_checkout_main.sh --host &lt;internal-runtime-redacted&gt; --user administrator --allow-dirty-reset" \
      --runtime-source "systemd guardrail units plus repo-owned scripts under &lt;internal-home-redacted&gt;" \
      --runtime-reconcile-command "bash scripts/host_start_openclaw_guardrail.sh --host &lt;internal-runtime-redacted&gt; --user administrator --start-now" \
      --runtime-verify-command "bash scripts/host_openclaw_runtime_guardrail.sh --host &lt;internal-runtime-redacted&gt; --user administrator" \
      --runtime-verify-command "ssh &lt;internal-runtime-redacted&gt;&lt;internal-runtime-redacted&gt; \"systemctl show jhf-openclaw-env-guardrail.service -p ExecMainStatus -p Result && systemctl show jhf-openclaw-env-guardrail.timer -p UnitFileState -p ActiveState -p SubState\""

Contracts and Policies​

  • STACK_RUNTIME_CONTRACT.md (docs/STACK_RUNTIME_CONTRACT.md)
  • SSO_HTTPS_SURFACE_INVENTORY.md (docs/SSO_HTTPS_SURFACE_INVENTORY.md)
  • ERP_IDENTITY_LIFECYCLE_BOUNDARY.md (docs/ERP_IDENTITY_LIFECYCLE_BOUNDARY.md)
  • RUNTIME_PORT_OBSERVATION_POLICY.md (docs/RUNTIME_PORT_OBSERVATION_POLICY.md)
  • SSO_V4_ENV_AUTH_RUNTIME.md (docs/SSO_V4_ENV_AUTH_RUNTIME.md)
  • FUTURE_MODULE_RUNTIME_AUTH_ONBOARDING.md (docs/FUTURE_MODULE_RUNTIME_AUTH_ONBOARDING.md)
  • SECRETS_AND_ENV_POLICY.md (docs/SECRETS_AND_ENV_POLICY.md)
  • M365_FILE_GRAPH_PROFILE.md (jhf-weft/docs/M365_FILE_GRAPH_PROFILE.md)

Incident/Recovery Runbooks​

  • AUTONOMOUS_RESTART_GUARDRAIL.md (docs/AUTONOMOUS_RESTART_GUARDRAIL.md)
  • GITEA_ORG_RUNNER_RECOVERY_RUNBOOK.md (docs/GITEA_ORG_RUNNER_RECOVERY_RUNBOOK.md)
  • ROLLBACK_AND_RECOVERY.md (docs/ROLLBACK_AND_RECOVERY.md)
  • CLIENT_TLS_TRUST_RUNBOOK.md (docs/CLIENT_TLS_TRUST_RUNBOOK.md)

Scan&Fix Runbook​

Schnellstart​

bash scripts/scan_and_fix.sh
  • Processes this repo's open Gitea issue queue serially by default.
  • Uses prompts/scan_and_fix_execution_standard.md as the runtime standard block.

Dry-Run​

bash scripts/scan_and_fix.sh --dry-run
  • Shows the selection and prompt preview.
  • Does not dispatch an executor.

Live-Run (bounded)​

bash scripts/scan_and_fix.sh --max-issues 5
  • Runs a bounded serial pass for the first N issues in priority order.

Typische Fehlerbilder​

  • GITEA_TOKEN missing: Token fehlt im kanonischen Operator-Env ~/.config/helpifyr/operator.env oder in HELPIFYR_OPERATOR_ENV_FILE; . wird in der Scan-Lane nicht mehr als stiller Fallback akzeptiert.
  • Cannot infer repo owner/name: origin Remote oder --repo-owner/--repo-name korrigieren.
  • scan_and_fix requires a pushed branch: for the OpenClaw executor, first push the current branch to origin or switch to a branch that already has a remote head; local reconcile-only branches without a remote head are now rejected fail-closed immediately.
  • Visible wait lines: scanfix_runner_heartbeat or scanfix_executor_heartbeat mean that the serial run is still active; they are not a stuck lock, but the bounded heartbeat during an active agent turn.
  • Local Codex fallback: if no --executor-cmd is set, scan_and_fix.sh uses gpt-5.4 by default; a different locally verified model can be selected with SCAN_AND_FIX_CODEX_MODEL.
  • Local executor failure: check the standard executor scripts/scan_and_fix_openclaw_executor.sh (openclaw-gateway, SSH/host access, agent timeout); override it explicitly with --executor-cmd only when needed.

License: AGPLv3 Project: https://helpifyr.com

Workspace Git/Scan Guardrails (Mandatory)​

  • Gitea is Source of Truth; local Windows workspaces are disposable working copies.
  • Never run Codex sessions on &lt;local-workspace-redacted&gt; root; always use a concrete repo path.
  • Limit active repo sessions to 2-3 in parallel.
  • Before each run in a repo: git fetch --prune, git checkout &lt;branch&gt;, git pull --ff-only.
  • No background git discovery loops (git status, git ls-files, worktree scans) without explicit scoped need.
  • Automation scripts must run repo-scoped only, never global over &lt;local-workspace-redacted&gt;.

scan_and_fix Standard​

  • scripts/scan_and_fix.sh must resolve credentials through scripts/operator_env.py, keep legacy root .env as compatibility fallback only, and fail closed when required keys are missing.
  • scripts/scan_and_fix_openclaw_executor.sh is the canonical repo-aware host executor when a live OpenClaw turn must prove workspace path + branch inside openclaw-gateway.
  • scripts/scan_open_issues_repo_only.sh must exist and query only current repo open issues via Gitea API.

Workspace Hygiene​

  • Daily cleanup: stale _worktrees/*, _tmp/*, test-results/*, large temporary artifacts.
  • Weekly cleanup: stale local branches/worktrees.
  • Never leave valuable artifacts as untracked files in workspace root.

Dirty-State Policy​

  • Dirty state is allowed while actively implementing.
  • Before new scan/automation runs: commit/stash, or use a dedicated worktree.
  • Never propagate dirty_unknown states.

Incident Playbook (git.exe storm)​

  1. Identify parent of git.exe (usually one Codex.exe).
  2. Stop only the offending process tree.
  3. Restart session on concrete repo path.
  4. Reduce parallel sessions.
  5. Verify git.exe count drops within 30-60s.

Weft Mail Public Surface DNS/Ingress Posture​

  • issue owner lane:
    • jhf-openclaw-env#1588
  • parent future owner lane:
    • jhf-openclaw-env#1587
  • upstream program:
    • jhf-weft#6
  • bounded runtime expectations:
    • &lt;internal-runtime-redacted&gt; is admitted in the repo-owned AdGuard rewrite list for <internal-runtime-redacted>
    • Caddy terminates tls internal for &lt;internal-runtime-redacted&gt;
    • the public surface stays bounded to a redirect into apps/mail
    • owner verify distinguishes missing DNS/ingress surfacing from later Weft/SSO/product gaps
  • scope boundary:
    • this lane proves bounded public DNS/TLS/redirect surfacing only
    • it must not be overstated as standalone mail-product completion, mailbox provisioning, or Heddle SSO admission

Canonical bounded Weft <internal-runtime-redacted> &lt;internal-runtime-redacted&gt; host-preserving public surface lane (jhf-openclaw-env#1595)​

  • Canonical materializer:
    • bash scripts/host_materialize_issue1595_weft_mail_public_surface.sh
  • Canonical verifier:
    • python scripts/verify_issue1595_weft_mail_public_surface.py --allow-blocked
  • Upstream refs:
    • jhf-openclaw-env#1587
    • jhf-weft#559
    • jhf-heddle#298
    • jhf-weft#6
  • bounded runtime expectations:
    • &lt;internal-runtime-redacted&gt;/ redirects only to apps/mail
    • /apps/mail/, /login, and the OIDC launcher stay canonical on &lt;internal-runtime-redacted&gt;
    • if Heddle still rejects the rewritten mail callback, the verifier classifies heddle_mail_redirect_uri_not_admitted
  • scope boundary:
    • this lane proves host-preserving public ingress/runtime surfacing only
    • it must not be overstated as full Heddle admission, standalone mailbox-product completion, or broad selfhost mail readiness

Canonical bounded Weft <internal-runtime-redacted> &lt;internal-runtime-redacted&gt; trusted-domain and overwritehost runtime lane (jhf-openclaw-env#1597)​

  • Canonical materializer:
    • bash scripts/host_materialize_issue1597_weft_mail_host_ingress_runtime.sh
  • Canonical verifier:
    • python scripts/verify_issue1597_weft_mail_host_ingress_runtime.py --allow-blocked
  • Upstream refs:
    • jhf-weft#576
    • jhf-openclaw-env#1595
    • jhf-weft#559
    • jhf-weft#6
  • bounded runtime expectations:
    • owner env truth in compose/nextcloud-selfhost.env is upserted to the canonical mail-host values before reconcile
    • nextcloud-selfhost is force-recreated from the reconciled env truth before OCC-level ingress reconcile runs
    • <internal-runtime-redacted> Nextcloud trusted_domains readback contains &lt;internal-runtime-redacted&gt;
    • <internal-runtime-redacted> overwritehost reads back &lt;internal-runtime-redacted&gt;
    • <internal-runtime-redacted> overwrite.cli.url reads back https://&lt;internal-runtime-redacted&gt;
    • bounded authenticated webmail verify is rerun against the canonical mail host after reconcile
  • scope boundary:
    • this lane proves owner-side Nextcloud config/runtime convergence for the canonical mail host
    • it must not be overstated as broad selfhost mail product completion beyond the bounded webmail proof

Canonical bounded Weft <internal-runtime-redacted> dual-host OIDC callback runtime lane (jhf-openclaw-env#1600)​

  • Canonical materializer:
    • bash scripts/host_materialize_issue1600_weft_dual_host_oidc_callback.sh
  • Canonical verifier:
    • python scripts/verify_issue1600_weft_dual_host_oidc_callback.py --allow-blocked
  • Upstream refs:
    • jhf-openclaw-env#1600
    • jhf-openclaw-env#1587
    • jhf-weft#588
    • jhf-heddle#298
    • jhf-weft#6
  • bounded runtime expectations:
    • apps/user_oidc stays canonical on &lt;internal-runtime-redacted&gt;
    • apps/user_oidc stays canonical on &lt;internal-runtime-redacted&gt;
    • both launchers keep distinct encoded redirect_uri callback hosts instead of collapsing onto one host
    • if Heddle still rejects one callback host, the verifier classifies the remaining blocker explicitly instead of overclaiming broad SSO admission
  • scope boundary:
    • this lane proves bounded dual-host launcher/callback canonicalization only
    • it must not be overstated as broad Weft selfhost SSO completion, full logout/session admission, or mailbox-product completion