Skip to main content

Operations

Documentation Map​

Operations

Tool / Contract Summary​

This page describes how jhf-tenter is operated in practice:

  • what the repo owns directly
  • what must be verified on the live host
  • which commands are the canonical start, stop, restart, and verify paths

Business Value​

  • Operators get one place for the verified runtime contract instead of piecing it together from multiple repos.
  • Deployment and validation repos can consume a stable operations baseline.
  • Wiki.js and deep-dive readers can separate contract truth from temporary runtime state.

Current Verified State​

Current host evidence from <internal-runtime-redacted>:

  • openclaw-gateway is live on :18789.
  • jhf-fabric-api is live on :28080.
  • jhf-voice-asterisk-ari is live on :19088.
  • jhf-voice-asterisk-gui is live on :19089.
  • jhf-heddle-keycloak is live on :18090.

Available now​

  • Canonical Asterisk stack source-of-truth docs and compose files.
  • CPU-safe runtime guardrails for shared-host ARI and GUI execution.
  • Repo-local smoke and Fabric self-check commands.
  • Host-near stack verification.
  • Voice runtime bring-up and live-call verification.
  • Package build and verify operations.

Optional / Extended​

  • deployment-executed rollout from the tenter-owned stack artifacts
  • GUI runtime plus SSO attachment
  • optional carrier slice operations when Fabric later publishes an enabled state

Planned / Not in current scope​

  • CI-driven host mutation
  • repo-owned infrastructure provisioning
  • repo-owned secrets rotation

Public Surfaces​

Start / stop / restart surfaces​

Full tenter-owned stack:

  • bash scripts/run-asterisk-stack.sh --ari-env-file <ari.env> --gui-env-file <gui.env> config
  • bash scripts/run-asterisk-stack.sh --ari-env-file <ari.env> --gui-env-file <gui.env> --remove-orphans up
  • bash scripts/run-asterisk-stack.sh --ari-env-file <ari.env> --gui-env-file <gui.env> restart
  • bash scripts/run-asterisk-stack.sh --ari-env-file <ari.env> --gui-env-file <gui.env> down
  • the helper renders repo-owned ARI config templates into .runtime/asterisk-ari-live/generated-config
  • the helper also materializes canonical tenter-owned runtime env copies into .runtime/asterisk-ari-live/ari.env and .runtime/asterisk-gui-live/gui.env

ARI:

  • docker compose -f runtime/asterisk-ari-live/docker-compose.yml --env-file runtime/asterisk-ari-live/ari.env.example up -d
  • docker compose -f runtime/asterisk-ari-live/docker-compose.yml --env-file runtime/asterisk-ari-live/ari.env.example down
  • docker compose -f runtime/asterisk-ari-live/docker-compose.yml --env-file runtime/asterisk-ari-live/ari.env.example restart

GUI:

  • docker compose -f runtime/asterisk-gui-live/docker-compose.yml --env-file runtime/asterisk-gui-live/gui.env.example up -d
  • docker compose -f runtime/asterisk-gui-live/docker-compose.yml --env-file runtime/asterisk-gui-live/gui.env.example down
  • docker compose -f runtime/asterisk-gui-live/docker-compose.yml --env-file runtime/asterisk-gui-live/gui.env.example restart

Verify surfaces​

  • python3 scripts/ci/verify_repo.py
  • bash scripts/fabric-selfcheck.sh
  • python3 scripts/export-fabric-metadata.py --check
  • python3 scripts/ci/verify_runtime_materialization_drift.py
  • python3 scripts/ci/verify_asterisk_stack_source_of_truth.py
  • python3 scripts/ci/verify_cpu_safe_runtime_guardrails.py
  • python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py
  • python3 scripts/ci/verify_realtime_voice_wave3_router.py
  • python3 scripts/ci/verify_realtime_voice_wave4_async_mode.py
  • python3 scripts/ci/verify_realtime_voice_wave5_guarded_speculative.py
  • python3 scripts/ci/verify_realtime_voice_wave6_shadow_mode_cutover.py
  • bash scripts/verify-realtime-voice-v6-acceptance.sh
  • python3 scripts/ci/verify_voice_host_near_bringup.py
  • python3 scripts/ci/verify_voice_live_call.py

Contract Families​

  • runtime stack source
  • voice runtime slices
  • Fabric governance adoption
  • Fabric combinations consumer
  • GUI handoff and operator-surface consumer

