Skip to main content

Troubleshooting

Scope​

This page is the canonical v1.6 troubleshooting surface for jhf-loom.

It is intentionally command-first and points to bounded diagnostics instead of ad-hoc host probing.

Common Failure Classes​

Search Mandatory Gate Fails​

Symptoms:

  • readiness is red
  • search service is unhealthy or delayed

Likely owner:

  • JaddaHelpifyr/jhf-loom

First checks:

  • confirm readiness is red before collecting broader diagnostics
  • validate the runtime contract to rule out repo/runtime drift first

Run:

bash scripts/loom-runtime-control.sh readiness
python scripts/validate_runtime_contract.py

Evidence to collect:

  • readiness command output
  • runtime contract validator output

Next action:

  • if search remains unhealthy after bounded postcheck, continue with docs/OPERATIONS.md and attach the bounded diagnostics output to the Loom owner issue

Escalation path:

  • ingress/auth symptoms -> jhf-openclaw-env or jhf-heddle
  • search/runtime symptoms -> stay in jhf-loom

Verify after recovery:

bash scripts/loom-runtime-control.sh postcheck
bash scripts/loom-runtime-control.sh readiness

Runtime Materialization Drift​

Symptoms:

  • repo truth and live stack diverge
  • app readback does not match compose/runtime truth

Likely owner:

  • JaddaHelpifyr/jhf-loom

First checks:

  • compare repo truth and live stack with the repo-owned drift validator first
  • avoid ad-hoc manual host probing before the validator output exists

Run:

python scripts/validate_runtime_materialization_drift.py
python scripts/validate_runtime_materialization_drift.py --host <live-host> --stack-dir <owner-runtime-stack-dir> --insecure

Evidence to collect:

  • local drift validator JSON/text output
  • live host drift validator output for the canonical stack dir

Next action:

  • if drift is repo-owned, fix the repo truth or materialization path in the Loom lane
  • if ingress or identity readback mismatches the stack truth, hand off to the owning repo instead of patching Loom around it

Escalation path:

  • stack/materialization drift -> jhf-loom
  • ingress/TLS/DNS drift -> jhf-openclaw-env
  • auth/session drift -> jhf-heddle

Verify after recovery:

python scripts/validate_runtime_materialization_drift.py --host <live-host> --stack-dir <owner-runtime-stack-dir> --insecure

Shared-Host Pressure / Memory Guard​

Symptoms:

  • excessive swap growth
  • low-idle profile no longer stays in the expected budget corridor

Likely owner:

  • JaddaHelpifyr/jhf-loom

First checks:

  • run the memory guard before any restart decision
  • confirm whether the idle-profile verifier or the guard fired first

Run:

bash scripts/loom-runtime-control.sh memory-guard
python scripts/validate_live_low_idle_runtime_policy.py --insecure --idle-window-seconds 1800 --moderate-traffic-seconds 90

Evidence to collect:

  • memory-guard output
  • low-idle validator output

Next action:

  • if the guard fails closed, treat it as a runtime-capacity incident and follow the reclaim/recovery runbook instead of forcing repeated restarts

Escalation path:

  • Loom runtime capacity issue -> jhf-loom
  • shared host pressure caused by external stack competition -> explicit owner handoff after Loom evidence exists

Verify after recovery:

bash scripts/loom-runtime-control.sh memory-guard

Run This Check​

python scripts/validate_docs_platform_v1_6.py
python scripts/validate_docs_inventory_rollout.py
bash scripts/loom-runtime-control.sh diagnostics
bash scripts/loom-runtime-control.sh readiness

Supporting Deep-Dive Docs​

  • Operations
  • Runbook
  • Deploy and Verify (docs/DEPLOY_VERIFY.md)
  • Shared Host Memory Reclaim (docs/SHARED_HOST_MEMORY_RECLAIM.md)

License: AGPLv3.

Helpifyr: https://helpifyr.com