Producer-/Consumer-Zuordnung​

  • jhf-tenter owns:
    • stack definition
    • non-secret runtime wiring
    • repo verification
  • jhf-deployment owns:
    • rollout execution
    • host-side automation
  • jhf-heddle owns:
    • GUI authentication and IdP semantics
  • helpifyr-fabric owns:
    • shared contract and combination truth

Compatibility Window​

  • Host ports 19088 and 19089 are static-required.
  • ARI and GUI stack files in this repo are the only canonical stack definitions for tenter-owned Asterisk surfaces.
  • Fabric versions must continue to match the read-only adoption verifier.

Lifecycle Status​

  • Repo operations layer:
    • active
  • Live runtime:
    • live-readback verified
  • CI posture:
    • smoke-only and non-mutating

Readiness / Drift / Monitoring​

Readiness is green when:

  • repo-local checks pass
  • Fabric surfaces are reachable
  • stack source-of-truth verification passes
  • live runtime presence matches the tenter-owned contract

Common drift patterns:

  • ports guessed from nearby services instead of the stack contract
  • Fabric state assumed from docs instead of live readback
  • deployment-local copies drifting from tenter-owned compose files
  • repo-owned env truth present in *.env.example and manifest contracts but missing from the active compose materialization
  • container env and mounted generated config disagreeing with the repo-owned stack contract
  • app /healthz or status readback disagreeing with active container env
  • undocumented host override files under ~/.config/helpifyr/runtime/jhf-tenter/
  • split-host local-audio bridge defaults drifting back to <internal-runtime-redacted>:18180 instead of the canonical LAN runtime at <internal-runtime-redacted>:18180
  • unbounded docker logs -f or repeated restart loops used as ad hoc diagnostics on a shared host

Canonical materialization-drift verifier:

python3 scripts/ci/verify_runtime_materialization_drift.py
python3 scripts/ci/verify_runtime_materialization_drift.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter

CPU-safe runtime guardrails​

Canonical low-pressure rules for the tenter-owned Asterisk stack:

  • default healthcheck interval is 60s
  • diagnostics are bounded:
    • timeout 15s docker logs --since 15m --tail 120 ...
  • restart checks use bounded backoff instead of tight polling
  • post-deploy cleanup must leave no hanging docker logs or docker exec helpers
  • reruns must stay idempotent

Canonical guardrail verifier:

python3 scripts/ci/verify_cpu_safe_runtime_guardrails.py
python3 scripts/ci/verify_cpu_safe_runtime_guardrails.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_cpu_safe_runtime_guardrails.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter --exercise-restart

Deployment / Verify​

Fast path:

python3 scripts/ci/verify_repo.py
bash scripts/fabric-selfcheck.sh
python3 scripts/export-fabric-metadata.py --check
python3 scripts/ci/verify_runtime_materialization_drift.py
python3 scripts/ci/verify_asterisk_stack_source_of_truth.py
python3 scripts/ci/verify_cpu_safe_runtime_guardrails.py
python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py
python3 scripts/ci/verify_realtime_voice_wave3_router.py
python3 scripts/ci/verify_realtime_voice_wave4_async_mode.py
python3 scripts/ci/verify_realtime_voice_wave5_guarded_speculative.py
python3 scripts/ci/verify_realtime_voice_wave6_shadow_mode_cutover.py
bash scripts/verify-realtime-voice-v6-acceptance.sh

Live host path:

python3 scripts/ci/verify_asterisk_stack_source_of_truth.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_runtime_materialization_drift.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_cpu_safe_runtime_guardrails.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py --check-live --host <internal-runtime-redacted>
python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py --check-live --exercise-restart --host <internal-runtime-redacted>
python3 scripts/ci/verify_realtime_voice_wave3_router.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_realtime_voice_wave4_async_mode.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_realtime_voice_wave5_guarded_speculative.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter
python3 scripts/ci/verify_realtime_voice_wave6_shadow_mode_cutover.py --check-live --host <internal-runtime-redacted>
VOICE_V6_VERIFY_LIVE=1 bash scripts/verify-realtime-voice-v6-acceptance.sh
python3 scripts/ci/verify_fabric_contract_adoption.py --fabric-base-url http://<internal-runtime-redacted>:28080
python3 scripts/ci/verify_fabric_combination_profiles.py --fabric-base-url http://<internal-runtime-redacted>:28080
python3 scripts/ci/verify_voice_host_near_bringup.py

Wave-3 realtime bridge router​

The bounded softphone bridge now exposes an explicit Wave-3 router posture:

  • hot agents route through warm-gateway
  • the hot route must prewarm a separated voice_runtime_target_ref; it must not continuously warm the productive main:main conversation session
  • explicit async turns return an accepted turn id plus pollable /turn-status
  • per-session/per-turn coordination replaces the old global bridge lock
  • stale turn completions are quarantined under .runtime/softphone-agent-bridge/shared/late-results

Canonical verifier:

python3 scripts/ci/verify_realtime_voice_wave3_router.py
python3 scripts/ci/verify_realtime_voice_wave3_router.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter

Wave-4 async default and quarantine​

The bounded bridge now also exposes a Wave-4 async default posture for non-hot agents:

  • non-hot agents default to async-bounded
  • async turns must return immediate accepted feedback
  • non-hot async work must not block a later hot turn in the same session
  • stale async completions are quarantined instead of overwriting the active session result

Canonical verifier:

python3 scripts/ci/verify_realtime_voice_wave4_async_mode.py
python3 scripts/ci/verify_realtime_voice_wave4_async_mode.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter

Wave-5 guarded speculative and barge-in​

The bounded bridge now also exposes a Wave-5 guarded speculative posture on the existing /one-turn surface:

  • speculation stays fail-closed until policy risk, confidence, and stable-word guards are all satisfied
  • diverging final transcripts must quarantine the speculative turn instead of publishing its audio
  • barge-in marks the superseded turn terminal with cancel or quarantine semantics from the backend matrix

Canonical verifier:

python3 scripts/ci/verify_realtime_voice_wave5_guarded_speculative.py
python3 scripts/ci/verify_realtime_voice_wave5_guarded_speculative.py --check-live --host <internal-runtime-redacted> --host-checkout /home/administrator/jhf-tenter

Wave-6 shadow-mode cutover and latency evidence​

The bounded bridge now also exposes a Wave-6 cutover-evidence posture:

  • cold, warm, and restart runs must emit one machine-readable evidence report
  • the report must keep warm-lane refs separate from productive conversation refs
  • the report must include bridge contract readback, local audio latency readback, and warm-gateway metrics snapshots
  • external hot-path drift must be classified as blocked_external, not hidden as a generic bridge failure
  • the stack helper must preserve repo-owned warm-lane keys when materializing canonical .runtime/asterisk-ari-live/ari.env, even if stale host override files still carry older values
  • the productive hot main path should use the OpenClaw hook lane plus bounded session readback instead of the slower openclaw agent CLI path when the local warm-gateway lane is live
  • text-only Wave-6 acceptance runs must keep STT bypass explicit; stale STT health samples stay informational while live TTS/playback/end-to-end and per-run hot-turn diagnostics remain fail-closed

Canonical verifier:

python3 scripts/ci/verify_realtime_voice_wave6_shadow_mode_cutover.py
python3 scripts/ci/verify_realtime_voice_wave6_shadow_mode_cutover.py --check-live --host <internal-runtime-redacted>
bash scripts/verify-realtime-voice-v6-acceptance.sh

Softphone bridge restart-health​

The bounded softphone bridge is green only when restart behavior stays aligned with the split-host local-audio contract:

  • the bridge defaults must point at the Windows LAN runtime http://<internal-runtime-redacted>:18180
  • the bridge may not silently fall back to <internal-runtime-redacted>:18180 in the Wave-2 lane
  • after a bounded restart, jhf-voice-softphone-agent-bridge must return to Docker healthy and serve a green /healthz response within the verify budget

Canonical verifier:

python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py
python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py --check-live --host <internal-runtime-redacted>
python3 scripts/ci/verify_softphone_agent_bridge_restart_health.py --check-live --exercise-restart --host <internal-runtime-redacted>

Known Limits​

  • The host-side openclaw status --json wrapper is still an external blocker for parts of the deepest live verification chain.
  • After the 2026-04-25 VM130 restore reroll, the tenter-owned Asterisk/bridge stack is back on repo-canonical origin/main, but the external warm-lane owner still has to materialize the separated voice_runtime_target_ref contract on <internal-runtime-redacted>; host-near LAN TTS to <internal-runtime-redacted>:18180 stays green while warm-lane readback and handoff still depend on owner-side runtime rollout.
  • This repo cannot guarantee that deployment has actually executed the newest stack revision unless host readback confirms it.
  • Windows operator flows still exist, but the current voice and Fabric runtime posture is Linux-host-near first.

Exceptions / Waivers​

  • Optional carrier slices may remain disabled.
  • GUI runtime health should be interpreted through the tenter-owned stack verifier and deployment execution evidence, not a second local health contract.
  • jhf-tenter#87
  • jhf-tenter#88
  • jhf-deployment#170
  • openclaw-environment#30

License​

AGPLv3. Learn more at helpifyr.com.